wifi-audit — a Claude Code skill that audits and optimizes a home/mesh Wi-Fi network from macOS using real networking tools (signal, channel congestion, latency, LAN inventory, topology) and returns a ranked, data-backed tuning plan. macOS only.

collect.sh

#!/usr/bin/env bash
# wifi-audit collector — read-only macOS Wi-Fi + LAN diagnostics. No sudo needed.
# Usage: bash collect.sh [wifi-interface]   (default en0)
set -u
IFACE="${1:-en0}"
hr(){ printf '\n==== %s ====\n' "$1"; }

hr "HOST"
sysctl -n hw.model 2>/dev/null
sw_vers 2>/dev/null | tr '\n' ' '; echo

hr "WIFI LINK (signal, channel, PHY, rate, security, country)"
system_profiler SPAirPortDataType 2>/dev/null | sed -n '/Current Network Information/,/Other Local Wi-Fi Networks/p' \
  | grep -E "PHY Mode|Channel|Security|Signal|Transmit Rate|MCS|Country Code"
ipconfig getsummary "$IFACE" 2>/dev/null | grep -E "SSID|BSSID|Security|LinkStatus|Rate"

hr "NEIGHBOR CHANNELS (5GHz/2.4GHz congestion)"
system_profiler SPAirPortDataType 2>/dev/null | awk '/Other Local Wi-Fi Networks/,0' \
  | grep -E "PHY Mode:|Channel:|Signal" | paste - - - | sed 's/  */ /g'

hr "IP / GATEWAY / DNS"
echo "ip: $(ipconfig getifaddr "$IFACE" 2>/dev/null)"
GW=$(netstat -rn 2>/dev/null | awk '$1=="default" && $NF ~ /^en/ {print $2; exit}')
echo "gateway: ${GW:-unknown}"
scutil --dns 2>/dev/null | awk '/nameserver\[0\]/{print "dns: "$3}' | sort -u

hr "ETHERNET ADAPTERS (wired option?)"
for i in $(networksetup -listallhardwareports 2>/dev/null | awk '/Device:/{print $2}'); do
  st=$(ifconfig "$i" 2>/dev/null | awk '/status:/{print $2}')
  [ -n "$st" ] && echo "$i: $st"
done

hr "LATENCY / LOSS / JITTER"
if [ -n "${GW:-}" ]; then echo "-- gateway $GW --"; ping -c 15 -q "$GW" 2>/dev/null | tail -2; fi
echo "-- internet 1.1.1.1 --"; ping -c 15 -q 1.1.1.1 2>/dev/null | tail -2

hr "DNS SPEED (router vs 1.1.1.1)"
for s in "${GW:-192.168.1.1}" 1.1.1.1; do
  printf "%s: " "$s"
  { /usr/bin/time -p dig +tries=1 +time=2 @"$s" apple.com >/dev/null; } 2>&1 | awk '/real/{print $2"s"}'
done

hr "TOPOLOGY (>1 private 10./192.168./172.16-31 hop = double-NAT)"
traceroute -n -m 4 -w 1 -q 1 1.1.1.1 2>/dev/null

hr "LAN DEVICES (ip / mac / name / private-MAC=Apple)"
SUB=$(echo "${GW:-192.168.1.1}" | sed 's/\.[0-9]*$//')
if command -v fping >/dev/null 2>&1; then
  fping -a -q -g "$SUB.0/24" >/dev/null 2>&1
else
  for i in $(seq 1 254); do ping -c1 -W 300 "$SUB.$i" >/dev/null 2>&1 & done; wait
fi
arp -an 2>/dev/null | grep "$SUB" | grep -vE "incomplete|ff:ff:ff:ff:ff:ff" | while read -r _ ip _ mac _; do
  ip=${ip//[()]/}
  o1=$(printf '%d' "0x${mac%%:*}" 2>/dev/null || echo 0)
  priv=""; [ $(( o1 & 2 )) -ne 0 ] && priv="[private/randomized MAC]"
  name=$(dig +short +time=1 +tries=1 -x "$ip" @"${GW:-192.168.1.1}" 2>/dev/null | head -1)
  printf "%-15s %-17s %-22s %s\n" "$ip" "$mac" "${name:-?}" "$priv"
done

hr "GATEWAY FINGERPRINT (router vendor)"
curl -skI --max-time 4 "https://${GW:-192.168.1.1}" 2>/dev/null | grep -iE "server|www-authenticate"
curl -sk --max-time 4 "https://${GW:-192.168.1.1}" 2>/dev/null \
  | grep -oiE "<title>[^<]*</title>|zyxel|tp-link|netgear|fritz|asus|ubiquiti|technicolor|sagemcom|huawei" | sort -u | head -5

hr "NEXT"
echo "Look up unknown MAC vendors (first 3 octets) at https://api.macvendors.com/<oui>"

SKILL.md

name

wifi-audit

description

Audit and optimize a home or mesh Wi-Fi network from a macOS machine. Use when the user wants to analyze, troubleshoot, speed up, or "make better/faster/stronger" their Wi-Fi, mesh, router, or home internet. It gathers REAL data with networking tools (signal, channel congestion, latency/loss/jitter, LAN device inventory, topology, router vendor), then returns a concise, ranked, data-backed tuning plan plus exactly where to change each setting. macOS only.

Wi-Fi Audit

Measure first, then recommend. Never give generic Wi-Fi advice from memory — run the collector, read the numbers, and tie every recommendation to a measured value.

1. Collect real data

Run the read-only collector (no sudo):

bash ~/.claude/skills/wifi-audit/scripts/collect.sh

Pass a non-default Wi-Fi interface as arg 1 if en0 is not Wi-Fi (check networksetup -listallhardwareports). It takes ~40s (two 15-count pings + a /24 sweep).

2. Look up unknown device vendors

For each LAN MAC that is NOT marked [private/randomized MAC], look up its OUI (first 3 octets) with WebFetch on https://api.macvendors.com/<oui>. Private/randomized MACs are Apple devices (iPhone/Mac with "Private Wi-Fi Address" on) — no lookup needed.

3. Interpret with these thresholds

• Signal (RSSI): −30..−50 excellent · −50..−60 good · −60..−67 ok · −67..−75 weak (move a node closer / fix roaming) · <−75 poor.
• SNR (signal − noise): >30 great · 20–30 ok · <20 poor.
• Link rate vs streams (5GHz, 80MHz, Wi-Fi 5): ~433 = 1 stream · ~866 = 2 streams. A strong signal but only ~half the 2-stream rate = stuck at 1 stream → interference or placement.
• Real throughput ≈ 40–55% of link rate. Compare to the WAN speed to find the real bottleneck. If Wi-Fi link caps below the fiber/cable speed, the client or RF is the limit, not the ISP.
• Latency/loss: any loss, or gateway ping jitter (stddev) >5 ms, points to RF contention. Internet path is healthy at <20 ms and 0% loss.
• Channel congestion: if your channel is shared by a neighbor stronger than ~−70 dBm, that is airtime contention → move channel.
• Double-NAT: more than one private-range hop (10., 192.168., 172.16–31.) in the traceroute = double NAT → put one router in bridge mode.
• Client Wi-Fi generation by Mac model: Intel Macs (MacBookPro16,* and earlier) = Wi-Fi 5 (ac). M1/M2 = Wi-Fi 6. M3/M4+ = Wi-Fi 6E. A dual-band AP (no 6GHz radio) makes 6E/7's 6GHz irrelevant — all clients share 5GHz.

4. Channel planning

• 2.4GHz: only 1, 6, 11 (20MHz). Pick the one with no strong neighbor.
• 5GHz width: 80MHz is the sweet spot. Use 160MHz only if the WAN clearly exceeds what 80MHz delivers and DFS radar drops are acceptable.
• 5GHz channels by region (read Country Code from the scan):
  • EU/NL: 36–64 (UNII-1/2A) and 100–140 (DFS). 149–165 is usually NOT allowed.
  • US: adds 149–165 (UNII-3).
• Assign each AP a different channel; prefer empty DFS (100–140) to escape neighbor-packed low channels. Apple/Roku handle DFS fine; some cheap IoT do not.

5. Output format (keep it concise)

1. Bottleneck — one line naming the single limiting factor.
2. Evidence — max 5 measured bullets (real numbers from the scan).
3. Do now — numbered, ranked, max 5. Each item states the fix AND where to change it (see settings map below). Biggest measured win first.
4. Offer click-by-click for the hardest step.

Honor the user's style: lead with the action, rank everything, do not pad.

Settings access map

Name the exact path for the user's gear. Common cases:

• TP-Link Omada (EAP APs — app or controller):
  • Channel / width / Tx power: Devices → tap the AP → Config → Radio (2.4/5GHz).
  • Minimum RSSI (force roaming): Devices → AP → Config → Advanced (or Roaming).
  • WPA3, Fast Roaming, Band Steering: Settings → Wireless Networks → SSID → Edit → Security / Advanced.
  • New IoT/guest SSID: Settings → Wireless Networks → Create.
• Zyxel ISP router (http://192.168.1.1, password on the sticker):
  • Turn off built-in Wi-Fi: Network Setting → Wireless → General → disable (both bands).
  • Bridge mode: Network Setting → Broadband or Operation Mode (may be ISP-locked; if so, just disable Wi-Fi).
• eero / Google Nest (app only): limited manual control — focus on placement, wired backhaul, and letting the app auto-pick channels.
• Netgear Orbi / ASUS (web admin): full manual channel, band, backhaul, WPA3.

Always-true wins (state only if the data supports them)

1. Wire any stationary device and the mesh backhaul when a cable is possible.
2. One SSID across all nodes + band steering + fast roaming, so clients pick the best AP.
3. WPA2/WPA3-mixed with PMF.
4. Put IoT and phone hotspots on a separate 2.4GHz SSID.