/skill-doctor in Claude Code: clean out the skills you never use

TL;DR /skill-doctor (v2.1.252 or later) gives you one row per skill: what its description costs you every turn, how many times you have invoked it, and when. Yellow rows have never run. The ones that also carry a number under context have been charging you that many tokens every turn since you installed them. Switch them off where their source says: /skills, /plugin, /mcp or claude.ai.

You have been collecting skills for months. Some you wrote yourself, others arrived inside a plugin you installed for one afternoon's job. All of them write their description line into the system prompt on every turn, used or not, because Claude has to see a skill to be able to pick it. The cost was never the problem. The problem was that nothing told you which ones had been billing for months without doing any work. Since v2.1.252 there is a command that names them one by one.

Result (my own session, trimmed):

$ claude -p "/skill-doctor"

Skills loaded this session

  skill                                      source               context  7d tokens   uses  last used
  carousel                                   userSettings            ~130          -     0×  never
  cc-cleanup                                 userSettings             ~90          -     0×  never
  lead-magnet                                userSettings            ~100          -     0×  never
  tip-board                                  userSettings             ~50          -     0×  never
  chrome-devtools-mcp:a11y-debugging         chrome-devtools-mcp      ~80          -     0×  never
  figma:figma-generate-design                figma                   ~290          -     0×  never
  figma:figma-design-to-code                 figma                   ~180          -     0×  never
  craft:close                                craft                      -          -     0×  never
  [29 more rows]
  seo-optimize                               userSettings               -          -     4×  181 days
  svg-illustration                           userSettings             ~30          -    16×  19 days
  claude-code-tip                            userSettings             ~30      25.9m   213×  today

  context = this skill's one-line listing in the system prompt, included every turn
  (dash = not in the current listing, costs nothing; full SKILL.md loads only when it runs)
  7d tokens = tokens attributed to the skill over the last 7 days of sessions on this machine

Plugins not used recently

  figma  last used 31 days ago
  typescript-lsp  last used 18 days ago

  Manage these in /plugin

43 skills, 4,470 tokens of listing. Of those, 24 had never been invoked, and those 24 accounted for 3,020 of the 4,470. Two thirds of what I paid every turn bought work that never happened. The figma plugin on its own was fourteen skills and 2,190 tokens, and I had last opened it 31 days earlier.

How to read the table

Three things that do not jump out, and they change which rows deserve your attention.

A dash under context means free. A skill with a dash is not in the current listing, so its description never rides along in the prompt and it costs you nothing. My craft:close shows up yellow and there is nothing to switch off there. What you are hunting is yellow rows with a number.

Yellow means "never", not "not lately". The flag is zero invocations since you installed it, not a stretch of time without touching it. My seo-optimize ran 4 times 181 days ago and prints in plain white. The section that tracks elapsed time is the one at the bottom, the plugin list with its last used.

The warnings at the end cover fewer skills than the table does. Under the table Claude Code sums up what it found (4 skills loaded but never invoked. Each one adds to the system prompt every turn. Disable in /skills, or remove from .claude/skills., plus a second line for the fifteen that came from plugins). But a plugin skill only makes it into that warning if no other skill from the same plugin has ever run. That is why my four chrome-devtools-mcp skills sit yellow in the table and appear in no warning at all: two of their siblings were used. Trust the row colour, not the tally at the bottom.

How to do the cleanup

1. Pull the report

/skill-doctor

Inside a session it opens in the Stats tab of the plugin manager. If you want it as plain text, to paste somewhere or pipe through grep, run it in non-interactive mode:

claude -p "/skill-doctor"

2. Sort by what it costs you, not by how many rows there are

Yellow rows with a number, biggest context first. One 290-token skill you have never used weighs as much as three 90-token ones. The report is sorted by time since last use, not by cost, so that ordering is on you.

3. Switch it off wherever its source lives

The source column is not decoration: it tells you where that particular skill gets switched off, and there are four different places. Your own skills in ~/.claude/skills leave the listing through /skills or by deleting the folder. Plugin skills cannot be switched off one at a time: either the whole plugin goes in /plugin, or they stay. Skills from an MCP server live on the server, so switching it off in /mcp takes its tools with it. And if you synced it from claude.ai, deleting the local copy buys you nothing: it comes back on the next sync, so it has to go off over there.

Reference

This report is not a general sweep. If what you want is one pass over everything at once (skills, MCP, plugins, a bloated CLAUDE.md, slow hooks) that proposes the changes for you, that is the full /doctor checkup: that one decides and asks your permission, this one hands you the numbers and lets you decide. For the toll of whole plugins there is the "Not used recently" detector, and to see what the entire listing adds up to, /context.

And if your question is not which skills you never use but which ones are actually expensive, that is the other half: /usage breaks your consumption down by skill and by MCP in tokens spent. This report looks at the opposite face, the skills that spend nothing because they have never run and still take up room.

One warning about what you are about to switch off: a skill that has never been invoked is not always a skill you do not need. Sometimes it is written in a way Claude cannot find, and then the fix is the description, not the delete key. That ground belongs to how to write a skill that actually triggers.

Official docs: Find unused skills

Requirements: Claude Code v2.1.252 or later. The session has to receive feature flags, so you will not have it on Bedrock, Vertex or Foundry, or with telemetry turned off. Over Remote Control, from your phone or browser, it answers Skill usage reports are not available on this connection.: run it in the terminal on the machine hosting the session. The 7d tokens column comes from scanning the transcripts saved on your own disk, and it is withheld in HIPAA-regulated organizations.