Claude Code's /skill-doctor Prices Your Skills in Context Tokens. The Price Is Not a Verdict.

What the new command actually measures, why an unused skill is usually a description problem, and the three-way choice most people never notice they have

Claude Code shipped a command on September 4 whose only job is to tell you that some of what you installed is wasting your money. /skill-doctor shows which loaded skills go unused and what they cost in context, so you can prune them. That is the entire changelog line for it in version 2.1.261, published to npm at 17:49 UTC.

Two days later, a Hacker News thread titled "How do you manage skills files?" pulled 301 points and 269 comments. The question was not how to write a skill. It was how to find them, keep them organized, and confirm they still work. Skills stopped being an authoring problem sometime this summer and became a portfolio problem, and a portfolio problem has a very specific failure mode: you start optimizing the number you can see.

Here is the thing about /skill-doctor. The number it gives you is real, it is worth having, and it answers a question nobody was actually asking.

What the command is measuring

Skills in Claude Code are not lazily streamed the way people often assume. The docs are direct about the mechanism: when you or Claude invoke a skill, the rendered SKILL.md content enters the conversation as a single message and stays there across later turns. Claude Code does not re-read the file on subsequent turns. It is sitting in the transcript. Every line of it is in every request you send for the rest of the session.

Anthropic's own guidance puts it in one sentence: "Once a skill loads, its content stays in context across turns, so every line is a recurring token cost."

That is why the command exists and why it is worth running. A skill you wrote in a hurry, with three paragraphs of preamble explaining your reasoning to a future reader, is charging you for those three paragraphs on every turn from the moment it fires until the session ends or gets compacted. Multiply by a session that runs four hours and it is not a rounding error.

There is one refinement worth knowing. If Claude re-invokes a skill whose rendered content is identical to the copy already in context, Claude Code adds a short note that the skill is already loaded rather than appending a second copy. If the rendered content differs, because arguments changed or an injected command produced new output, it appends the full content again. So a skill with variable content costs more than its file size suggests, and a static one costs less than repeated invocations would imply. /skill-doctor is measuring what actually landed, which is the right thing to measure.

Why the report will mislead you

The command reports two things: did this skill fire, and what did it cost. From those two facts most people will construct a third, which the command never said: is this skill worth keeping.

That inference breaks in both directions.

A skill can fail to fire because it is useless. A skill can also fail to fire because Claude never knew it applied. Those look identical in the report and they need opposite responses.

The mechanism here is the description field in the frontmatter. Per the docs, the description is what helps Claude decide when to load the skill automatically. It is the only part of the skill the model sees before deciding whether to pull the rest into context. A skill with a beautifully written body and a vague description is invisible. It will show up in /skill-doctor as zero invocations, near-zero cost, and it will look exactly like dead weight.

I have written skills that fell into this trap and the tell is always the same: I can describe out loud, precisely, when I want the thing to fire, and my description field says something like "helps with API work." The model is not being obtuse. It is doing pattern matching against a sentence I wrote carelessly because I already knew what I meant.

The other direction is subtler. A skill can fire constantly and be actively bad for you, and it will look like a healthy, well-earning line item. Frequency is not correctness. /skill-doctor will happily report that your over-eager formatting skill loaded in every session, cost you 900 tokens a turn, and was worth it, which is a claim the command has no way to make.

The three-way choice nobody uses

The obvious response to a /skill-doctor report is binary. Keep or delete. Claude Code has a third option and almost nobody reaches for it.

You can set disable-model-invocation: true in a skill's frontmatter. The skill stays installed, stays typeable as /whatever, and stops being something Claude reaches for on its own. If you do not want to edit the file, skillOverrides accepts "user-invocable-only" from settings, which does the same thing from outside.

This is the correct answer for the largest category in most people's report: the skill you genuinely need, four times a month, that you know by name. It costs you nothing while it sits idle. It costs you nothing in false invocations. And it is there when you type it.

The category that actually deserves deletion is narrow: skills that fire, cost real context, and you cannot remember why you installed them. That is a much shorter list than the report's zero-invocation column, and confusing the two is how a team ends up deleting the deploy skill they use once a quarter and keeping the one that hijacks every code review.

Put this into practice

The whole audit takes about fifteen minutes and you should do it in a project where your skills directory has grown past the point where you can name every entry from memory.

Run it on a session that did real work, not a fresh one. /skill-doctor reports on what loaded. If you run it in an empty session you get a report about nothing. Open a project, do a normal hour of work, then run it. The report is only as good as the session it describes.

Sort the output into three piles, not two. Fired and you value it: leave it alone. Fired and you cannot justify it: delete it, and this pile is where deletion belongs. Never fired: do not touch it yet. That third pile is the one that needs the next step.

For everything in the never-fired pile, read your own description field before you decide anything. Ask whether you could tell, from that sentence alone and nothing else, when this skill should run. If the answer is no, the skill was never tested. Rewrite the description with concrete trigger phrases, the words you would actually type, and give it a week. If the answer is yes and it still never fires, then you have learned something real.

Move the rare-but-real skills to user-invoked. Add disable-model-invocation: true to the frontmatter, or set "user-invocable-only" in skillOverrides if the skill came from a plugin or a sync you would rather not edit. You keep the capability and stop paying the auto-invocation tax on it.

Then attack the bodies of the survivors, not the count. The docs are explicit that the body persists across turns, so the highest-value edit in most skill directories is not deleting a skill, it is cutting the explanatory prose out of the three skills that fire every session. State what to do. Skip the narration about why. A skill that goes from 1,100 tokens to 400 and still fires correctly is worth more than deleting four skills that never loaded in the first place.

One more thing, from the same docs page and easy to miss during a cleanup: a skill's allowed-tools grant applies whenever you or Claude invoke it, including in a -p run inside a folder you have never trusted. If you are auditing skills anyway, read the allowed-tools of anything checked into a repository you did not write. A skill can grant itself broad tool access, and that is a separate problem from what it costs.

What this does not fix

/skill-doctor measures cost. It does not measure value, quality, correctness, or overlap, and treating its output as a quality signal is the specific mistake this article exists to prevent.

It cannot tell you that two of your skills give contradictory instructions and the one that fires second wins. It cannot tell you that a skill fired and produced a worse result than no skill at all. It cannot tell you whether a skill that never fired would have been the right one for a task Claude fumbled. It reports on what happened in a session, so it inherits every bias of the work you happened to do that day, and one atypical session produces a misleading report.

It also cannot see the cost that is not a skill. If your context is under pressure, skills are rarely the biggest line. Tool output, file reads, and MCP server tool schemas usually dominate, and the same release that added /skill-doctor also added bashOutputMaxChars and taskOutputMaxChars to raise how much output lands inline before it spills to a file, up to 128K characters. Raising that number is the opposite trade from pruning skills. Both are context spending decisions and neither command tells you which one you should be making.

And the honest caveat about the audit itself: pruning has a floor. Once you have cut the prose from your three hot skills and moved the rare ones to user-invoked, you are done. There is no version of this where you keep finding savings every week, and a team that turns skill auditing into a recurring ritual has invented a new way to avoid writing software.

The part worth keeping

The reason this command matters is not the tokens. It is that it turns an argument into a measurement. Every team running agents has had the same unresolvable conversation about whether all this configuration is helping, conducted entirely in vibes, and now one half of it has a number attached.

Use the number for what it is. It tells you what you are spending. It does not tell you what you are getting, and the gap between those two is where your judgment still has to live. Run the report, sort into three piles instead of two, and be more suspicious of the skills that fire constantly than the ones that never do.

Sources: Claude Code changelog (version 2.1.261, publish timestamp from the npm registry); Claude Code skills documentation; Ask HN: How do you manage skills files?, posted 2026-09-06, 301 points and 269 comments as of this writing.

Medium metadata

Title: Claude Code's /skill-doctor Prices Your Skills in Context Tokens. The Price Is Not a Verdict.
Subtitle: What the new command actually measures, why an unused skill is usually a description problem, and the three-way choice most people never notice they have
Tags: Claude Code, AI Agents, Developer Tools, Prompt Engineering, Software Engineering
Suggested kicker image: a single utility meter on a bare wall, dial mid-sweep, hard side light
Canonical: import from the fervorai.dev URL