| name | network-optimizer-skill |
| description | Diagnose and safely optimize network speed and stability across macOS, Linux, and Windows. Use when a user asks to improve Wi-Fi/Ethernet speed, DNS latency, packet loss, proxy/VPN/TUN routing, route priority, MTU, background bandwidth, or Linux BBR/FQ TCP tuning without destructive resets. |
| license | MIT |
| metadata | {"version":"0.2.0","author":"6Kmfi6HP","compatibility":"macOS, Linux, and Windows diagnostics. Linux-only BBR/FQ tuning with explicit approval and root privileges."} |
Network Optimizer Skill
Overview
Use this skill to improve a computer or server network path without jumping straight to resets. The workflow is conservative: diagnose first, make the smallest reversible change that the evidence supports, then re-test and compare.
Supported operating systems:
- macOS:
networkQuality, scutil, networksetup, route, dig, ping, ifconfig, nettop, and airport when available.
- Linux:
ip, ss, tc, sysctl, resolvectl, nmcli, iw, dig, ping, and ethtool when available.
- Windows: PowerShell
Get-NetAdapter, Get-NetRoute, Get-DnsClientServerAddress, Resolve-DnsName, Test-NetConnection, Get-NetIPConfiguration, and netsh.
Linux BBR/FQ tuning is Linux-only. Do not propose BBR/FQ changes on macOS or Windows.
Safety Contract
Follow these rules before any network-changing command:
- Do not run destructive resets such as deleting services, network locations, routes, VPN profiles, firewall rules, or full winsock/network resets.
- Do not use
sudo or Administrator PowerShell until the user has seen the risk and approved the action.
- Do not change DNS, service order, interface metrics, qdisc, congestion control, MTU, VPN/proxy state, or network caches without approval.
- If the session is SSH, RDP, remote desktop, cloud shell, or routed through VPN/Tailscale/WireGuard/Shadowrocket/Stash/Clash/Surge, warn that changes can disconnect the session.
- Prefer reversible operations and record original values before applying changes.
- When command output may be large, cap it:
COMMAND 2>&1 | head -c 4000.
Fast Path
If the user asks to optimize the current machine:
- Identify OS and context:
- Unix-like:
uname -s
- Windows:
$PSVersionTable.PSVersion; Get-CimInstance Win32_OperatingSystem
- Run a before audit:
- macOS/Linux:
skills/network-optimizer-skill/scripts/network-audit.sh before
- Windows:
powershell -ExecutionPolicy Bypass -File skills/network-optimizer-skill/scripts/windows-network-audit.ps1 -Phase before
- Read
SUMMARY.md and the relevant raw files.
- Classify the likely bottleneck: local link, Wi-Fi RF, gateway, WAN/ISP, DNS, proxy/VPN/TUN, MTU, host TCP settings, service/interface priority, or background traffic.
- If Linux and the user asked for BBR/FQ or server speed tuning, run:
skills/network-optimizer-skill/scripts/linux-bbr-fq.sh diagnose
- Propose only minimal safe changes supported by data and ask before any privileged or route-affecting change.
- Apply approved changes.
- Run the after audit.
- Compare:
python3 skills/network-optimizer-skill/scripts/compare-network-runs.py <before-dir> <after-dir>
- Report the top 3 findings, changes made, improvements/regressions, and remaining manual recommendations.
If bundled scripts are unavailable, use the cross-platform procedure.
Required Diagnostics
Always collect a before baseline before changing anything:
- Throughput or responsiveness when a platform tool exists: macOS
networkQuality; Linux iperf3 only if a known endpoint exists; Windows Test-NetConnection for reachability and routing rather than internet speed.
- DNS query timing against current resolvers and public candidates.
- Ping to the default router/gateway.
- Ping to public DNS addresses such as
1.1.1.1 and 8.8.8.8.
- Default route, interface priority/metric, DNS configuration, proxy configuration, and VPN/tunnel state.
- Wi-Fi/Ethernet quality: link speed, RSSI/noise/channel where available, duplex, MTU, error/drop counters.
- Packet loss and latency.
- High-traffic or route-controlling background processes.
- Linux only: current/available TCP congestion controls,
net.core.default_qdisc, qdisc state, kernel version, and tcp_bbr module state.
Evidence Interpretation
Use this triage map:
- Gateway ping bad: likely Wi-Fi/RF, cable/NIC, local switch/router, duplex, or LAN congestion.
- Gateway ping good but public ping bad: likely ISP/WAN, VPN route, MTU, upstream congestion, or packet shaping.
- Public ping good but DNS slow: DNS resolver choice, local DNS proxy, VPN DNS, captive/enterprise resolver, or cache issue.
- Tunnel owns the default route: separate tunnel performance from raw WAN performance.
- Wi-Fi has weak RSSI, poor SNR, low Tx rate, or crowded 2.4 GHz: prefer RF fixes before OS tuning.
- Linux TCP throughput is poor on high-BDP or variable links and BBR is available but not selected: consider BBR, with
fq as a measured optional pairing for servers.
- Existing qdisc is
fq_codel or cake on a router: do not blindly replace it with fq; these qdiscs may be intentionally managing bufferbloat.
Linux BBR/FQ Rules
Use the Linux BBR/FQ reference before applying this branch.
BBR modes:
bbr: set net.ipv4.tcp_congestion_control=bbr.bbr-fq: set net.ipv4.tcp_congestion_control=bbr and net.core.default_qdisc=fq.
Only propose bbr or bbr-fq when all are true:
- OS is Linux.
- The host has root access available.
- Kernel exposes or can load
tcp_bbr.
- Current workload is TCP-heavy enough that congestion-control tuning is relevant.
- User understands that fairness/latency can change and wants to proceed.
Do not promise universal speed improvement. BBR can help many high-latency, lossy, or high-BDP TCP paths, but it can also interact poorly with some queues, fairness expectations, or non-TCP workloads.
Safe apply path:
- Run
skills/network-optimizer-skill/scripts/linux-bbr-fq.sh diagnose.
- Show the user the planned mode:
skills/network-optimizer-skill/scripts/linux-bbr-fq.sh plan bbrskills/network-optimizer-skill/scripts/linux-bbr-fq.sh plan bbr-fq
- After approval, run the exact apply command with root:
sudo skills/network-optimizer-skill/scripts/linux-bbr-fq.sh apply bbrsudo skills/network-optimizer-skill/scripts/linux-bbr-fq.sh apply bbr-fq
- Keep the backup path printed by the script.
- Re-test.
- If worse, restore with:
sudo skills/network-optimizer-skill/scripts/linux-bbr-fq.sh restore <backup-file>
The helper does not silently run tc qdisc replace dev IFACE root fq because live qdisc replacement can disrupt traffic and multi-queue devices often use mq as root. If immediate per-interface qdisc replacement is desired, present it as a separate advanced operation.
Allowed Low-Risk Fixes
Only apply these after explaining the change and getting approval:
- Put the actively used Wi-Fi/Ethernet interface first in macOS service order, Linux route metric, or Windows interface metric.
- Disable clearly unused pseudo/legacy services, but never delete their configuration.
- Set DNS servers only after measured DNS latency supports the change. Record original DNS first.
- Flush DNS/mDNS cache after DNS changes or cache suspicion.
- Ask the user to pause or quit bandwidth-heavy apps; do not kill important apps without explicit approval.
- Linux only: apply BBR or BBR/FQ through the managed sysctl file and backup workflow.
Never claim the network is fixed until the after audit has been run and compared with before.
Final Report Shape
End with:
- A before/after table for available metrics: throughput/responsiveness, gateway loss/latency, public loss/latency, DNS timing, and Linux TCP/qdisc state when relevant.
- The 3 main problems found, ranked by confidence and impact.
- Changes made, including exact original values and backup paths.
- Items not fixed automatically and the recommended manual next step.
- Residual risk, especially VPN/proxy/remote-session uncertainty and BBR/FQ fairness/latency tradeoffs.
