debugging-network-issues
Investigates network, streaming and protocol failures with falsification-first layered experiments, the general fallback for unknown root causes.
Install / Use
npx skills add daymade/claude-code-skills --skill debugging-network-issuesInstalls into whichever agent you are using.
SKILL.md
Installable skill definition
Quality Score
Category
Development & EngineeringSupported Platforms
Tags
Our assessment of debugging-network-issues
debugging-network-issues scores 84/100 on our quality scale, 2895th of 4,698 Development & Engineering skills we index.
Its SKILL.md is 53 KB long, well organised into 37 sections with 5 code examples: long enough that it reads more like full documentation than a focused instruction file, which agents can find harder to follow.
With 1,426 GitHub stars, it is one of the more widely adopted skills in the catalogue.
Maintenance, license and trust
- The repository was last updated about 2 months ago, so debugging-network-issues is actively maintained.
- Our last check on 2026-10-14 found the source still online.
- It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
- Its trust signals score 100/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.
AI review by kimi-k2.7-code on 2026-10-03. Automated pattern scan on 2026-10-03. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
debugging-network-issues compared with similar skills
All 4 of these similar skills score higher than debugging-network-issues; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| debugging-network-issues (this skill)by daymade | 84 | 1.4k | 53d ago | SKILL.md |
| taste-skillby Leonxlnx | 100 | 116.8k | 8d ago | CLAUDE.md |
| ai-job-searchby ai-job-search-dev | 100 | 72.1k | today | CLAUDE.md |
| claude-howtoby luongnv89 | 100 | 47.3k | 2d ago | CLAUDE.md |
| lobehubby lobehub | 100 | 85.6k | today | MCP Server |
Frequently asked questions
- How do I install debugging-network-issues?
- Run
npx skills add daymade/claude-code-skills --skill debugging-network-issues. The install tabs above show the steps for each supported agent. - Which AI agents does debugging-network-issues work with?
- It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
- Is debugging-network-issues safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is MIT-licensed and scores 100/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is debugging-network-issues still maintained?
- The repository was last updated about 2 months ago, so debugging-network-issues is actively maintained.
Skill content
View source on GitHubname: debugging-network-issues description: >- Investigates network, streaming and protocol failures with falsification-first layered experiments, the general fallback for unknown root causes. Use for ECONNRESET / RST_STREAM / SSE stalls, CDN/CGNAT timeouts or certificate errors, throughput collapse where everything returns 200 but transfers crawl, or LAN identity/topology mysteries. Not for known Tailscale/TUN/DNS/proxy-path conflicts (use tunnel-doctor).
Debugging Network Issues
Evidence-driven investigation methodology for incidents where the obvious cause is probably wrong. Built from a real 5-hour production case (see references/case-sse-rst-130s.md) where assumption-stacking wasted hours that a 10-minute layered experiment would have resolved.
Apply this skill when the user reports a network/streaming/protocol symptom and the investigator feels tempted to diagnose from one log line or one circumstantial data point. The skill's job is to slow that reflex down.
Triage first — is this a known domain?
Before applying the general methodology below, check whether the symptom points at a stack that already has a dedicated skill in this repo. Those carry the domain-specific symptom→cause→fix tables this skill deliberately stays general about — start there, and come back here for methodology if the root cause turns out to be elsewhere.
| If the symptom is… | Start with |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
| macOS Tailscale ⨯ proxy/VPN conflict (Shadowrocket / Clash / Surge): tailscale ping works but SSH/curl/git fails, Connection closed by 198.18.x.x, TUN DNS hijack, ~60s getaddrinfo resolver stall | tunnel-doctor |
| Cloudflare config: ERR_TOO_MANY_REDIRECTS, SSL-mode mismatch, DNS / proxy-status issues behind the orange cloud | cloudflare-troubleshooting |
| Windows App / AVD / W365 RDP connection quality: WebSocket instead of UDP Shortpath, high RTT, STUN/TURN interference | windows-remote-desktop-connection-doctor |
| Client-side proxy / VPN / TUN misrouting: one specific site fails with ERR_CONNECTION_CLOSED or SSL_ERROR_SYSCALL, other sites work, DNS returns fake/TUN IPs, and adding a PROXY rule did not help | this skill — read references/case-proxy-tun-cname-override.md first |
| TLS certificate-verification errors (UNKNOWN_CERTIFICATE_VERIFICATION_ERROR, a cert for the wrong site) or mid-handshake EOFs on every DIRECT-routed/domestic domain at once, while proxied domains work — and any proxy health watchdog still reports green | tunnel-doctor (TUN DIRECT split-brain step) |
| The proxy is reachable and the OS/Tailscale route is healthy, but bulk transfers are slow and changing the active exit/node changes the measured rate | tunnel-doctor — proxy node / exit / chain capacity branch |
| Nothing errors — it is just slow. Every request returns 200, latency and health checks look fine, but transfers crawl, bulk jobs overrun their estimates, or files arrive truncated | this skill — go straight to Step 0.7; the error-driven steps have nothing to bite on |
If none match — or you tried a domain skill and the evidence points elsewhere — continue below. The methodology generalizes to any multi-layer system.
Note for this skill specifically: If the symptom is a Cloudflare 524/522 on a large
POSTbody (e.g.,/<openrouter-path>withContent-Length> 1 MB), the failure is often upload time to origin exceeding Cloudflare's origin read timeout, not backend slowness. Use the upload-vs-processing checklist below before assuming a backend stall.
Core principles
1. Evidence over assumption
If you cannot point to a concrete artifact — log line, pcap frame, probe output, metric sample — you are guessing, not diagnosing. Before stating "X is the cause", require yourself to name the direct evidence. If it does not exist yet, add instrumentation (see references/instrumentation-patterns.md) or capture it (see references/packet-capture-recipes.md) before continuing.
2. Falsification over confirmation
N independent sources "confirming" a hypothesis does not make it true. One falsifying observation rules it out. Before acting on a hypothesis, answer:
"What observation would make me abandon this hypothesis?"
If the answer is "nothing" or "I cannot think of one", the hypothesis is unfalsifiable and must not drive the investigation. If the answer is concrete, go look for that observation before committing to action.
3. Layered isolation
Multi-hop systems (client → CDN → LB → reverse proxy → app → upstream) concentrate bugs at the seams between layers. When a symptom could plausibly come from several layers, do not reason about which layer; test. The canonical technique: run the same logical request through three or more paths that differ by exactly one hop, then compare where the symptom appears. This resolves in minutes what stacking hypotheses cannot resolve in hours. See references/layered-isolation-experiment.md.
The same technique isolates capacity, not just correctness. When the symptom is a rate rather than an error, vary the stack instead of the hop: measure the same direction over two channels that share the network path but share no application code. It is the cheapest way to stop tuning an application that was never the bottleneck. Resist compressing the reading into "agreement means the path" — that holds only when both channels are slow; two fast channels mean the probe failed to reproduce the symptom and prove nothing at all. See Step 0.7 for how to read each of the four outcomes.
4. Counter-review before committing
Before committing to a root cause or shipping a fix, have independent reviewers challenge the conclusion — not confirm it. Agents are good at surfacing risks a single investigator did not think of; they are bad at weighing them. Apply the four-question filter (see references/counter-review-pattern.md) to every finding before it shapes action.
5. A green health check certifies only the path it probes
Monitors watch the paths their authors thought to probe. Multi-plane systems — a TUN proxy with a DIRECT plane and a proxied plane, a service with a data plane and a control plane, a stack with a backend API and a web login page — fail one plane at a time, and a watchdog that probes only the other plane stays green through the entire outage. In the incident behind this principle, a proxy health daemon probed one overseas endpoint through the proxy every 5 minutes and logged "healthy" for 2+ hours while the direct plane was completely down.
Before accepting "the monitor says it's healthy" as evidence, ask: which exact path does that check exercise? Its green counts as evidence for that path alone. Enumerate the planes the system actually forwards or serves, and probe the failing one directly — the check that would have caught the outage is usually one curl away.
A check also certifies only the quantity it is large enough to measure. Path coverage is one axis; scale is the other, and it is the one that hides throughput collapse. A liveness probe returns a few hundred bytes, so its timing is dominated by handshake and round-trip — in the case study it answered in 40 ms all day, unchanged, across a 100× swing in the link's actual capacity, and it was not lying: it genuinely did what it measures. Same for ping/RTT, which times a small packet's round trip and says nothing about capacity.
The practical rule: a probe measures the link only once transfer time dominates its total time. So size it by the answer you need, not by convenience — if a probe returns in well under a second, essentially all of that was setup and you have measured setup. Sidestep the sizing question entirely by budgeting time instead of bytes (stream for N seconds, divide what arrived by N), which is what Step 0.7's commands do and why they stay cheap on a link that is already crawling. Extend the question to: which path, and at what scale?
6. Exhaust the instruments before asking the user — escalate only what only they can provide
A user's spoken observation ("the Wi-Fi drops for a few seconds", "some apps report connection errors") is a lead, not a question to hand back. Treat each open sub-question it contains as presumed observable, and search for the instrument before asking: monitor/probe ledgers (where a health daemon exists, its log holds the failure timetable of the paths it probes — in both directions: a green ledger never falsifies the user's observation (Principle 5), and a red one says nothing about paths it never probed), system logs (kernel link/disassociation events settle "did Wi-Fi physically drop"; per-process error bursts settle "which apps failed" only for apps that log there), and control channels on the same network (a second host over a different medium — a wired box with no proxy, a hotspot comparison, even the router's own status page; when no control channel exists, say so explicitly rather than treating the question as answered). When the instrument search comes back empty for a sub-question, the move is Step 4 — stand up instrumentation and wait for recurrence — not "ask the user to recall".
Only three categories legitimately reach the user mid-investigation:
- Decision rights — production changes, restarts, spending, anything past your authorization boundary.
- Physical actions and first-person observations no instrument captured — unplugging a box, reading a label password, whether the Wi-Fi icon itself disappeared on a device you have no telemetry for.
- Credentials or access you do not have — a management password that exists only on a device label.
Observed 2026-09-10: a home-network investigation closed its report with four questions for the user. "Which apps reported errors" — its diagnostic content, a per-plane failure timetable — was already in the health daemon's ledger (the app-name list itself lives only on the user's screen, and adds no layer information the timetable lacks); "did Wi-Fi actually drop" was settled by twelve hours of kernel logs with zero disassociation events; both went to the user anyway. The fourth — "is the retired router still broadcasting" — is the honest counter-example: its ARP absence proved nothing (Trap 14: a probe certifies only the L2 domain it ran on), the platform redacted the Wi-Fi scan, so that one correctly reached the user as a five-second physical check.
For every question you hand the user, write one sentence in the report naming why no instrument can answer it and which of the three categories it falls in. If you cannot produce that sentence, the question is not exhausted — go back to the instruments; do not ask.
Workflow
Copy this checklist into the investigation notes and check items off:
Investigation Progress:
- [ ] Step 0: Scope the symptom (exact error, exact times, who, who-not, what changed)
- [ ] Step 0.5: Verify the premi
Truncated for display — read the full file on GitHub.
Related Skills
taste-skill
116.8kAgent skills that give coding agents taste: art direction, reference images and a browser check instead of generic AI pages
ai-job-search
72.1kThe job search that runs on your machine. AI job application framework built on Claude Code: evaluate postings, tailor CVs, write cover letters, prep interviews. Fork it and own it.
claude-howto
47.3kA visual, example-driven guide to Claude Code — from basic concepts to advanced agents, with copy-paste templates that bring immediate value.
lobehub
85.6k🤯 LobeHub - Super-Agents on Your Team. Add super-agents to the chats your team already uses.They take on work by themselves and get better every week.
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
