Skip to main content
skill CX Codex

clash-doctor — Claude Code skill: what it does, how to install

clash-doctor diagnoses Clash Verge and mihomo connectivity, routes AI traffic, and manages TUN bypass rules directly from your agent.

MIT 142 installs ★ 300 updated 2026-10-23

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add majiayu000/spellbook --skill clash-doctor -a claude-code
Open on GitHub

What clash-doctor does

The skill inspects mihomo core health, profile routing, and active node chains via Unix sockets or the configured HTTP controller. Diagnostic checks and multi-machine sync comparisons run in read-only mode, so safe inspection never alters network settings. Any write operation requires an explicit confirmation step.

Configuration edits apply to enhancement overlays for remote targets or to local hub YAML files. The tool avoids editing raw subscription dumps and relies on tun.route-exclude-address for traffic bypasses.

Restarting Clash Verge is mandatory after updating overlays or hub YAML files, because issuing PUT /configs does not re-merge overlay rules.

What it helps with

  • diagnose proxy failures and check live mihomo kernel status
  • configure custom routing for AI tools inside remote profiles
  • exclude specific relay IP addresses from TUN handling
  • compare local hub topologies across multiple machines
  • clone and switch subscription profiles safely

Example prompts for the agent

  • Run clash-doctor status to inspect kernel state and selected nodes
  • Use clash-doctor setup-ai remote-profile to configure routing for AI tools
  • Exclude IP 192.168.1.50 from TUN using clash-doctor bypass 192.168.1.50

How to install clash-doctor

1Skills CLI (Vercel)

npx skills add majiayu000/spellbook --skill clash-doctor -a claude-code

2Manually: put the files in place

~/.claude/skills/clash-doctor/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/clash-doctor/

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

Questions about clash-doctor

How to install clash-doctor in Claude Code?

Run npx skills add majiayu000/spellbook --skill clash-doctor -a claude-code in your terminal.

What does clash-doctor do?

It diagnoses mihomo and Clash Verge routing, inspects live proxies, compares node topologies, and edits enhancement overlays.

Why does Clash Verge require a full restart after writing changes?

The PUT /configs endpoint does not re-merge enhancement overlays, so the app must be reopened for writes to take effect.

Source text

SKILL.md · MIT
---
name: clash-doctor
description: >
  Clash Verge 与 mihomo 诊断和 profile 管理。当用户遇到代理失败、需要配置
  AI 工具路由、本地 Hub 拓扑、多机对齐、TUN 绕过、克隆或切换订阅,或同步后
  配置未生效时使用。进程线路使用 clash-routes,出口 IP 质量使用 ip-check。
  普通网络测速不使用。
allowed-tools: Bash, Read, Write, Edit, Glob, Grep
metadata:
  argument-hint: '[host | profiles | status | hub | align | roles | switch-check <name> | clone <src> <dst> | setup-ai <name> | switch <name> | rustdesk <IP> | bypass <IP>]'
---

# Clash Verge Diagnostics

Inspect Clash Verge or mihomo, manage profile-specific routing, and diagnose connectivity.

## Routing

- Confirm the target profile, constraints, requested access path, and done-when signal.
- Load `references/full-guide.md` for commands, templates, and diagnosis matrices.
- Load `references/local-hub.md` before `hub`, `align`, `roles`, `clone`, `setup-ai`, or `switch`, and whenever the user says a previous sync did not apply.
- Keep the change limited to the requested target.

## Safety

- Diagnose and align are read-only. Writes require a shown summary and explicit confirmation.
- Edit enhancement overlays or the confirmed local-hub YAML. Do not edit raw subscription dumps.
- `tun.route-exclude-address` is union-only. `DIRECT` is not a TUN bypass.
- Never invent or print node IPs, credentials, subscription UIDs, or machine hostnames.
- After an overlay or hub-YAML write, quit and reopen Clash Verge. `PUT /configs` does not re-merge overlays.

## Modes

| Argument | Mode |
|---|---|
| empty or a hostname | diagnose |
| `profiles` / `list` / `ls` | list local and remote profiles |
| `status` | live kernel, TUN, and selected nodes |
| `hub` / `roles` | local-hub topology |
| `align` / `sync-check` | read-only multi-machine comparison |
| `switch-check` / `health` | pre-switch health |
| `clone` / `setup-ai` / `switch` | confirmed profile writes |
| `rustdesk` / `bypass` | TUN exclusion for a relay IP |

Resolve the named target before `setup-ai`. Apply airport-style enhancement overlays only when that target is `type: remote`; edit the named hub YAML when it is `type: local`.

## Verify

- Parse the target YAML after every write.
- Query mihomo by trying both Unix sockets and then the configured HTTP controller; fall back on request failure, not socket existence alone.
- For routes, `chains[-1]` is the matched group and `chains[0]` is the dialed node.
- Report files changed, commands run, evidence, and remaining risk.

## References

- `references/full-guide.md` — commands, templates, and diagnosis matrix
- `references/local-hub.md` — hub ownership, node roles, alignment, and landmines

© majiayu000 · MIT · majiayu000/spellbook

Similar skills

All skills for DevOps and infrastructure →

From the same set13

The whole set →
product-ux-expert product-ux-expert — a skill for reviewing interfaces against Nielsen's heuristics, building user journey maps, and auditing accessibility against WCAG 2.2 AA. CX Codex +1 212installs prd-master prd-master is a skill for writing product specifications, user stories, and acceptance criteria. It structures requirements with RICE and MoSCoW and sets measurable goals. CX Codex +1 166installs observability-sre The observability-sre skill guides monitoring, SLO design, tracing, logging, and incident response. Use it when a project needs Prometheus, Grafana, or OpenTelemetry practices. CX Codex +1 165installs database-patterns database-patterns guides AI agents on pairing PostgreSQL with Redis: schema types, indexing, JSONB usage, caching strategies, and stampede prevention. CX Codex +1 162installs trip-planner trip-planner builds detailed day-by-day travel itineraries with navigation addresses, transit times, and evening prep checklists. Useful when organizing holidays or road trips. CX Codex +1 134installs auth-security auth-security is a Claude Code skill that sets OAuth 2.1 and RFC 9700 rules for secure API auth, including PKCE, refresh token rotation, and strict JWT verification. CX Codex +1 117installs devops-excellence devops-excellence enforces DevOps best practices: eliminates root users in containers, strips static secrets, and configures OIDC in pipelines. CX Codex +1 114installs golang-web golang-web — a skill for Claude Code, Codex, and other IDEs that defines Go web application architecture. It structures projects, manages dependencies, and enforces standardized error handling. CX Codex +1 102installs

Project sponsors

Companies that keep this analytics open