Claude Code Skill Doctor: Find What Every Skill Costs You

Type /skill-doctor into a Claude Code session (version 2.1.252 or later) and you get a report showing what every loaded skill costs you in context and how often each one has actually been used — which makes the new claude code skill doctor command the quickest way to find and switch off the skills that are silently taxing every single turn of your sessions. The command appears in the official Claude Code changelog under version 2.1.261, released 4 September 2026, described as a way "to show which loaded skills go unused and what they cost in context, so you can prune them". If your Claude Code setup has accumulated skills the way most working setups do, this is the spring clean the tool has been missing.

📺 Watch: Claude Code Just Got a HUGE Customization Upgrade

🔥 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 Actually Shows

According to the official Claude Code documentation (fetched 9 September 2026), the claude code skill doctor report covers the skills in your session other than bundled skills and enterprise skills, and for each one it shows two things: what the skill costs and how often it gets used. In an interactive session the report opens in the Stats tab of the /plugin manager; in non-interactive mode with the -p flag, Claude Code prints it as plain text instead. Crucially, the report flags skills that have never been invoked at all and tells you where to turn them off. The docs even give you a triage order: of the skills it tells you where to turn off, start with the ones carrying the highest context cost. That single sentence is the whole optimisation strategy — biggest dead weight first.

Why Unused Skills Cost You Real Money

Here is the mechanism that makes the skill doctor worth running. As the documentation puts it, every skill in the skill listing adds to your context on every turn, whether or not Claude ever uses it. Skills advertise themselves to the model through their descriptions, and those descriptions ride along in every single request. Ten skills you never invoke are not neutral clutter — they are a recurring context charge on every message you send, all day, every day. Context spent on dead skills is context not available for your actual code, and on metered API usage it is tokens you are billed for. That makes pruning a direct cousin of the tactics in the how to reduce Claude Code token usage guide on this site: same goal, different lever. It also compounds with scale — if you run multiple sessions a day, a few thousand characters of unused skill descriptions quietly becomes one of the larger recurring line items in your context budget.

If you want a Claude Code setup that is already tuned — the Agent OS zip, prompt libraries, daily tutorials and weekly live coaching calls — check out the AI Profit Boardroom and grab the full setup inside. Want a 1-on-1 look at your own AI workflow instead? Book a free SEO strategy session and get it mapped out properly.

📺 Watch: Free Claude Code Is CRAZY GOOD!

How To Run The Claude Code Skill Doctor

The command itself could not be simpler — open Claude Code in your terminal and type /skill-doctor — but there are three requirements worth knowing before you wonder why nothing happens. First, per the official docs, it requires Claude Code v2.1.252 or later, and the changelog lists it as arriving in the 2.1.261 release of 4 September 2026, so update first if you are behind. Second, it is not available in sessions that skip feature-flag fetching, which can affect some locked-down or offline-leaning configurations. Third, it does not work over Remote Control: run it from your phone or browser and Claude Code replies that skill usage reports are not available on this connection. The fix is simply to run /skill-doctor in the terminal on the machine where the session is actually running. None of these are dealbreakers — they are just the difference between the command working first time and you assuming it is broken. The -p route deserves a special mention for anyone running Claude Code in scripts or scheduled jobs: because the report prints as plain text in non-interactive mode, you can capture it, diff it against last month's output and watch your context spend trend over time rather than guessing.

A Simple Pruning Workflow

Once the report is in front of you, the pruning pass takes about five minutes. A workflow that follows the documentation's own guidance looks like this:

1. Update Claude Code, open a normal working session, and run /skill-doctor once you have used the session the way you typically do — the usage numbers are only meaningful if they reflect real work.
2. Sort your attention by context cost, exactly as the docs advise: of the skills flagged with a place to turn them off, start with the highest-cost ones.
3. Turn off everything flagged as never invoked, using the location the report gives you for each skill.
4. For skills that are used but rarely, weigh the cost against the convenience — a cheap skill used monthly can stay, an expensive one used monthly probably should not.
5. Re-run the report every few weeks, because skills accumulate the same way browser extensions do: one at a time, each individually reasonable.

Two edge cases are worth flagging while you prune. Bundled skills and enterprise skills sit outside the report's scope, so do not be surprised when they fail to appear — the skill doctor is auditing the skills you and your plugins added, not the ones Claude Code ships with or your organisation mandates. And usage numbers describe your session, so a skill that looks dead in your coding sessions might be the backbone of a teammate's content workflow; on shared machines or shared settings files, check before you switch things off globally rather than for yourself.

The point of the workflow is not minimalism for its own sake — it is that every character of context you reclaim goes back to the thing you actually opened Claude Code to do. Leaner context also tends to mean sharper tool selection, because the model is choosing from skills that genuinely belong in your workflow rather than scanning past a graveyard of one-off experiments.

Where This Fits In Your Claude Code Setup

The skill doctor lands as part of the same early-September wave of quality-of-life releases as the new output settings covered in the Claude Code bash output limit write-up — Anthropic shipping visibility and control features rather than headline model changes. Both point the same direction: the difference between an average and an excellent Claude Code setup is increasingly about context hygiene, not model choice. If you are still getting oriented, the learn Claude Code guide covers the fundamentals and the Claude Code training round-up goes deeper, while the free Claude Code guide shows how to run all of this without a subscription. Skills themselves remain absolutely worth using — the best SEO skill for Claude and the wider Claude skills for marketing collection are exactly the kind of high-use skills that survive any honest pruning pass. The skill doctor is not an argument against skills; it is an argument for knowing what each one costs. Slot the pruning pass into your wider Agent OS maintenance routine, and if you are choosing which model to run your newly leaner setup on, the Goldie Bench write-up covers how the current model brains compare in hands-on tests.

The bigger picture is worth thirty seconds. Agentic tools are moving from "add more capability" to "spend capability wisely", and the claude code skill doctor is one of the clearest examples yet — a first-party admission that context is a budget, and that most setups are overspending it on skills nobody uses. The teams getting the most out of Claude Code by the end of 2026 will not be the ones with the most skills installed; they will be the ones who know, to the character, what their context is buying them. Running one diagnostic command every few weeks is a very cheap way to be in that group.

If you want your whole AI stack tuned like this — working setups, the Agent OS zip, prompt libraries and weekly live coaching calls — check out the AI Profit Boardroom and get inside now. And for a personalised plan, book a free SEO strategy session — bring your setup and leave with a roadmap.

Real wins from inside the AI Profit Boardroom

See all 3,000+ members →

← Back to all posts