How do I use Claude Code /skill-doctor?

Use Claude Code /skill-doctor to diagnose skill and plugin issues. Version floor from CHANGELOG 2.1.261; keep [GAP] honest if CLI untested.

Run /skill-doctor in a Claude Code terminal session to see what each loaded skill costs in context and how often it’s used, then turn off the unused ones. CHANGELOG first lists it under 2.1.261; the commands/skills docs say v2.1.252+ with feature-flag fetching. It is not /doctor (broader setup checkup) and not /context (live context grid).

TL;DR. Type /skill-doctor on the host terminal. Interactive sessions open the report in the /plugin manager Stats tab; -p prints text. Prune with /skills / skillOverrides, or /plugin for plugins. Remote Control phone/browser can’t run the report.

Prerequisites

A recent Claude Code CLI - check with claude --version. Prefer ≥ 2.1.261 (CHANGELOG add). Docs floor is v2.1.252+ plus feature-flag fetching. [GAP · 2026-09-14]: claude was not on PATH in the drafting environment, so the live --version string wasn’t captured.
Feature-flag fetching on - docs: /skill-doctor isn’t available in sessions that skip feature-flag fetching.
Terminal on the host machine - if you run /skill-doctor over Remote Control from phone or browser, Claude Code replies that skill usage reports aren’t available on that connection. Run it in the terminal where the session is hosted.

Run `/skill-doctor`

Start (or attach to) a Claude Code session in the terminal.
Type:

/skill-doctor

Interactive: the report opens in the /plugin manager Stats tab (skills docs - Find unused skills).
Non-interactive (-p): Claude Code prints the report as text.

What the report covers (official skills docs):

Skills in your session other than bundled skills and enterprise skills
Unused skills in the listing, with context cost - start with the highest-cost unused ones
Plugins you haven’t used recently (so you can disable/uninstall via /plugin)

No extra CLI flags are documented for /skill-doctor beyond invoking the command itself. Don’t invent ones from blogs.

What to do with the report

Prefer pruning before raising budgets.

Turn off highest-cost unused skills first - the report flags them and points you where to turn them off.
Personal / project skills: open /skills, filter if needed, press Space (or Enter) to cycle visibility. That writes skillOverrides in settings. Documented values:

Override	Claude listing	`/` menu
`"on"`	Name + description	Yes
`"name-only"`	Name only	Yes
`"user-invocable-only"`	Hidden	Yes
`"off"`	Hidden	Hidden

Plugin skills: skillOverrides does not affect them. Use /plugin to disable or uninstall.
Only after pruning: if the Skills listing is still tight, skills docs mention raising the listing budget (skillListingBudgetFraction, skillListingMaxDescChars, or env SLASH_COMMAND_TOOL_CHAR_BUDGET). Description listing is capped at 1,536 chars per entry. Check the Skills row in /context for listing size after budget.

If you’re drowning in marketing plugins and need a pick order rather than a prune order, see What Claude marketing skills to install first. After you keep a plugin, how to run claude plugin eval is the next ops step.

`/skill-doctor` vs `/doctor` vs `/context`

Command	Scope	When to use
`/skill-doctor`	Skills-focused cost + usage - find skills (and unused plugins) to turn off	Listing budget pressure; many personal/project/plugin skills
`/doctor` (`/checkup`)	Broader setup checkup: install/PATH, unused skills/MCP/plugins vs cost, slow hooks, CLAUDE.md trim, and more - reports first, asks before changing	“Something’s wrong with my setup” / declutter CLAUDE.md
`/context`	Live context grid; Skills row = listing size after budget	See what’s filling the window right now

Same family of “why is my context heavy?” questions; different jobs. Don’t run /doctor expecting only a skills cost table, and don’t expect /skill-doctor to trim CLAUDE.md.

Pitfalls

Unknown command - upgrade toward 2.1.261+ (or at least the docs 2.1.252+ floor) and ensure feature flags aren’t disabled.
Remote Control only - report isn’t available on that connection; use the host terminal.
Confusing with /doctor - doctor may also surface unused skills among many other checks; skill-doctor is the focused cost/usage report.
Turning off skills you still invoke by name - "off" hides from Claude and the / menu; use "user-invocable-only" or "name-only" when you still want manual /skill-name.
Leaving plugin skills alone via skillOverrides - won’t work; use /plugin.

For a reflection-after-acting pairing after you prune and keep working, see Skill of the day: discernment-nudge.

FAQ

What version do I need?
Cite both: CHANGELOG adds /skill-doctor under 2.1.261; commands/skills docs require v2.1.252+ and feature-flag fetching. Run claude --version on your machine ([GAP] here if CLI missing).

Does /skill-doctor change files automatically?
No. It reports. You turn skills off via /skills / skillOverrides, or manage plugins via /plugin. /doctor is the one that can propose fixes after confirmation.

Why is Skills cost still high after pruning?
Listing budget and per-entry description length (1,536-char cap). Check /context Skills row after budget; raise budget knobs only after pruning.

Can Claude invoke /skill-doctor for me?
You run the slash command. The report is for human prune decisions.

Unused plugin skills?
The report may list plugins you haven’t used recently. Disable or uninstall through /plugin, not skillOverrides.

Sources (checked 2026-09-14)

anthropics/claude-code CHANGELOG.md · 2.1.261 - Added /skill-doctor to show which loaded skills go unused and what they cost in context, so you can prune them
Commands reference - /skill-doctor - cost + usage; requires v2.1.252+ and feature-flag fetching
Extend Claude with skills - Find unused skills - Stats tab / -p text; non-bundled/non-enterprise; unused plugins; Remote Control limitation; skillOverrides; listing budget
Local: claude --version - CLI not found ([GAP])

Also see Create a Claude Code skill and Claude Skills.