| name | wifi-debug |
| description | This skill should be used when the user asks to "debug wifi", "wifi not working", "check wifi", "why is wifi slow", "wifi signal", or mentions SSID, RSSI, channel, noise, or AirPort. Collects wifi state on macOS and writes a JSON result to ~/.mac-guardian/data/. |
wifi-debug
Reports on the active wifi association: SSID, RSSI, channel, noise, Tx rate, BSSID, surrounding networks, and recent disconnect events.
When to invoke
Trigger on phrases like: "debug wifi", "wifi not working", "check wifi", "why is wifi slow", "wifi signal".
Data sources and fallbacks
macOS Sonoma and later deprecate airport. Use a layered approach:
wdutil info — authoritative on newer macOS. Non-elevated output is usually redacted but still includes SSID, channel, and RSSI on many systems. Invoke without sudo: wdutil info 2>/dev/null. Do not call sudo.- Legacy
airport — /System/Library/PrivateFrameworks/Apple80211.framework/Versions/Current/Resources/airport -I. If the binary exists and returns output, prefer it for RSSI / noise / Tx rate numbers.
networksetup — networksetup -getairportnetwork en0 for SSID, networksetup -getinfo "Wi-Fi" for MAC / IP.
If none yield data, emit severity info, summary "Wi-Fi interface off or unavailable."
What to extract
- SSID (string)
- BSSID (string, may be redacted without location permissions — record as "redacted" then)
- Channel (integer + band, e.g.
36 (5GHz))
- RSSI dBm — integer. Severity mapping:
- ≥ −60:
ok
- −60 to −70:
info
- −70 to −80:
warn
- < −80:
critical
- Noise dBm — integer.
warn if > −80.
- Tx rate — Mbps.
info if < 72, warn if < 24.
- Security type —
ok if WPA2/WPA3, warn if WEP or Open.
- MCS index (if available, raw only).
Surrounding networks
If on a legacy macOS where airport -s works, include a count of discovered networks plus the strongest 10 in raw. On Sonoma+, skip with an info finding "airport -s no longer available."
Recent wifi events
log show --style compact --last 1h --predicate 'subsystem == "com.apple.wifi"' 2>/dev/null | tail -60. Skip gracefully if log is unavailable or produces no output. Do not pipe directly into the user's terminal; store the tail in the raw.log_tail field (truncated to ~4 KB).
Output contract
Standard envelope. Write to ~/.mac-guardian/data/wifi-debug-<ISOdate>.json.
Top-level severity = max of RSSI, noise, Tx rate, security severities. Summary example: "SSID HomeNet5G, RSSI −58 dBm, 867 Mbps (ok)."
Handoff
- On direct invocation:
bash ${CLAUDE_PLUGIN_ROOT}/scripts/render-single.sh wifi-debug.
- When invoked by
daily-health-report, return JSON path only.
Safety
- Never run
sudo wdutil info or similar. Report truthfully when detail is redacted.
- Read-only. Do not join / leave / change networks.
