How to use the Connectivity Triage agent skill for macOS

What the skill makes the agent do

When a Mac has an active connectivity problem, the agent follows a fixed sequence of read-only checks. These include ping, DNS queries, traceroute, curl timing and similar built-in tools. It works from the symptom toward the narrowest check that can tell the possible causes apart, and it stops early once the evidence is clear enough.

The skill separates what it actually observed from what it infers and what remains unknown. It then names the most likely fault-domain category without changing any settings. The four domains it isolates are local-LAN, DNS, upstream path, and remote service or application.

• Observed: directly supported by command output or user-provided evidence.
• Inferred: the most likely explanation after correlating observations.
• Unknown: not established by the current evidence.

How to install the connectivity-triage skill

Download the ZIP for the skill from this page. Unzip it into one of two locations: ~/.claude/skills/ to make the skill available across your projects, or the .claude/skills/ folder inside a specific project to make it available only there.

If you use the Claude apps instead of files on disk, open Settings, go to Capabilities, then Skills, and upload the ZIP there.

• Personal install: unzip into ~/.claude/skills/
• Project install: unzip into the project's .claude/skills/ folder
• Claude apps: Settings → Capabilities → Skills, then upload the ZIP

How to trigger the skill with natural requests

You do not need to type a special command. Describe the symptom in ordinary words and name the affected hostname or URL. The skill's description covers API or MCP timeouts and disconnects, DNS lookups that fail or vary, and video calls or other interactive traffic with packet loss or latency.

Include the exact hostname or URL the application uses. The source says that testing an unrelated public site can show general connectivity but cannot prove the affected service is healthy.

• "My API calls to api.example.com time out on this Mac. Help me find out where the failure is." (replace the hostname with your own)
• "DNS lookups for our internal site are failing on and off. Triage it."
• "Video calls on my Mac are stuttering. Check whether the network is the cause."

What the checks look like

The agent chooses which checks to run based on the symptom. It does not run every probe. The commands below are the ones named in the skill, shown with placeholders for your own values.

Use scutil --dns to inspect resolver configuration and dig to test lookup behaviour. Use ping and a numeric traceroute for reachability and path visibility. Use nettop to see whether a specific process is opening connections, and curl to time the phases of an HTTP(S) request. networkQuality gives a broad responsiveness signal when it is available.

• Resolver state: scutil --dns
• Name lookup: dig +time=2 +tries=1 <hostname>
• Reachability: ping -c 5 <destination>
• Path: traceroute -n -q 1 -m 20 <destination>
• Process activity: nettop -n -L 3 -p <process-name-or-pid>

How to read the result

Every result has four parts: the symptom, the observations, the fault-domain assessment, and the next safest check. The assessment names exactly one primary category: local-link/LAN, DNS, upstream-path, remote-service/application, or inconclusive. It also gives a confidence level of low, medium or high, which reflects how good the evidence is, not how severe the problem is.

Expect inconclusive when probes disagree. The skill is built to prefer that answer over a confident guess. A failed ping can come from ICMP filtering, and a silent traceroute hop does not prove that hop is dropping packets.

• Symptom: the failure and the affected destination or application
• Observations: relevant measurements, including any evidence that was unavailable or blocked
• Fault-domain assessment: category, confidence and a short explanation
• Next safest check: one diagnostic action that reduces uncertainty the most

What you need before you start

The skill is for macOS only. It relies on the standard networking tools scutil, dig, ping, traceroute, nettop and curl. networkQuality is optional, and the skill continues without it. You also need the affected hostname or URL from the user. The skill runs scripts and uses the network.

• macOS with scutil, dig, ping, traceroute, nettop, curl
• networkQuality (optional)
• The affected hostname or URL
• Licence: MIT

Safety notes: scripts and network use

This skill runs scripts and sends network traffic. During diagnosis it is designed not to change anything. It will not alter interface state, restart network services, edit resolver configuration, flush DNS caches, change firewall or VPN settings, install packages, or send state-changing requests to remote services. Probes are bounded, so it does not run indefinite or high-volume tests.

The skill does not fix problems. If you want a fix, you have to ask for remediation separately, and the skill will recommend a diagnostic step rather than a configuration change by default.

• Keep probes bounded: the skill uses short ping counts and time limits on curl.
• VPNs, captive portals, proxies, scoped DNS and endpoint security tools can all limit what the evidence shows.

Tips for better results

Give the skill the exact hostname or URL the application uses, and say when the failure started and whether it is continuous or intermittent. For a process-specific problem, name the process or its PID so the nettop check can target it.

If the first result is inconclusive, run the next safest check it recommends and then ask the agent to reassess with the new evidence. Keep the output, because the observations section is what lets you or a colleague follow the reasoning later.

• Name the process or PID for app-specific problems.
• Tell the agent whether the failure is continuous or intermittent.
• Reassess after each diagnostic step instead of trying random fixes.