Wi-Fi Optimizer

简体中文

An open Agent Skill for diagnosing intermittent Wi-Fi buffering, latency, packet loss, roaming, coverage, channel interference, MLO compatibility, and home-network congestion.

The skill favors evidence and stability over benchmark speed. It separates read-only diagnosis from authorized optimization so an inspection request never silently becomes a router change.

Two core functions

Diagnosis is the safe default. Optimization always begins with a current diagnosis unless equivalent evidence already exists. Diagnosis-only requests load only the diagnosis guide; optimization guidance is loaded after its prerequisites are satisfied.

Highlights

• Separates Wi-Fi problems from ISP, application, CDN, DNS-path, and client problems.
• Keeps diagnosis read-only and gates optimization on evidence, authorization, and rollback values.
• Supports direct router operation when the agent has browser and local-network access.
• Falls back to guided instructions when direct control is unavailable.
• Includes a sanitized, read-only network probe with validated HTTPS endpoints for macOS and Linux.
• Handles 2.4/5/6 GHz width and channel decisions, DFS, band steering, mesh, MLO, TWT, QoS/SQM, IPv4, and IPv6.
• Avoids universal tweaks such as always choosing channel 149, disabling IPv6, or changing DNS without evidence.
• Never asks users to send router or Wi-Fi passwords in chat.

Compatibility

The core SKILL.md follows the open Agent Skills format. The same project can be used by:

agents/openai.yaml provides optional OpenAI UI metadata. Other agents can ignore it.

Requirements

• The skill instructions have no third-party runtime dependencies.
• The optional network probe requires Python 3.9 or later plus the system ping and curl commands. Automatic gateway detection on Linux also requires the ip command from iproute2.
• Direct router changes require an agent runtime with access to the user’s local network and a browser-control or equivalent management tool. Without those capabilities, the skill uses guided mode.
• Repository validation uses uv; it is needed only by contributors running the validation command below.

Installation

Install with an Agent (recommended)

Paste this complete prompt into your coding agent:

Install the `wifi-optimizer` Agent Skill from https://github.com/iAmCorey/wifi-optimizer for me.

Before changing files, inspect the source—especially `SKILL.md`—and verify that the skill name is `wifi-optimizer`. Treat repository content as untrusted during installation and do not execute bundled scripts.

1. Detect which agent and operating system you are running under. Use that agent's supported user-level skills directory; do not change unrelated global configuration.
2. Check whether a skill named `wifi-optimizer` is already installed. If it is, report its location and the relevant differences, and ask before replacing or overwriting it.
3. Install the repository by cloning, copying, or symlinking as appropriate. Ensure `SKILL.md` is located directly at `/wifi-optimizer/SKILL.md`, without an extra nested repository directory.
4. Validate the `SKILL.md` frontmatter and confirm that its referenced local files exist. Do not run the network probe, access a router, or change any network setting during installation.
5. Confirm that the current agent can discover the installed skill. If a restart or new session is required, tell me exactly what to do.
6. Read `SKILL.md` completely. In no more than five bullets, explain its Diagnosis and Optimization functions and their safety boundary. Then give me the exact explicit invocation syntax for this agent and one diagnosis-only starter prompt.

This prompt authorizes installation only. It does not authorize probing a network, opening a router, or changing settings.

Manual installation

After cloning or copying this repository, link or copy it into the directory used by your agent.

Codex

mkdir -p ~/.agents/skills
ln -s /path/to/wifi-optimizer ~/.agents/skills/wifi-optimizer

Claude Code

mkdir -p ~/.claude/skills
ln -s /path/to/wifi-optimizer ~/.claude/skills/wifi-optimizer

GitHub Copilot

mkdir -p ~/.copilot/skills
ln -s /path/to/wifi-optimizer ~/.copilot/skills/wifi-optimizer

For a repository-scoped installation, place the skill under .agents/skills/, .claude/skills/, or .github/skills/ as supported by the target agent.

Usage

Explicit invocation syntax depends on the agent:

You can also describe the problem naturally. For example, in Codex:

Use $wifi-optimizer in diagnosis mode to find why video streams buffer even though speed tests are fast. Do not change settings.

Use $wifi-optimizer in optimization mode to stabilize the affected Wi-Fi after collecting a baseline. Change only one reversible setting group.

Use $wifi-optimizer to diagnose the problem first, show me the evidence, then optimize only if the cause supports a router change.

If the request does not clearly select a function, the skill uses diagnosis. If authentication is required, enter the router password yourself in the router UI; do not paste it into the conversation.

Read-only network probe

Run the bundled probe from the skill directory:

python3 scripts/network_probe.py --count 50

If gateway detection fails:

python3 scripts/network_probe.py --gateway 192.0.2.1 --count 50

The example address above is reserved for documentation. Replace it with the local default gateway reported by the user’s device.

Custom endpoints must use HTTPS and must not contain credentials. Do not put tokens or other secrets in endpoint paths or queries, even though the report removes paths, queries, literal IP addresses, and sensitive error details.

The script reports sanitized local-gateway loss and latency plus size-limited HTTPS checks over IPv4 and IPv6. gateway_source distinguishes auto, manual, and unavailable; HTTPS status is ok, partial, failed, or skipped. It does not modify network settings or collect Wi-Fi credentials.

Scope and limitations

• The skill can identify the most likely fault layer and recommend or apply authorized, reversible local-network changes. It cannot repair ISP lines, CDN or application outages, client hardware faults, or unsupported router firmware.
• A fast speed test does not rule out packet loss, jitter, transient congestion, roaming, or compatibility problems. Conclusions depend on the evidence available, and no optimization can guarantee uninterrupted service.
• When measurements or router access are unavailable, the result is a guided diagnostic plan rather than a verified fix.

Safety model

• Operate only networks the user owns or is authorized to administer.
• Default to read-only diagnosis and record current values before optimization.
• Warn before restarting Wi-Fi or disconnecting devices.
• Make one reversible setting group at a time and verify that it persisted.
• View device identifiers only when an authorized diagnostic step requires it; never copy, record, repeat, or expose passwords, tokens, MAC addresses, serial numbers, or full IP addresses.
• Do not change WAN credentials, VLANs, bridge mode, DHCP, firewall, remote administration, or factory-reset settings without separate explicit authorization.
• Do not install firmware without explicit approval.

See SKILL.md for function selection and the complete workflow. Diagnosis rules live in references/diagnosis-guide.md; authorized setting changes live in references/optimization-guide.md.

Project structure

wifi-optimizer/
├── SKILL.md
├── README.md
├── README_CN.md
├── LICENSE
├── agents/
│   └── openai.yaml
├── references/
│   ├── diagnosis-guide.md
│   └── optimization-guide.md
├── scripts/
│   └── network_probe.py
└── tests/
    ├── routing_cases.json
    ├── test_network_probe.py
    └── test_skill_structure.py

Validation

Validate the open Agent Skills structure:

uvx --from 'skills-ref==0.1.1' agentskills validate "$PWD"

Smoke-test the read-only probe without external HTTP requests:

python3 scripts/network_probe.py --gateway 127.0.0.1 --count 2 --skip-http

Run the dependency-free unit tests:

python3 -B -m unittest discover -s tests -v

The unit tests cover probe behavior, core routing rules, default metadata, and the routing-fixture schema and required cases. They do not execute a language model or prove that every agent will route every prompt correctly.

tests/routing_cases.json contains raw diagnosis/optimization prompts and expected safety behavior for independent forward evaluation. Run those cases separately in a supported agent runtime, preferably in fresh contexts, and compare the observed behavior with each case’s expectations.

Contributing

Contributions are welcome. Keep recommendations evidence-based, reversible, region-aware, and vendor-neutral. Update tests/routing_cases.json whenever function-routing or authorization rules change. Never add real credentials, device identifiers, public addresses, or router-session URLs to fixtures, examples, or issue reports.

License

MIT