# Wifi Debug

> 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/.

- Skill: `dennisonbertram/wifi-debug` (Agent Skill)
- Install (CLI): `npx skillmds@latest add dennisonbertram/wifi-debug`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dennisonbertram/wifi-debug/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: dennisonbertram (https://skillmd.com/u/dennisonbertram)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/dennisonbertram/wifi-debug

---


# 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:

1. **`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`.
2. **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.
3. **`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.