How to read this manual
Each command gets its own section with three blocks: Scenario (when to reach for it), Usage (the command and common flags), Effect (the dark terminal block below is a real, colorized screenshot of the run).
Conventions: --scope project scopes to the current repo and avoids touching global config; --json emits machine-readable output for CI. The example project contains 1 duplicate skill, so you will see "data-exporter has 2 copies" appear in several places.
Install & Run Install & Run
Scenario
skill-doctor is a local CLI that audits skills installed by AI coding assistants (Claude Code / Codex / Copilot / Cursor / WorkBuddy / InfCode, etc.): duplicates, conflicts, security risks, and context cost. Install it once and use it in any project directory.
Usage
| Option | Description |
|---|---|
| npm i -g @evilstar2025/skill-doctor | Install globally, then use the `skill-doctor` command directly. |
| npx @evilstar2025/skill-doctor <cmd> | Run a command on the fly without installing. |
| skill-doctor --version | Print the version (this manual targets 0.6.0). |
Notes
Requires Node.js ≥ 20. Every command accepts `--json` for machine-readable output, which is convenient for CI. The examples in this manual run against a sample project that intentionally puts a skill named `data-exporter` into both `.claude` and `.github` (creating 1 duplicate) and also contains `code-reviewer` for diff demos.
Effect
$ skill-doctor --version 0.6.0
skill-doctor --help Overview: --help
Scenario
First time using it, or when you forget a sub-command or flag? Check --help first. It lists every command and option and serves as the index.
Usage
| Option | Description |
|---|---|
| -h / --help | Works for any sub-command, e.g. `skill-doctor conflicts --help`. |
| -v / --version | Print just the version. |
Notes
Below is the real output of --help on this machine, which you can use as a cheat sheet.
Effect
$ skill-doctor --help skill-doctor Usage: skill-doctor scan [--scope project|global|all] [--strategy token|embedding] [--threshold N] [--embedding-model ID] [--json] [--report [path]] skill-doctor show <name> [--json] skill-doctor conflicts [--scope project|global|all] [--strategy token|embedding] [--threshold N] [--embedding-model ID] [--analyze] [--kind duplicate|conflict|all] [--fail-on high|med|low] [--limit N] [--json] skill-doctor audit [--scope project|global|all] [--severity high|med|low] [--fail-on high|med|low] [--ai] [--no-cache] [--json] [--report [path]] skill-doctor check [--scope project|global|all] [--fail-on high|med|low] [--budget-tokens N] [--json] skill-doctor cleanup [--scope project|global|all] [--json] skill-doctor cost [project-dir] [--platform PLATFORM] [--scope project|global|all] [--source skill|mcp|all] [--resource all|agents|skill|mcp|plugin|memory] [--codex-config path] [--show-disable] [--include-cache] [--tokenizer openai|approx] [--tokenizer-model model] [--budget-tokens N] [--platform-budget platform=N] [--fail-on-budget] [--json] skill-doctor context [project-dir] [--platform PLATFORM] [--scope project|global|all] [--source skill|mcp|all] [--resource all|agents|skill|mcp|plugin|memory] [--codex-config path] [--show-disable] [--include-cache] [--tokenizer openai|approx] [--tokenizer-model model] [--budget-tokens N] [--platform-budget platform=N] [--fail-on-budget] [--json] skill-doctor context enable|disable --id <resource-id> [--platform codex] [--codex-config path] [--json] skill-doctor diff <skill-a> <skill-b> [--report [path]] skill-doctor ui [project-dir] [--port N] [--no-open] skill-doctor dashboard [--scope project|global|all] [--report [path]] [--open] skill-doctor install <path|slug> [--target <platform>] [--link] skill-doctor uninstall <name> [--target <platform>] [--force] skill-doctor center migrate|show skill-doctor config view [--json] skill-doctor config set analysis|embedding --base-url <url> --model <model> [--api-key <key>] [--timeout-ms <n>] [--clear-api-key] skill-doctor config test [--service analysis|embedding] skill-doctor --version Model config file: ~/.skill-doctor/config.json { "analysis": { "baseUrl": "http://host/v1", "model": "gpt-4o", "apiKey": "..." }, "embedding": { "baseUrl": "http://host/v1", "model": "bge-m3", "apiKey": "..." } } Platforms: --platform values: claude|cursor|copilot|codex|gemini|windsurf|trae|opencode|kiro|openclaw|hermes|workbuddy|infcode|unknown (aliases: claudecode->claude, claude-code->claude)
scan scan — list installed skills
Scenario
When you want to know which skills are installed in the current project, on which platforms, and whether any duplicates or conflicts exist — run `scan` first. It is the starting point for all subsequent diagnostics.
Usage
| Option | Description |
|---|---|
| --scope project|global|all | Scan scope; default `all`. The manual examples use `project` to limit the scan to the current repo. |
| --group | Use an LLM to group skills by topic (requires a configured analysis model). |
| --strategy token|embedding | Conflict-detection strategy; default `token` (local, offline). |
| --report [path] | Also export a visual HTML report. |
| --json | Emit structured JSON for script consumption. |
Notes
The example finds 3 skills (claude × 2, copilot × 1) and reports 1 duplicate. `--report` writes scan-report.html (a real sample ships with this manual).
Effect
$ skill-doctor scan --scope project SKILL DOCTOR REPORT Total skills installed: 3 Duplicates detected: 1 Conflicts detected: 0 Platforms: - claude: 2 - copilot: 1 Skills: - code-reviewer platform: claude scope: project install source: .claude/skills confidence: high repository: — author: — - data-exporter platform: claude scope: project install source: .claude/skills confidence: high repository: — author: — - data-exporter platform: copilot scope: project install source: .github/skills confidence: high repository: — author: —
$ skill-doctor scan --scope project --report scan-report.html Report written to: E:/tmp/sd-manual-demo/caps/scan-report.html
show <name> show — inspect one skill
Scenario
After scanning a pile of skills, drill into one: its source path, description, trigger conditions (When to Use), and other semantically similar skills.
Usage
| Option | Description |
|---|---|
| <name> | Skill name (required), e.g. `data-exporter`. |
| --json | Emit structured JSON. |
Notes
In the real output below, RELATED SKILLS reports a similarity of 0.25 with another `data-exporter` — that is exactly the lead you follow for duplicate / conflict investigations.
Effect
$ skill-doctor show data-exporter SKILL: data-exporter Platform: claude | Scope: project Source: E:\tmp\sd-manual-demo\.claude\skills\data-exporter\SKILL.md PROVENANCE Install source: .claude/skills Scope: project Confidence: high Repository: — Author: — DESCRIPTION Export database tables and SQL query results to CSV and Parquet files for downstream analysis and reporting. WHEN TO USE → Exporting a Postgres table to CSV → Dumping the result of an ad-hoc SQL query for reporting → Writing Parquet files for a data pipeline → Export database tables and SQL query results to CSV and Parquet files for downstream analysis and reporting. RELATED SKILLS data-exporter similarity: 0.25 shared: analysi, csv, data
conflicts conflicts — detect duplicates & conflicts
Scenario
When you suspect different platforms/directories hide same-named or highly similar skills (which overwrite each other and waste context), `conflicts` finds them and suggests "delete which, keep which".
Usage
| Option | Description |
|---|---|
| --scope project|global|all | Scan scope, default `all`. |
| --kind duplicate|conflict|all | Filter by kind; `duplicate` = same name, `conflict` = semantically similar. |
| --fail-on high|med|low | Exit with code 1 when severity reaches this level — for CI gating. |
| --limit N | Show at most N items. |
| --strategy / --threshold / --embedding-model | Same as `scan`; controls detection precision. |
Notes
The real output finds 2 copies of `data-exporter` and recommends removing the older one (the one under `.github`). In CI, add `--fail-on high` so any duplicate fails the build.
Effect
$ skill-doctor conflicts --scope project DUPLICATES data-exporter [2 copies] E:\tmp\sd-manual-demo\.claude\skills\data-exporter\SKILL.md E:\tmp\sd-manual-demo\.github\skills\data-exporter\SKILL.md SUGGESTIONS consider removing: E:\tmp\sd-manual-demo\.github\skills\data-exporter\SKILL.md keep: E:\tmp\sd-manual-demo\.claude\skills\data-exporter\SKILL.md (newer (modified 2026-08-07))
audit audit — security audit
Scenario
Before shipping skills to the team or CI, you want to know whether they contain obvious security risks (dangerous shell commands, suspicious network calls, etc.). Without `--ai`, the audit runs on local rules with zero configuration.
Usage
| Option | Description |
|---|---|
| --scope project|global|all | Scan scope, default `all`. |
| --severity high|med|low | Only show findings of this severity or higher. |
| --ai | Use the configured analysis model for a deeper scan (requires `config set analysis` first). |
| --no-cache | Ignore the AI audit cache and re-analyze. |
| --report [path] | Export a visual HTML audit report. |
Notes
The 3 example skills do not trigger any local rule, so the result is "No findings". As soon as a skill containing dangerous instructions is installed, the exact risk and severity will appear here.
Effect
$ skill-doctor audit --scope project Skill Safety Audit — 3 skills scanned No findings.
check check — one-shot health gate (CI favorite)
Scenario
In CI or pre-commit, run one command that combines: security risks, skill conflicts, and whether context budget is exceeded — and returns pass/fail with an exit code. More convenient than running audit + conflicts + cost separately.
Usage
| Option | Description |
|---|---|
| --scope project|global|all | Scan scope, default `all`. |
| --fail-on high|med|low | Severity threshold (default `high`); exit 1 when reached. |
| --budget-tokens N | Per-turn token budget; exceeding it counts as failure. |
| --json | Emit structured output for pipelines to parse. |
Notes
Real output: failed — security 0, conflicts 1, budget not exceeded. Because a duplicate was found, the check failed — perfect as a pre-merge gate.
Effect
$ skill-doctor check --scope project --fail-on high Project check: failed Security findings: 0 Conflicts: 1 Context over budget: no
cleanup cleanup — remove duplicate skills
Scenario
Once `conflicts` tells you there are duplicates, `cleanup` lists every duplicate copy and can — with `--execute` — interactively remove them one by one, reclaiming both disk and context.
Usage
| Option | Description |
|---|---|
| --scope project|global|all | Scan scope, default `all`. |
| --execute | Enter interactive mode (default is read-only listing only). |
| --json | Emit the cleanup list as JSON for scripts. |
Notes
Without `--execute`, this is a safe read-only preview. With `--execute`, it asks you `[1/2/s]` for each duplicate (press `s` to skip). The demo output is the preview.
Effect
$ skill-doctor cleanup --scope project DUPLICATE SKILLS 1 duplicate found. Run with --execute to remove interactively. data-exporter [1] E:\tmp\sd-manual-demo\.claude\skills\data-exporter\SKILL.md [2] E:\tmp\sd-manual-demo\.github\skills\data-exporter\SKILL.md
cost / context cost — estimate the context tax
Scenario
Skills, MCP servers, and Agent config silently inflate every conversation, burning tokens and money. `cost` breaks down per-platform/per-resource "how many tokens per turn" and grades you against the budget; the `context` sub-command can also enable/disable Codex resources.
Usage
| Option | Description |
|---|---|
| [project-dir] | Project directory to analyze (default: current). |
| --platform <p> | Limit to a single platform (claude/codex/copilot/...). |
| --source skill|mcp|all | Restrict to skills / MCP / everything. |
| --budget-tokens N | Per-turn budget; over-budget rows are flagged. |
| --fail-on-budget | Exit with code 1 when over budget. |
| --tokenizer openai|approx | Tokenizer; default `openai` (precise). |
| context enable|disable --id <id> | Enable/disable a Codex context resource. |
Notes
Real output: ~392 tokens/turn, broken down per platform (copilot/claude) and per skill, graded A (within budget). A great lever to fight "AI gets more expensive the more you use it".
Effect
$ skill-doctor cost --scope project CONTEXT COST REPORT Project: E:\tmp\sd-manual-demo Scope: project (current project only) Estimated token tax: 392 tokens/turn Tokenizer: openai model=gpt-4o encoding=o200k_base Budget: 2000 tokens/turn Grade: A (within budget) Items scanned: 5 By coding agent: - copilot: 236 tokens/turn (3 items) budget: 2000 grade: A (within budget) startup: 236 always-on: 0 activation risk: 241 - claude: 156 tokens/turn (2 items) budget: 2000 grade: A (within budget) startup: 156 always-on: 0 activation risk: 158 Highest cost items: - data-exporter tokens: 80 platform: claude scope: project source: skill kind: claude-skill-description activation: startup budget: startup-selection activation tokens: 83 confidence: high path: E:\tmp\sd-manual-demo\.claude\skills\data-exporter\SKILL.md fix: OK - data-exporter tokens: 80 platform: copilot scope: project source: skill kind: agent-skill-description activation: startup budget: startup-selection activation tokens: 83 confidence: high path: E:\tmp\sd-manual-demo\.github\skills\data-exporter\SKILL.md fix: OK - data-exporter tokens: 80 platform: copilot scope: project source: skill kind: agent-skill-description activation: startup budget: startup-selection activation tokens: 83 confidence: high path: E:\tmp\sd-manual-demo\.claude\skills\data-exporter\SKILL.md fix: OK - code-reviewer tokens: 76 platform: claude scope: project source: skill kind: claude-skill-description activation: startup budget: startup-selection activation tokens: 75 confidence: high path: E:\tmp\sd-manual-demo\.claude\skills\code-reviewer\SKILL.md fix: OK - code-reviewer tokens: 76 platform: copilot scope: project source: skill kind: agent-skill-description activation: startup budget: startup-selection activation tokens: 75 confidence: high path: E:\tmp\sd-manual-demo\.claude\skills\code-reviewer\SKILL.md fix: OK
diff <a> <b> diff — compare two skills
Scenario
You want to know exactly how two skills differ (to merge, replace, or discover they are the same thing under different names). `diff` lays out their fields and trigger conditions side by side.
Usage
| Option | Description |
|---|---|
| <skill-a> <skill-b> | Two skill names (required). |
| --report [path] | Export a visual HTML comparison report. |
Notes
When no analysis model is configured, `diff` falls back to "fields only" mode (see the notice in the real output below). Once a model is configured, it also gives a semantic interpretation of the differences.
Effect
$ skill-doctor diff data-exporter code-reviewer ┌──────────────────────────────────────────────────────────┐ │ Skill Diff: data-exporter vs code-reviewer └──────────────────────────────────────────────────────────┘ ⚠ LLM analysis unavailable — showing extracted fields only. ── 触发条件 ──────────────────────────────────────────────────── data-exporter - Exporting a Postgres table to CSV - Dumping the result of an ad-hoc SQL query for reporting - Writing Parquet files for a data pipeline code-reviewer - Reviewing a GitHub pull request for SQL injection risks - Checking a diff for performance regressions - Enforcing project style rules on new code
ui ui — launch the web dashboard
Scenario
When you prefer a clickable web UI over the terminal — with overview, conflicts, context cost, and the skill library at a glance — `ui` starts a local web server with session-based auth.
Usage
| Option | Description |
|---|---|
| [project-dir] | Project directory to analyze (default: current). |
| --port N | Listen port; default: random. |
| --no-open | Do not auto-open the browser (server still starts). |
Notes
After starting, the CLI prints a local URL with a session token (see the real output below). Open it in a browser to use the full UI; press Ctrl+C to stop.
Effect
$ skill-doctor ui --port 4173 --no-open Skill Doctor UI: http://127.0.0.1:4173/session/RJebkCY4F_lOCXp6llb3m1dIJcSdrPoEKdXIb7t6mOg Press Ctrl+C to stop.
dashboard dashboard — export a static overview report
Scenario
You do not want to run a server — just export a single-file HTML overview (skills, conflicts, audit, duplicates, cleanup suggestions) to share or commit.
Usage
| Option | Description |
|---|---|
| --scope project|global|all | Scan scope, default `all`. |
| --report [path] | Export HTML; default path is `dashboard.html`. |
| --open | Auto-open the report in a browser after generation. |
Notes
Even without `--report`, dashboard.html is written. A real sample of it ships as an appendix of this manual.
Effect
$ skill-doctor dashboard --scope project --report dashboard.html Dashboard written to: E:/tmp/sd-manual-demo/caps/dashboard.html
install / uninstall install / uninstall — manage skills
Scenario
You have a local skill directory (or a marketplace slug) and want to install it into a specific AI platform directory, then later uninstall it. Both operations are recorded in the unified skill center (center.json).
Usage
| Option | Description |
|---|---|
| <path|slug> | Local path or marketplace slug (required). |
| --target <platform> | Target platform; auto-detected when omitted. |
| --link | Install as a symlink (handy while developing). |
| uninstall <name> --target <p> | Uninstall a skill by name. |
| --force | Force uninstall even if other references exist. |
Notes
The example below uses an isolated environment (a temporary HOME) and shows: install `data-exporter` into claude → center.json immediately records the skill and its installation → force-uninstall removes the record.
Effect
$ skill-doctor install ./data-exporter --target claude # then uninstall ✓ Installed 'data-exporter' to claude Path: E:\tmp\sd-manual-home\.claude\skills\data-exporter\SKILL.md --- center.json after install --- { "version": 1, "skills": [ { "id": "64b7eb3b082ca5f6952d1cd772e24fa97541d4becb47e797e3c4f2e5840a4e52", "name": "data-exporter", "rootPath": "E:\\tmp\\sd-manual-home\\.claude\\skills\\data-exporter", "source": { "type": "local", "originalPath": "E:\\tmp\\sd-manual-demo\\.claude\\skills\\data-exporter\\SKILL.md" }, "treeHash": "sha256:e838245632383828c2414edbcd112ab773292d084065bda76ba58aa2e8650843", "addedAt": "2026-08-07T06:15:07.251Z", "updatedAt": "2026-08-07T06:15:07.251Z", "installations": [ { "id": "7a2d3e1a42503025822ddb949e43383b51a998e25234c3917b7d337e511d5166", "targetId": "claude-global-skills", "platform": "claude", "scope": "global", "mode": "copy", "installedPath": "E:\\tmp\\sd-manual-home\\.claude\\skills\\data-exporter\\SKILL.md", "installedRootPath": "E:\\tmp\\sd-manual-home\\.claude\\skills\\data-exporter", "deployedHash": "sha256:e838245632383828c2414edbcd112ab773292d084065bda76ba58aa2e8650843", "installedAt": "2026-08-07T06:15:07.250Z" } ] } ] } ✓ Uninstalled 'data-exporter' from claude --- center.json after uninstall (forced) --- { "version": 1, "skills": [] }
center center — the unified skill center
Scenario
skill-doctor uses `center.json` as the single source of truth for skills and their installation records. Older data (catalog/deployments/registry) must be migrated in once; `show` then prints the whole picture.
Usage
| Option | Description |
|---|---|
| center migrate | Migrate legacy data into center.json (idempotent, re-runnable). |
| center show | Print the entire center.json as JSON. |
Notes
`migrate` output shows 34 skills migrated, 1 installation record, no backup (the machine was already in center format). The `show` output is long; only the first entries are shown below (34 skills in total on this machine).
Effect
$ skill-doctor center migrate Migrated to center.json: skills: 34 installations: 1 backups: (none)
$ skill-doctor center show { "version": 1, "skills": [ { "id": "8f03cf43-2c5b-446c-a818-4bc49e531f93", "name": "agent-evaluator", "rootPath": "E:\\GitHub\\skills\\.claude\\skills\\agent-evaluator", "source": { "type": "local", "originalPath": "E:\\GitHub\\skills\\.claude\\skills\\agent-evaluator" }, "treeHash": "sha256:65200faa99549113977205cef59cf1ba2bf9eb6b714e45d5d7bc4100b9c3f4d1", "addedAt": "2026-07-27T00:57:35.725Z", "updatedAt": "2026-07-27T00:57:35.725Z", "installations": [] }, { "id": "d4f52402-2de4-403d-8f2f-cbe32a396162", "name": "ai-image-asset-generator", "rootPath": "E:\\GitHub\\skills\\.claude\\skills\\ai-image-asset-generator", "source": { "type": "local", "originalPath": "E:\\GitHub\\skills\\.claude\\skills\\ai-image-asset-generator" }, "treeHash": "sha256:651252f7b73f130fd5e2c306a0e340e47c1cb32c76fe90add2ab04df789fda3e", "addedAt": "2026-07-27T00:57:35.773Z", "updatedAt": "2026-07-27T00:57:35.773Z", "installations": [] }, { …（已省略剩余技能，本机 center.json 共 34 个技能）
config config — configure analysis / embedding models
Scenario
To unlock skill-doctor's AI-enhanced capabilities (semantic interpretation in `show`, embedding strategy in `conflicts`, `audit --ai`, semantic differences in `diff`), first configure an OpenAI-compatible analysis model in `~/.skill-doctor/config.json` (optionally an embedding model too).
Usage
| Option | Description |
|---|---|
| config view | View the current model configuration. |
| config set analysis|embedding --base-url <url> --model <m> | Set the analysis/embedding model endpoint and name. |
| --api-key <key> | Set the API key (or rely on the environment variable). |
| --clear-api-key | Clear a stored API key. |
| config test [--service analysis|embedding] | Connectivity self-test. |
Notes
The real output below shows the machine is not configured yet. Once configured, `show`, `conflicts --strategy embedding`, `audit --ai`, and `diff` will gain the corresponding smart features.
Effect
$ skill-doctor config view Model configuration (~/.skill-doctor/config.json): analysis: not configured embedding: not configured
$ skill-doctor config set analysis --base-url <url> --model <model> Usage: skill-doctor config set analysis|embedding --base-url <url> --model <model> [--api-key <key>] [--timeout-ms <n>] [--clear-api-key]