| name | network-diagnostics |
| description | This skill should be used when the user asks to "debug my network", "internet is slow", "check connectivity", "why is my internet bad", "diagnose network", or mentions DNS, packet loss, or VPN issues. Performs read-only network diagnostics on macOS and writes a JSON result to ~/.mac-guardian/data/. |
network-diagnostics
Checks reachability, DNS, active interfaces, VPN state, and listening ports on a macOS machine.
When to invoke
Trigger on phrases like: "debug my network", "internet is slow", "check connectivity", "why is my internet bad", "diagnose network".
What to check
1. Default route — route -n get default 2>/dev/null. If no route, severity critical, summary "No default route — likely offline."
2. Latency and loss — ping -c 5 -t 5 1.1.1.1 and ping -c 5 -t 5 8.8.8.8. Parse the summary line for packet loss and round-trip.
- 0% loss, avg <50 ms:
ok.
- <10% loss or avg 50–200 ms:
info.
- 10–25% loss or avg 200–500 ms:
warn.
- ≥25% loss or avg ≥500 ms:
critical.
Skip gracefully if ping is blocked (record info).
3. DNS resolution — dig +short +time=3 +tries=1 google.com @1.1.1.1 and dig +short +time=3 +tries=1 apple.com. Empty result from either = warn. Missing dig (command -v dig) → fall back to nslookup or host; if none available record info.
4. Configured resolvers — scutil --dns | awk '/nameserver/ {print $NF}' | sort -u. List in raw.
5. Active hardware ports — networksetup -listallhardwareports. Record names and MAC addresses in raw (no severity).
6. Interfaces with IPv4 — ifconfig -a | awk '/^[a-z]/ {iface=$1} /inet /{print iface, $2}'. List in raw.
7. VPN state — detect presence of utun or ppp interfaces with an inet address. Any present = info "VPN-like interface active: …".
8. Listening ports (owned by this user) — lsof -iTCP -sTCP:LISTEN -P -n 2>/dev/null | awk 'NR==1 || $3 == ENVIRON["USER"]'. Summarise top 10 (command + port) in raw; no severity unless a well-known-but-unexpected port is open (22, 23, 3389, 5900) → info.
9. Established connections — lsof -iTCP -sTCP:ESTABLISHED -P -n 2>/dev/null | awk 'NR>1 {print $1, $9}' | sort -u | head -40. Record in raw.
10. Traceroute (optional, slow) — only run if latency check passed: traceroute -n -w 2 -q 1 -m 8 1.1.1.1. Include hop list in raw. Skip on timeout; do not spend more than ~15 seconds here.
Output contract
Standard envelope. Write to ~/.mac-guardian/data/network-diagnostics-<ISOdate>.json.
Set top-level severity to the worst finding severity. Summary should name the dominant problem ("22% packet loss to 1.1.1.1; DNS OK") or confirm "Network OK — 0% loss, 18 ms avg, DNS resolving."
Handoff
- On direct invocation:
bash ${CLAUDE_PLUGIN_ROOT}/scripts/render-single.sh network-diagnostics.
- When invoked by
daily-health-report, return the JSON path only.
Safety
- Read-only. Do not flush DNS, restart interfaces, or toggle VPN.
- Guard every external tool with
command -v and record "tool not available" as a finding when missing.
