network-troubleshoot-skill

network-troubleshoot-skill

Every developer hits network errors.
This skill makes any AI coding agent fix them for you.

中文文档 · Troubleshooting Guide · Patterns from Agents · Contributing

One copy-paste to give your AI coding agent network debugging superpowers.
Works with Claude Code, Cursor, GitHub Copilot, Windsurf, Cline, Codex, Continue, Aider, Kiro, Trae, CodeBuddy, OpenCode, Augment, Gemini, Cody, Amazon Q, and more.

One-Click Install

macOS / Linux / Windows Git Bash:

curl -fsSL https://raw.githubusercontent.com/CacinieP/network-troubleshoot-skill/main/install.sh | bash -s -- cursor

Windows PowerShell:

irm https://raw.githubusercontent.com/CacinieP/network-troubleshoot-skill/main/install.ps1 | iex
# Then enter: cursor

Supported: cursor, claude-code, copilot, windsurf, cline, codex, continue, aider, kiro, trae, codebuddy, opencode, augment, gemini, cody, amazon-q, generic

Why Use This

Most AI-agent rule repos are generic prompt collections. This one is narrowly focused on network failures that stop real development work: DNS failures, proxy/VPN cascades, SSL errors, registry timeouts, package-manager failures, Docker pulls, Git fetches, and HTTP 4xx/5xx issues.

The goal is simple: when an agent sees a network error, it should gather the right diagnostics, classify the symptom, choose the likely root cause, apply a reversible fix, and verify the original command again.

What It Does

When network errors occur, this skill guides your AI coding agent through a structured diagnostic workflow:

1. Symptom Classification — Identify the error type (connectivity, DNS, proxy, SSL, HTTP, etc.)
2. Automated Diagnostics — Run the right diagnostic commands for the OS and symptom
3. Root Cause Analysis — Interpret diagnostic output to pinpoint the issue
4. Resolution Steps — Apply actionable fixes with copy-paste commands

Supported Agents — 17+

Any other agent? Use adapters/generic/network-troubleshoot.md — a plain markdown file that works everywhere.

Quick Start

# One command — replace <agent> with your tool name
curl -fsSL https://raw.githubusercontent.com/CacinieP/network-troubleshoot-skill/main/install.sh | bash -s -- <agent>

# Example: install for Cursor
curl -fsSL https://raw.githubusercontent.com/CacinieP/network-troubleshoot-skill/main/install.sh | bash -s -- cursor

git clone https://github.com/CacinieP/network-troubleshoot-skill.git
cd network-troubleshoot-skill

# Claude Code
mkdir -p ~/.claude/skills/network-troubleshoot && cp skills/network-troubleshoot/SKILL.md ~/.claude/skills/network-troubleshoot/

# Cursor
cp adapters/cursor/network-troubleshoot.mdc .cursor/rules/

# GitHub Copilot
mkdir -p .github && cp adapters/github-copilot/copilot-instructions.md .github/

# Windsurf
cp adapters/windsurf/.windsurfrules .

# Cline
cp adapters/cline/.clinerules .

# Continue
mkdir -p .continue/rules && cp adapters/continue/rules/network-troubleshoot.md .continue/rules/

# Aider
cp adapters/aider/CONVENTIONS-network.md .

# Kiro
mkdir -p .kiro/steering && cp adapters/kiro/steering/network-troubleshoot.md .kiro/steering/

# Trae
mkdir -p .trae/rules && cp adapters/trae/.trae/rules/network-troubleshoot.md .trae/rules/

# CodeBuddy
mkdir -p .codebuddy/rules/network-troubleshoot && cp adapters/codebuddy/.codebuddy/rules/network-troubleshoot/RULE.mdc .codebuddy/rules/network-troubleshoot/

# Augment
cp adapters/augment/.augment-rules .

# OpenCode
cp adapters/opencode/AGENTS.md .

# Sourcegraph Cody
cp adapters/cody/.cody.md .

# Amazon Q Developer
mkdir -p .amazonq/rules && cp adapters/amazon-q/.amazonq/rules/network-troubleshoot.md .amazonq/rules/

# Any other agent
cp adapters/generic/network-troubleshoot.md .

Features

Error Coverage

Platform Support

Diagnostic Flow

Network Error
     │
     ▼
┌─────────────────────┐
│  Symptom Classification  │
└──────────┬──────────┘
           │
     ┌─────┼──────┬───────┬───────┬───────┐
     ▼     ▼      ▼       ▼       ▼       ▼
  Connectivity DNS  Proxy  SSL/TLS  HTTP  Timeout
     │     │      │       │       │       │
     ▼     ▼      ▼       ▼       ▼       ▼
    ping  nslookup  env   openssl  curl  traceroute
    nc    dig      proxy  s_client -vvv   mtr
     │     │      │       │       │       │
     └─────┴──────┴───────┴───────┴───────┘
                    │
                    ▼
           ┌──────────────┐
           │  Root Cause   │
           └──────┬───────┘
                  ▼
           ┌──────────────┐
           │  Resolution   │
           └──────┬───────┘
                  ▼
           ┌──────────────┐
           │   Verify      │ ← re-run failed command
           └──────────────┘

China Developer Support

Built from real Chinese developer agent sessions with specific patterns:

• Proxy/VPN cascade diagnosis (Clash, V2Ray, SSR)
• npm/pip/docker registry mirror configuration
• GFW-related connectivity patterns
• Chinese language triggers (网络问题, 连不上, 无法访问, 代理, 超时)
• Proxy layer mismatch detection (Electron+Go, Docker Desktop, VS Code+extensions)
• TUN mode diagnosis and resolution guidance

Common Fixes Quick Reference

One-Click Proxy Setup (China Developers)

export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890
export ALL_PROXY=socks5://127.0.0.1:7891
npm config set registry https://registry.npmmirror.com
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
git config --global http.proxy http://127.0.0.1:7890

Repository Structure

network-troubleshoot-skill/
├── skills/
│   └── network-troubleshoot/
│       └── SKILL.md                       # Claude Code skill (primary)
├── adapters/
│   ├── generic/                           # Universal fallback
│   ├── cursor/                            # .mdc format
│   ├── github-copilot/                    # copilot-instructions.md
│   ├── windsurf/                          # .windsurfrules
│   ├── cline/                             # .clinerules
│   ├── codex/                             # Agent markdown
│   ├── continue/                          # .continue/rules/
│   ├── aider/                             # CONVENTIONS-network.md
│   ├── kiro/                              # .kiro/steering/
│   ├── trae/                              # .trae/rules/ (MDC format)
│   ├── codebuddy/                         # .codebuddy/rules/ (MDC format)
│   ├── opencode/                          # AGENTS.md
│   ├── hermes/                            # Agent instructions
│   ├── augment/                           # .augment-rules
│   ├── gemini/                            # GEMINI.md
│   ├── cody/                              # .cody.md
│   └── amazon-q/                          # .amazonq/rules/
├── docs/
│   ├── TROUBLESHOOTING_GUIDE.md           # Full reference guide
│   └── PATTERNS_FROM_AGENTS.md            # Data-driven pattern analysis
├── install.sh                             # One-click installer
├── install.ps1                            # PowerShell installer
├── CONTRIBUTING.md                        # How to contribute
├── LICENSE
├── README.md
└── README_CN.md

Comparison with Similar Projects

Key differentiator: This is the only repo that combines (1) multi-agent support across 17+ tools, (2) data-driven patterns from real sessions, (3) China/GFW-specific scenarios, and (4) zero-config copy-paste installation. NetClaw is excellent for enterprise network engineers (BGP/OSPF/EVPN), while this project targets developers encountering network errors in their daily workflow.

Competitive Score

Data Sources

1. 112+ coding agent interaction sessions — Claude Code (577), KimiCode (25), Codex (11), Cursor (3)
2. 9 network troubleshooting patterns extracted from real-world developer workflows
3. China-specific network scenarios — proxy cascade, GFW patterns, registry mirrors
4. Industry best practices — curl, openssl, dig diagnostic references

Contributing

Contributions welcome:

• Additional agent adapter formats
• Platform-specific diagnostic commands
• New error patterns and edge cases
• Translations
• Example sessions

License

MIT

If this saved you from a network debugging session, consider giving it a ⭐!
It helps other developers discover this tool.