tunnel-doctor
MUST be used first for tunnel / proxy-path connectivity failures or slow throughput (网络故障 / 连不上 / 代理或隧道下超时). Diagnoses Tailscale, proxy, TUN, DNS and SSH-tunnel problems on macOS and Windows/WSL, e.g.
Install / Use
npx skills add daymade/claude-code-skills --skill tunnel-doctorInstalls into whichever agent you are using.
SKILL.md
Installable skill definition
Quality Score
Category
OperationsSupported Platforms
Our assessment of tunnel-doctor
tunnel-doctor scores 84/100 on our quality scale, 568th of 745 Operations skills we index.
Its SKILL.md is 84 KB long, well organised into 147 sections with 71 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 tunnel-doctor 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
ReviewOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands (1 minor note below). An AI review judged it risky: Line 1040 is flagged as an instruction to install software by piping a downloaded script into a shell; in a skill/rules file that directs the agent to execute remote code without package-manager verification.
- noteInstalls by piping a downloaded script into a shellline 1040
curl -fsSL https://tailscale.com/install.sh | sh
AI review: risky
- Line 1040 is flagged as an instruction to install software by piping a downloaded script into a shell; in a skill/rules file that directs the agent to execute remote code without package-manager verification.
- The skill instructs the agent to make disruptive network changes (edit route tables, restart VPN/proxy services, change Docker daemon proxy settings) that can alter system connectivity.
- While the overall purpose is legitimate network troubleshooting, the remote-script install pattern and broad network reconfiguration authority meaningfully increase the agent's attack surface and potential for accidental harm.
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.
tunnel-doctor compared with similar skills
All 4 of these similar skills score higher than tunnel-doctor; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| tunnel-doctor (this skill)by daymade | 84 | 1.4k | 53d ago | SKILL.md |
| Agent-Reachby Panniantong | 100 | 112.3k | 8d ago | CLAUDE.md |
| x402by browser-use | 100 | 121.0k | 3d ago | SKILL.md |
| algorithmic-artby anthropics | 100 | 177.9k | 55d ago | SKILL.md |
| pptxby anthropics | 100 | 177.9k | 55d ago | SKILL.md |
Frequently asked questions
- How do I install tunnel-doctor?
- Run
npx skills add daymade/claude-code-skills --skill tunnel-doctor. The install tabs above show the steps for each supported agent. - Which AI agents does tunnel-doctor 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 tunnel-doctor safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands (1 minor note below). An AI review judged it risky: Line 1040 is flagged as an instruction to install software by piping a downloaded script into a shell; in a skill/rules file that directs the agent to execute remote code without package-manager verification. 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 tunnel-doctor still maintained?
- The repository was last updated about 2 months ago, so tunnel-doctor is actively maintained.
Skill content
View source on GitHubname: tunnel-doctor description: >- MUST be used first for tunnel / proxy-path connectivity failures or slow throughput (网络故障 / 连不上 / 代理或隧道下超时). Diagnoses Tailscale, proxy, TUN, DNS and SSH-tunnel problems on macOS and Windows/WSL, e.g. Tailscale ping works but SSH fails, curl works but browser gets 503, Git/Docker fails behind the proxy, or downloads crawl despite a reachable proxy. Not for application-layer bugs (use debugging-network-issues). allowed-tools: Read, Grep, Edit, Bash
Tunnel Doctor
Diagnose and fix conflicts when Tailscale coexists with proxy/VPN tools on macOS, with specific guidance for SSH access to WSL instances.
Methodology base: the general diagnostic discipline this skill builds on — evidence over assumption, falsification over confirmation, layered isolation, counter-review — lives in the debugging-network-issues skill. This skill is the macOS Tailscale⨯proxy domain layer on top of it; reach for the base skill when the symptom is not a known Tailscale/proxy conflict.
Ownership boundary: this skill owns concrete local network-path operations:
Tailscale, route/DNS/proxy interception, VM/WSL propagation, TUN forwarding
planes, and proxy node/exit/chain capacity. Use debugging-network-issues as the
general method when the boundary is still unknown or the symptom belongs to
SSE/CDN/application protocol behavior. This keeps one concrete operator instead
of forcing the user to choose between two overlapping proxy doctors.
Target and task scope
Before remote probes or changes, establish whether the target is a designated test machine, an explicitly requested colleague's working computer, or unknown. Use the owner's existing machine-purpose ledger and current task; do not log into a colleague's machine to classify it. Saved SSH access and previous successful tests do not grant ongoing use. Use designated test machines for routine testing; their unavailability does not authorize another person's computer.
Keep an explicitly requested one-off test on a colleague's computer within its stated result and necessary verification. Stop there on completion, cancellation, or a need for an unapproved environment change. Move later performance, migration, and regression tests to designated test machines. A test failure does not authorize disabling that person's proxy/VPN, quitting apps, changing routes, or installing a background task. Proceed with disruptive repair there only when the user has explicitly requested that repair and its interruption. Existing authorization for owner test-machine maintenance remains valid; do not ask again for its routine steps.
Apply this boundary even when invoked directly, through another Skill, after compaction, or through a peer handoff. After access is stopped, use existing records rather than another SSH probe to verify that it stopped.
Disruptive network changes
Before any authorized VPN disconnect, app termination, route cutover, or service restart, read network_change_recovery.md. Validate prerequisites before interruption, arm bounded recovery before the first disruptive action, and verify both the repaired path and the user's original network use. A successful stop command, a detached process, or a restart placed at the end of a script is not recovery evidence.
Conflict Layers
Proxy/VPN tools on macOS create conflicts at several independent layers. Layers 1-3 affect Tailscale connectivity; Layer 4 affects SSH git operations; Layer 5 affects VM/container runtimes. TUN-state failure modes beyond this table — SSH/git connection drops, resolver stall, DIRECT split-brain — are covered in Steps 2H–2J:
| Layer | What breaks | What still works | Root cause |
|-------|-------------|------------------|------------|
| 1. Route table | Everything (SSH, curl, browser) | tailscale ping | tun-excluded-routes adds en0 route overriding Tailscale utun |
| 2. HTTP env vars | curl, Python requests, Node.js fetch | SSH, browser | http_proxy set without NO_PROXY for Tailscale |
| 3. System proxy (browser) | Browser only (HTTP 503) | SSH, curl (both with/without proxy) | Browser uses VPN system proxy; DIRECT rule routes via Wi-Fi, not Tailscale utun |
| 4. SSH ProxyCommand double tunnel | git push/pull (intermittent) | ssh -T (small data) | connect -H creates HTTP CONNECT tunnel redundant with Shadowrocket TUN; landing proxy drops large/long-lived transfers |
| 5. VM/Container proxy propagation | docker pull, docker build | Host curl, running containers | VM runtime (OrbStack/Docker Desktop) auto-injects or caches proxy config; removing proxy makes it worse (VM traffic via TUN → TLS timeout) |
Diagnostic Workflow
Step 1: Identify the Symptom
Determine which scenario applies:
- Browser returns HTTP 503, but
curland SSH both work → System proxy bypass conflict (Step 2C) local.<domain>fails in browser/defaultcurl, but direct/no-proxy request works → Local vanity domain proxy interception (Step 2C-1)- Tailscale ping works, SSH works, but curl/HTTP times out → HTTP proxy env var conflict (Step 2A)
- Tailscale ping works, SSH/TCP times out → Route conflict (Step 2B)
- Remote dev server auth redirects to
localhost→ browser can't follow → SSH tunnel needed (Step 2D) make status/ scripts curl to localhost fail with proxy → localhost proxy interception (Step 2E)git push/pullfails withFATAL: failed to begin relaying via HTTP→ SSH double tunnel (Step 2F)docker buildRUN apk/aptfails withConnection refusedinstantly → OrbStack transparent proxy + TUN conflict (Step 2G-1, fix:--network host)docker pullfails withTLS handshake timeout→ VM proxy misconfiguration (Step 2G-2, fix:docker.jsonwithhost.internal)- Container healthcheck
(unhealthy)but app runs fine → Lowercase proxy env var leak (Step 2G-4, fix: clearhttp_proxy+HTTP_PROXY) docker buildcan't fetch base images → VM/container proxy propagation (Step 2G)docker pullworks butdocker buildstill dies fetching base-image tokens (TLS/i-o timeout) on a WSL2 + Docker Desktop host, or every runbook proxy port on a Windows+v2rayN host silently died after a v2rayN upgrade → buildkit direct-dials past the DD proxy override / v2rayN ≥7.17 LAN-port split (references/windows_host_tun_wsl_cascade.md §2026-08-23)git clonefails withConnection closed by 198.18.x.x→ two different mechanisms produce this; Step 2H separates them- Every domestic/DIRECT-rule site fails at once (TLS
unexpected EOFmid-handshake, proxy-port CONNECT returns 503, Node CLIs reportUNKNOWN_CERTIFICATE_VERIFICATION_ERROR) while proxied overseas sites keep working → TUN DIRECT split-brain (Step 2J) - Everything on macOS fails at once — domestic AND overseas, and even Step 2J's real-IP probe fails → do not declare an outage yet; run the physical-interface discriminator in "TUN full-stall vs genuine outage" (above Step 2A)
- SSH connects but
operation not permitted→ Tailscale SSH config issue (Step 4) - SSH connects but
be-child sshexits code 1 → WSL snap sandbox issue (Step 5) - TCP port 22 reachable (
nc -zsucceeds) but SSH fails withkex_exchange_identification: Connection closed→ Tailscale SSH proxy intercept on WSL (Step 5A) - Same
kex_exchange_identification/Connection closed by UNKNOWN port 65535, but there is no Tailscale — you are behind a TUN and the host is a public cloud VM whose HTTPS still works → could be your TUN or the destination's firewall allowlist; they are indistinguishable from the client. Step 2K settles it out-of-band tailscale sshreturns "not available on App Store builds" → Wrong Tailscale distribution on macOS (Step 5B)- Any tool using system DNS (
ssh,curl,git) hangs ~60s before resolving, butnslookupreturns instantly → Stalled resolver ingetaddrinfochain (Step 2I) - Windows+WSL host: everything offline at once (domestic AND overseas), WSL dead too, "even Tailscale won't come online" — and/or the user tried several recovery actions (switched NICs, toggled TUN) and can't tell which one fixed it → Windows host TUN cascade + event-log forensics (Step 5C)
- Tailscale, DNS, route ownership, and proxy reachability all pass, but large transfers remain slow and switching the active proxy node changes throughput → proxy node / exit / chain capacity workflow in references/proxy_node_chain_throughput.md
- You want one app's bulk traffic (BaiduNetdisk downloads, Feishu/Lark uploads) off the metered proxy — or out of the status-bar counter entirely → not a conflict; a splitting task. On this Mac the
shadowrocket-splittingskill owns the whole workflow (target list, replay, CIDR capture, wipe guard); the mechanism background is references/proxy_conflict_reference.md § "Per-app traffic splitting on macOS" — which of the three mechanisms (DIRECT rule /tun-excluded-routes/always-real-ip) can work for the app depends on whether it connects to literal IPs or the system resolver, and the DNS-layer keys are inert on the macOS Catalyst build.
Key distinctions:
- SSH does NOT use
http_proxy/NO_PROXYenv vars. If SSH works but HTTP doesn't → Layer 2. curluseshttp_proxyenv var, NOT the system proxy. Browser uses system proxy (set by VPN). Ifcurlworks but browser doesn't → Layer 3.- If
tailscale pingworks but regularpingdoesn't → Layer 1 (route table corrupted). - If
ssh -T git@github.comworks butgit pushfails intermittently → Layer 4 (double tunnel). - If host
curl https://...works butdocker pulltimes out → Layer 5 (VM proxy propagation). - If
docker pullworks butdocker buildRUN apk addfails instantly withConnection refused→ OrbStack transparent proxy broken by TUN (Step 2G-1). - If container healthcheck shows
(unhealthy)but app works → lowercasehttp_proxyleaked into container (Step 2G-4). - If DNS resolves to
198.18.x.xvirtual IPs → a TUN is active, which is not by itself a diagnosis: under TUN every hostname resolves this way, on success as well as failure. Go to Step 2H to find out which mechanism you have. - If connections to fake-IP-resolved domains die but the same host works via
curl --resolve <host>:443:<real-ip>(real IP fromdig @<public-resolver>) → the TUN tool's DIRECT forwarding state is broken, not your network and not the destination (Step 2J). - If
nc -zsucceeds on port 22 but SSH gets no banner (kex_exchange_identification) → Tailscale SSH proxy intercept (Step 5A). Confirm withtcpdump -i any port 22on the remote — 0 packets means Tailscale intercepts above the kernel. - If
nc -zalso succeeds on a port the destination does not serve (probe 65001) → under a TUN the local stack answers for the destination, so nonc -zresult on that host means anything. Never read a port probe you have not calibrated this way. This supersedes the plainnc -zreading in the bullet above whenever a TUN — not just Tailscale — is in the path (Step 2K). - If the destination's own
journalctl -u sshshows zero entries for your attempts → something beforesshdis eating them, but not necessarily the network: a host-local packet filter drops them just as silently.tcpdumpon the host separates "never arrived" from "arrived and was dropped locally"; only the first implicates your TUN. Reach the machine through the cloud provider's guest-agent channel to ask, since that path does not use the port you cannot reach. Check the journal, notauth.log: on Ubuntu 24.04sshdwrites nothing toauth.log, so an empty file there is not evidence (Step 2K). - A cloud host enforces an inbound port twice — provider security group and host firewall (
ufw/firewalld/nftables). Adding your IP to
Truncated for display — read the full file on GitHub.
Related Skills
Agent-Reach
112.3kGive your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.
x402
121.0kSet up Browser Use Cloud payments with x402 — pay per request from a crypto wallet (USDC on Base mainnet), no signup or API key.
algorithmic-art
177.9kCreating algorithmic art using p5.js with seeded randomness and interactive parameter exploration. Use this when users request creating art using code, generative art, algorithmic art, flow fields, or particle systems.
pptx
177.9kUse this skill any time a .pptx or .potx file is involved in any way — as input, output, or both. This includes: creating slide decks, pitch decks, or presentations; reading, parsing, or extracting text from any .pptx or .potx file (even if the extracted content will be used elsewhere, like in an em…
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.
