Skip to main content
skill CX Codex

network-troubleshooting — Claude Code skill for network errors

The network-troubleshooting Claude Code skill diagnoses network failures in commands and services. It activates for DNS, TLS, proxy, connection, and package registry timeout errors.

Apache-2.0 131 installs ★ 312 updated 2026-10-08

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add Mindrally/skills --skill network-troubleshooting -a claude-code
Open on GitHub

What network-troubleshooting does

The skill helps trace network errors such as refused connections, DNS failures, certificate issues, proxy errors, and package registry timeouts. It gathers the failing command and error, classifies the symptom, then selects a check scoped to the affected host, URL, or port.

Checks are read-only and stay focused on the failing target. The skill avoids exposing configuration secrets and never disables certificate verification. Changes to network, proxy, Git, or other system settings require explicit approval for the specific action.

What it helps with

  • trace why a service refuses a connection
  • diagnose DNS lookup failures for a host
  • inspect a TLS certificate without bypassing verification
  • investigate npm or pip registry timeouts
  • distinguish proxy errors from remote service failures

Example prompts for the agent

  • Find out why curl cannot connect to api.example.com.
  • Diagnose the timeout from npm install.
  • Check whether the Git certificate error points to a TLS problem on the remote host.

How to install network-troubleshooting

1Skills CLI (Vercel)

npx skills add Mindrally/skills --skill network-troubleshooting -a claude-code

2Manually: put the files in place

~/.claude/skills/network-troubleshooting/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/network-troubleshooting/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about network-troubleshooting

How do I install network-troubleshooting in Claude Code?

Run npx skills add Mindrally/skills --skill network-troubleshooting -a claude-code. The skill is installed at ~/.claude/skills/network-troubleshooting/SKILL.md.

What does network-troubleshooting do?

It classifies network errors and selects scoped diagnostic checks for the affected target. Results are explained before any remediation is suggested.

How does network-troubleshooting handle network checks?

It uses read-only checks limited to the failing target. TLS verification must not be disabled, and system settings cannot be changed without explicit approval.

Source text

SKILL.md · Apache-2.0
---
name: network-troubleshooting
description: "Systematic, safety-first diagnosis of developer network failures such as connection refused, DNS resolution errors, TLS certificate problems, proxy failures, and package registry timeouts. Use when a command fails with a network-shaped error (curl, npm, pip, git, docker), when a service is unreachable, or when the user asks to debug connectivity, DNS, TLS, or proxy issues."
metadata:
  maintainer: Mindrally
  source: https://github.com/Mindrally/skills
---

# Network Troubleshooting

This skill provides a concise, safety-first decision guide for diagnosing developer network failures. Diagnostics must stay read-only and target-scoped — this is not an automated remediation toolkit.

## Safety Boundaries

These boundaries apply to every step of the workflow below and must never be relaxed, even if asked:

- Prefer read-only diagnostics and trusted project-provided diagnostic scripts.
- Use the failing host, URL, registry, or service as the default probe target — do not probe unrelated hosts.
- Ask before probing unrelated external services.
- Never print proxy URLs, credentials, tokens, auth headers, package index URLs, registry hostnames from config, or raw config values in shared output.
- Internal hosts and URLs may be collected for target-scoped local diagnostics, but replace them with placeholders before sharing logs or reports unless the user explicitly approves including them.
- Never dump local configuration from npm, pnpm, yarn, pip, Git, Docker, shell, OS proxy, VPN, or certificate stores.
- Never disable, bypass, or skip TLS or certificate verification (no `-k`/`--insecure`, no `NODE_TLS_REJECT_UNAUTHORIZED=0`, no `verify=False`), even temporarily "just to test."
- Never change OS networking, DNS, proxy, package manager, Git, Docker, shell, VPN, or trust-store settings without explicit user approval for the exact action being taken.

## Workflow

1. **Collect** — Capture the exact error text, the failing command, the target host/URL/port, OS/shell, proxy/VPN context, and whether the failure affects one target or many.
2. **Classify** — Match the symptom against the error classification table below to form a hypothesis.
3. **Diagnose** — Run only read-only checks scoped to the failing target, starting with the smallest relevant check.
4. **Explain** — Interpret each diagnostic result in plain language before suggesting any fix.
5. **Advise** — Present remediation options as choices; wait for explicit user approval before changing any state.
6. **Verify** — After an approved change, re-run the original failing command or an equivalent target-scoped check.

## Error Classification

| Error Pattern | Likely Category |
|---|---|
| `ECONNREFUSED`, `ERR_CONNECTION_REFUSED`, `Connection refused` | Target service or port is not listening |
| `ECONNRESET`, `socket hang up`, `Connection reset` | Connection dropped by target, proxy, firewall, or middlebox |
| `ETIMEDOUT`, `ERR_CONNECTION_TIMED_OUT`, `timed out` | Routing, firewall, proxy, or target availability |
| `ENOTFOUND`, `EAI_NONAME`, `ERR_NAME_NOT_RESOLVED`, `getaddrinfo` | DNS or hostname issue |
| `ERR_PROXY_CONNECTION_FAILED`, proxy tunnel errors, HTTP `407` | Proxy configuration or proxy authentication |
| `UNABLE_TO_VERIFY_LEAF_SIGNATURE`, `CERT_HAS_EXPIRED`, `self signed`, `ERR_CERT_*` | TLS certificate or local trust issue |
| HTTP `403` | Authorization, IP allowlist, CORS, or policy block |
| HTTP `502`, `503`, `504` | Upstream service, gateway, CDN, or transient server issue |
| `npm ERR! network`, package install timeout, `pip` timeout | Package registry, proxy, DNS, or network path issue |
| `fatal: unable to access`, Git fetch/push timeout | Git remote, proxy, DNS, TLS, or network path issue |

## Safe Target-Scoped Checks

Choose the smallest relevant check and explain what it does before running it. Always substitute the specific failing `<target-host>`, `<port>`, and `<path>` — never a broader or unrelated target.

### Connectivity

Linux/macOS:

```bash
ping -c 4 <target-host>
curl -v telnet://<target-host>:<port> --connect-timeout 5
```

Windows PowerShell:

```powershell
Test-Connection -ComputerName <target-host> -Count 4
Test-NetConnection -ComputerName <target-host> -Port <port>
```

### DNS

Linux/macOS:

```bash
nslookup <target-host>
dig <target-host>
```

Windows PowerShell:

```powershell
Resolve-DnsName <target-host>
```

### HTTP

Linux/macOS:

```bash
curl -vvv -o /dev/null -w "HTTP %{http_code}\nTime: %{time_total}s\nDNS: %{time_namelookup}s\nConnect: %{time_connect}s\nTLS: %{time_appconnect}s\n" https://<target-host>/<path>
curl -I https://<target-host>/<path>
```

Windows PowerShell:

```powershell
$uri = "https://<target-host>/<path>"
try {
  $resp = Invoke-WebRequest -Uri $uri -Method Head -TimeoutSec 10
  "HTTP status: $([int]$resp.StatusCode)"
} catch [Net.WebException] {
  if ($_.Exception.Response) {
    "HTTP status: $([int]$_.Exception.Response.StatusCode)"
  } else {
    "HTTP request failed: $($_.Exception.Message)"
  }
}
```

### TLS

Linux/macOS:

```bash
openssl s_client -connect <target-host>:<port> -servername <target-host> -showcerts </dev/null
echo | openssl s_client -connect <target-host>:<port> -servername <target-host> 2>/dev/null | openssl x509 -noout -subject -issuer -dates
```

Windows PowerShell — check the certificate and HTTP status separately so a non-2xx response is never mislabeled as a certificate failure:

```powershell
try {
  $req = [Net.HttpWebRequest]::Create("https://<target-host>:<port>/<path>")
  $req.Method = "HEAD"
  $req.Timeout = 5000
  try {
    $resp = $req.GetResponse()
  } catch [Net.WebException] {
    $resp = $_.Exception.Response
    if ($req.ServicePoint.Certificate) {
      $cert = $req.ServicePoint.Certificate
      "Cert subject: $($cert.Subject)"
      "Cert expires: $($cert.GetExpirationDateString())"
    }
    if ($resp) {
      "HTTP status: $([int]$resp.StatusCode) $($resp.StatusDescription)"
      $resp.Close()
    } else {
      "TLS/network error: $($_.Exception.Message)"
    }
    return
  }
  $cert = $req.ServicePoint.Certificate
  if ($cert) {
    "Cert subject: $($cert.Subject)"
    "Cert expires: $($cert.GetExpirationDateString())"
  }
  "HTTP status: $([int]$resp.StatusCode) $($resp.StatusDescription)"
  $resp.Close()
} catch {
  "TLS/network error: $($_.Exception.Message)"
}
```

### Proxy and Package Managers

- Avoid raw config reads for proxy, package manager, Git, Docker, or OS network configuration.
- Report only whether relevant settings appear present when this can be checked without printing values.
- If the available command would print a URL, token, internal hostname, auth header, or full config value, do not run it.
- Only perform package registry probes when the failed operation already targeted that registry, or after the user approves that exact probe target.

## User-Approved Remediation Options

Present these as choices for the user to approve — never apply them automatically.

| Diagnosis | Safe Advice |
|---|---|
| Target service is not listening | Check whether the local or remote service is running and whether the expected port is correct. |
| DNS lookup fails | Check the hostname, hosts-file expectations, DNS service status, or approved DNS changes. |
| Proxy appears required or unavailable | Ask whether the user wants to start or adjust the proxy/VPN, then verify only the approved target. |
| TLS certificate expired | Renew or replace the certificate, fix system time, install a trusted local development CA, or update the trust store. Never bypass TLS verification. |
| TLS unknown CA | Import the correct CA into the appropriate trust store after the user confirms the source and scope. |
| HTTP `407` | Ask the user to confirm proxy authentication requirements before changing credentials or tool settings. |
| HTTP `403` | Check authentication, API key scope, IP allowlist, CORS policy, or service policy. |
| HTTP `502`/`503`/`504` | Treat as upstream or gateway instability; check status pages when approved and retry with backoff. |
| Package install timeout | Discuss approved registry, proxy, or network-path options without printing or changing stored config values. |
| Git network failure | Discuss approved remote URL, proxy, credential, TLS, or network-path options without changing global Git settings automatically. |
| Docker pull failure | Discuss approved registry mirror, proxy, or daemon settings as a user-approved configuration change. |

## Verification

- After any user-approved change, re-run the original failing command whenever possible.
- If a smaller check is needed instead, keep it scoped to the same failing host, URL, registry, or service.
- Always explain what each diagnostic result means before recommending the next step.

© Mindrally · Apache-2.0 · Mindrally/skills

Similar skills

All skills for DevOps and infrastructure →

From the same set247

The whole set →
robocorp-cursor-rules Agent rules for writing RoboCorp RPA automation in Python: plain functions, Pydantic validation, async I/O. CX Codex +1 677installs parcel-bundler parcel-bundler — a skill that gives the agent a working set of Parcel conventions: entry points, TypeScript, CSS modules, caching and production builds. Useful when the project has no bundler config. CX Codex +1 674installs clean-code The clean-code Claude Code skill guides code writing and review, with an emphasis on clarity and restrained abstractions. It applies to new code, refactors, and quality checks. CX Codex +1 182installs embedded-stm32 embedded-stm32 — a skill for Claude Code and Codex providing engineering rules for embedded C/C++ firmware on STM32 using the HAL. Triggers when writing peripheral drivers, handling interrupts, or setting up DMA. CX Codex +1 132installs readme-best-practices The readme-best-practices Claude Code skill guides README writing and review. It activates for a new project README, a rewrite, or a repository documentation check. CX Codex +1 121installs security-devsecops security-devsecops — a skill for Claude Code and Codex guides DevSecOps and AppSec practices across projects. Activates when handling credentials, user input, auth, or configuring CI/CD pipelines. CX Codex +1 117installs ros2-robotics The ros2-robotics Claude Code skill guides ROS 2 package and node development. It activates for work on topics, QoS, tf2, launch files, or colcon workspace tests. CX Codex +1 111installs blender-python-addon blender-python-addon — a skill for Claude Code that establishes best practices for Blender add-on development via the bpy API. Triggers when writing operators, UI panels, or bmesh routines. CX Codex +1 111installs

Project sponsors

Companies that keep this analytics open