/skill-doctor: find the skills costing you context

You start Claude Code, you haven’t asked for anything yet, and part of the context is already gone. On the install measured here, 117 personal skills are loaded, 108 have never been invoked, and their listing goes out again on every turn of the conversation.

What /skill-doctor actually shows

The command arrived with Claude Code 2.1.261, released on 4 September 2026. The release note announces it in one line: it shows which loaded skills go unused and what they cost in context, so you can prune them.

The documentation spells out the scope. The report covers the skills in your session, except for the skills bundled with Claude Code and enterprise skills. It flags the ones that were never invoked, shows where to disable them, and throws in a list of plugins you haven’t used recently. In an interactive session, it opens in the Stats tab of the /plugin manager. In non-interactive mode, with -p, Claude Code prints it as text.

Two conditions to know before trying it. You need Claude Code 2.1.252 or later. And from Remote Control, on phone or browser, the command refuses to answer: it returns Skill usage reports are not available on this connection. Run it in the terminal of the machine hosting the session.

Why does a skill that’s never invoked still cost context?

Because a skill loads in three stages. The open Agent Skills standard calls this progressive disclosure: at startup, the agent only reads the name and description of each skill. When a task matches that description, it reads the body of the SKILL.md. It only opens the accompanying files if it needs them. The mechanism is detailed in our guide to the SKILL.md format.

The first level, though, is paid on every conversation turn. The Claude Code documentation is explicit: every skill in the listing adds to the context on every turn, whether Claude uses it or not. And that listing has a character budget worth 1% of the model’s context window. Beyond that, Claude Code shortens the descriptions to fit the budget, at the risk of stripping out exactly the keywords that trigger the right skill.

Too many skills costs tokens, then, and degrades the triggering of the ones you actually wanted along the way.

The report, across 117 skills

On an install that loads 117 personal skills, the command prints one line per skill and a closing sentence. Non-interactive mode prints it as plain text, which makes it easy to keep :

claude -p '/skill-doctor'

Skills loaded this session

  skill                      source        context  7d tokens   uses  last used
  ab-test-setup              userSettings     ~270          -     0×  never
  cold-email                 userSettings     ~230          -     0×  never
  …
  seo-onpage                 userSettings     < 20          -     0×  never
  …
  seo-search-console         userSettings     ~190       1.2m     1×  6 days
  seo-keyword-research       userSettings     ~160      15.2m     1×  3 days
  video                      userSettings     ~210     548.4k     4×  3 days
  wp-article-thumbnails      userSettings     ~190      28.5m     8×  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

108 skills loaded but never invoked. Each one adds to the system prompt every turn.
Disable in /skills, or remove from .claude/skills.

Four columns carry the decision. context gives the weight of the listing line, the one that goes out on every turn: from under 20 to 360 tokens per skill here, around 8,800 in total. 7d tokens counts what the skill actually consumed over seven days, and shows a dash when it consumed nothing. uses and last used say the rest: of the 117 skills loaded, 108 have never been invoked, and only five consumed anything during the week.

Measuring without the command

On a version earlier than 2.1.252, or simply to cross-check the order of magnitude, level 1 can be measured directly in the files, since it’s made up of nothing but YAML frontmatter.

# Level 1 weight: name + description of each personal skill
awk 'FNR==1{f=0;p=0}
     /^---[[:space:]]*$/{f++; next}
     f!=1{next}
     /^[A-Za-z_-]+:/{p=($1=="name:"||$1=="description:"||$1=="when_to_use:")}
     p{c+=length($0)}
     END{printf "%d skills, %d caracteres, ~%d tokens\n", ARGC-1, c, c/4}' \
  ~/.claude/skills/*/SKILL.md
# 117 skills, 45715 caracteres, ~11428 tokens

The “one token for every four characters” estimate gives 11,428 tokens where the report counts around 8,800: it overestimates, which is more than enough to decide. The same calculation on ~/.codex/skills gives 7 skills and around 590 tokens: on this point, the two agents aren’t playing in the same league, as shown by our Codex vs Claude Code comparison.

The second command prints the ranking. That one is enough to decide.

awk 'FNR==1{if(NR>1) print c, d; c=0; f=0; p=0; n=split(FILENAME,t,"/"); d=t[n-1]}
     /^---[[:space:]]*$/{f++; next}
     f!=1{next}
     /^[A-Za-z_-]+:/{p=($1=="name:"||$1=="description:"||$1=="when_to_use:")}
     p{c+=length($0)}
     END{print c, d}' ~/.claude/skills/*/SKILL.md | sort -rn | head -5
# 1101 elevenlabs-game-music
# 1078 elevenlabs-game-sfx
# 864 directory-submissions
# 855 customer-research
# 831 ab-test-setup

These 117 SKILL.md files add up to 778,142 characters, or around 194,500 tokens, and the listing accounts for only 6% of that. So progressive disclosure is doing its job, and what weighs on you day to day is the number of skills. That said, 45,715 characters is in the same ballpark as the listing budget: there’s no way to know without /context whether my descriptions are already being trimmed.

Trimming what you don’t use

Open /skills, highlight a skill, press Space to cycle through the states, then Escape to save. The menu writes the skillOverrides setting itself in .claude/settings.local.json. There are four states.

name-only is the right compromise for a skill you invoke yourself now and then: the name stays in the listing, the description stops costing anything. off suits the ones you installed “just to see”.

Watch out for plugins: skills brought in by a plugin aren’t covered by skillOverrides. You need to disable the plugin from /plugin, then run /reload-plugins or restart the session for its skills to be unloaded.

Checking that the cut helped

The Skills line in /context gives the size of the listing after the budget is applied: that’s exactly what the model receives. Note it down, cut, restart the session, note it down again. If it doesn’t move even though you’ve disabled ten skills, you were probably already at the ceiling and Claude Code was truncating your descriptions. The cut will still have gained you triggering accuracy.

For the bill, /cost and /usage remain the benchmarks, but expect a modest gain: the real benefit shows up in context, not in euros. If you’re after savings of a different order of magnitude, it’s file-read routing you need to look at, as in Spotify’s write-up on hooks.

Two settings let you widen the budget instead of cutting: skillListingBudgetFraction (for example 0.02 for 2%) and the SLASH_COMMAND_TOOL_CHAR_BUDGET environment variable, which sets a number of characters. Widening it just moves the problem: the context you save on skills is lost elsewhere.

What to remember

• A skill that’s never invoked still costs its name and description on every turn: that’s level 1 of progressive disclosure.
• /skill-doctor requires Claude Code 2.1.252 or later, and shows up in the Stats tab of the /plugin manager.
• The report counts 117 skills loaded here, 108 never invoked, around 8,800 tokens of listing. Two lines of awk on ~/.claude/skills/*/SKILL.md give the same order of magnitude without the command.
• You cut with /skills and the Space key. Plugin skills are cut from /plugin, then /reload-plugins.
• You check on the Skills line of /context, which reflects the budget actually applied.