The Claude Code skill doctor command is /skill-doctor, added in Claude Code v2.1.261 on 4 September 2026, and it does one specific job: it shows which of your loaded skills go unused and what each one costs you in context, so you can prune the dead weight. If your Claude Code sessions have been feeling heavier as your skills folder has grown, this is the diagnostic that tells you exactly which skills are earning their place and which are just burning tokens on every request. Here is what it reports, why context cost from idle skills is a real problem for automation workflows, and how to run a sensible pruning pass.
📺 Watch: Claude AI SEO: How to Rank #1 FAST
🔥 Get the Agent OS as a free bonus: AI Profit Boardroom members get the full Agent OS zip, prompt libraries, daily tutorials and weekly live coaching calls. → Get inside · Want AI SEO help 1-on-1? Book a free SEO strategy session →
What the Claude Code Skill Doctor Command Actually Does
The official Claude Code changelog entry for v2.1.261, published on 4 September 2026, describes the feature in one line: "Added /skill-doctor to show which loaded skills go unused and what they cost in context, so you can prune them." Two separate pieces of information matter there.
First, usage: the command surfaces which loaded skills are actually being used, versus loaded but sitting idle. Skills are packaged instruction sets — deploy steps, review checklists, house styles, repo workflows — and every one you enable is a bet that it will trigger often enough to be worth carrying. The skill doctor settles that bet with data instead of guesswork.
Second, cost: every loaded skill occupies context before you type a word. Skill descriptions and metadata ride along so the model knows what it can invoke, which means an overgrown skills folder taxes every session — slightly less room for your code, your files and your conversation history. The skill doctor makes that invisible tax visible per skill, which is precisely what you need to decide what stays.
Why Unused Skills Are a Real Automation Problem
For casual use, a few idle skills are harmless. For automation-heavy setups — scheduled jobs, long agent sessions, pipelines that run Claude Code dozens of times a day — the economics change. Context spent on skills you never trigger is context not spent on the task, and on long sessions it is also the difference between the model keeping the thread and the conversation being compacted earlier than it needed to be. If you have been collecting skills the way most builders do — grab everything that looks useful, enable it, forget it — an audit tool arriving in the core CLI is the nudge to run the cleanup you have been deferring.
The rule of thumb the skill doctor enables: keep skills that trigger regularly, keep the rare-but-critical ones you invoke by name, and prune everything that is neither. A skill you can re-enable in a minute does not need to sit in every session on the off-chance.
There is also a quality angle beyond raw token cost. Every loaded skill is another candidate the model weighs when deciding how to approach a task, and two half-relevant skills with overlapping descriptions can pull a session in the wrong direction entirely. A lean, deliberate skill set does not just cost less — it makes the tool's behaviour more predictable, which is exactly what you want from anything you run on a schedule without watching it.
If you want a library of skills and workflows actually worth loading — the Agent OS zip, prompt libraries and daily tutorials that members use to ship automation that pays — check out the AI Profit Boardroom → get inside and grab the stack. Want AI SEO mapped out for your own site first? Book a free SEO strategy session — it is 1-on-1 and free.
How to Run a Pruning Pass With /skill-doctor
- Update to v2.1.261 or later. The command shipped on 4 September 2026, so anything older will not have it. Check your version via /status.
- Run /skill-doctor inside a normal working session. Read it the way you would read a profiler: sort your attention by cost, then ask of each expensive skill — has this triggered lately, and would anything break tomorrow if it were gone?
- Prune in one batch. Disable the unused, expensive entries, keeping anything critical-but-rare that you call deliberately.
- Re-check after a week of real work. Usage data is only as good as the period it covers, so a skill that looks idle during a documentation week might be your most-used skill during a build week. Judge on a representative sample.
If you are newer to the skills system itself and this is all sounding abstract, start with the broader guides: Claude Code training covers operating the tool properly, and the best Hermes Agent skills shows what a genuinely earning-its-keep skill looks like on the agent side of the fence. The same pruning logic applies either way: skills are leverage when used and overhead when idle.
What Shipped Alongside the Claude Code Skill Doctor Command
The v2.1.261 release carried more than the skill doctor, and the neighbours are worth knowing because they share a theme — visibility and control for serious workloads. Per the same official changelog entry of 4 September 2026: an "Organization policy" line was added to /status and claude doctor, explaining why an organisation's policy could not be loaded, such as a proxy not passing the endpoint through; new bashOutputMaxChars and taskOutputMaxChars settings let you raise how much command and background-task output Claude receives inline — up to 128K characters — before it is saved to a file; and a new flag reads the subagent system prompt from a file, for prompts too large to pass on the command line.
A day earlier, v2.1.260 of 3 September 2026 added the diff panel that shows uncommitted changes beside the conversation in fullscreen mode. Taken together, the first week of September gave Claude Code a noticeably better cockpit: see your diffs, see your policy status, see your skill costs. For the permission side of that cockpit — deciding what runs without asking — see the guide to Claude Code permission prompts, which covers the same release family's control surface. And if you run Claude Code on your own infrastructure, Claude Code self-hosted environments covers where these settings matter most.
📺 Watch: LIVE: Building Agentic Operating Systems with Claude
Choosing Which Skills Deserve the Context They Cost
The skill doctor tells you what is idle; it cannot tell you what is valuable. That judgement comes from knowing what a high-leverage skill looks like in practice. For marketing and content work, Claude skills for marketing walks the category, and the best SEO skill for Claude covers the single skill that earns its context on any content site. On the agent side, the Hermes learn skill shows the self-improving pattern — a skill that builds other skills — which is the kind of thing you keep loaded even in lean setups.
If you are assembling a fuller system around this, the Agent OS guide covers the operating layer that decides which skills, prompts and workflows travel together, and the Goldie Bench write-up covers how the different agent brains compare in hands-on tests — relevant here because a stronger model wastes less of the context you just reclaimed.
Common Questions About /skill-doctor
Is the Claude Code skill doctor command free to use?
It ships inside Claude Code itself from v2.1.261 — there is no separate purchase; your existing plan covers it. If you are still working out which plan that should be, is Claude Code free breaks down the tiers.
Does pruning a skill delete it?
Pruning is about unloading, not destroying. A skill removed from your loaded set stops costing context immediately, and re-enabling later is trivial. The command's job, per the changelog, is to show usage and cost "so you can prune them" — the decision and the mechanism stay in your hands.
How often should I run it?
Monthly is plenty for most setups, plus once after any burst of skill collecting. The failure mode it prevents builds slowly, so a periodic audit keeps you permanently ahead of it.
The Bottom Line
The Claude Code skill doctor command turns skill management from folklore into measurement: run /skill-doctor, see which loaded skills go unused and what they cost in context, prune the losers, and re-check on a real work sample. Every fact above comes from the official Claude Code changelog for v2.1.261, dated 4 September 2026 — read the entry after you update, and treat the ten minutes of pruning it prompts as some of the cheapest performance work available to you this month.
If you want your AI stack producing income rather than just consuming subscriptions — with the full Agent OS, 1,000+ workflows and five live coaching calls a week — check out the AI Profit Boardroom → join here. Rather talk it through first? Book a free SEO strategy session and get a personal ranking plan.
