Network optimizer skill

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:

1. Do not run destructive resets such as deleting services, network locations, routes, VPN profiles, firewall rules, or full winsock/network resets.
2. Do not use sudo or Administrator PowerShell until the user has seen the risk and approved the action.
3. Do not change DNS, service order, interface metrics, qdisc, congestion control, MTU, VPN/proxy state, or network caches without approval.
4. 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.
5. Prefer reversible operations and record original values before applying changes.
6. 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:

1. Identify OS and context:
   • Unix-like: uname -s
   • Windows: $PSVersionTable.PSVersion; Get-CimInstance Win32_OperatingSystem
2. 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
3. Read SUMMARY.md and the relevant raw files.
4. 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.
5. If Linux and the user asked for BBR/FQ or server speed tuning, run: skills/network-optimizer-skill/scripts/linux-bbr-fq.sh diagnose
6. Propose only minimal safe changes supported by data and ask before any privileged or route-affecting change.
7. Apply approved changes.
8. Run the after audit.
9. Compare: python3 skills/network-optimizer-skill/scripts/compare-network-runs.py <before-dir> <after-dir>
10. 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:

1. Run skills/network-optimizer-skill/scripts/linux-bbr-fq.sh diagnose.
2. Show the user the planned mode:
   • skills/network-optimizer-skill/scripts/linux-bbr-fq.sh plan bbr
   • skills/network-optimizer-skill/scripts/linux-bbr-fq.sh plan bbr-fq
3. After approval, run the exact apply command with root:
   • sudo skills/network-optimizer-skill/scripts/linux-bbr-fq.sh apply bbr
   • sudo skills/network-optimizer-skill/scripts/linux-bbr-fq.sh apply bbr-fq
4. Keep the backup path printed by the script.
5. Re-test.
6. 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.