A dedicated command for a problem this site has covered piecemeal
Claude Code v2.1.261, shipped 4 September 2026, added a new command: /skill-doctor, described in the release's own changelog as showing "which loaded skills go unused and what they cost in context, so you can prune them." At the time of writing, neither the commands reference nor the skills documentation had a dedicated section for it yet, both fetched in full for this piece. That's not unusual for a command that shipped a day before an article is written: Claude Code's own docs regularly lag a release by a day or two. What follows draws on the changelog's own wording plus the skill-listing mechanics /skill-doctor evidently audits, which are documented in detail elsewhere on the same site.
If you've read why Claude Code shortens or drops your skill's description or the skillOverrides setting, the problem /skill-doctor targets will be familiar: install enough skills and the listing Claude sees every turn starts costing real context, some of it on skills nobody's touched in weeks.
Why a skill listing costs context at all
Every Claude Code session loads a listing of installed skills, name and description, so Claude knows what's available before it reads any skill's full body. That's progressive disclosure, the mechanic that makes hundreds of installed skills cheap in the common case. The listing itself isn't free, though. Claude Code's own documentation is specific about the cost:
Claude Code loads a listing of skill names and descriptions into context so Claude knows what's available. The listing always contains every skill name, but if you have many skills, Claude Code shortens descriptions to fit the listing's character budget, which can strip the keywords Claude needs to match your request. The budget scales at 1% of the model's context window. When the listing overflows, Claude Code drops descriptions starting with the skills you invoke least, so the skills you use most keep their full text.
That budget is a real setting, skillListingBudgetFraction, defaulting to 0.01, one percent of the context window. A second setting, skillListingMaxDescChars, caps each individual description at 1,536 characters by default regardless of how much budget is left. Between the two, a workspace with a lot of installed skills can end up with several descriptions silently truncated or dropped entirely, and until now the only way to see that happening was /doctor, or the Skills row in /context.
Where /doctor already touched this
/doctor is Claude Code's general setup checkup, and its documented scope is broad. Per the commands reference:
Run a setup checkup that diagnoses issues and can fix them. Checks installation health, including duplicate or leftover installs, PATH problems, and unparseable settings files. Finds unused skills, MCP servers, and plugins versus their context cost, flags slow hooks, and checks for a newer version on your release channel. Deduplicates local CLAUDE.md files against checked-in ones, trims checked-in CLAUDE.md files by cutting content Claude could derive from the codebase, and migrates the always-loaded guidance that remains into skills and nested CLAUDE.md files that load on demand.
Notice "finds unused skills... versus their context cost" is already in there, one line among many. /doctor also handles PATH problems, settings file corruption, hook performance, CLAUDE.md bloat, version checks, and offers to turn on auto mode. That's a lot of ground for one command, and the skills-and-context slice of it is easy to miss inside a report covering half a dozen unrelated concerns.
/skill-doctor reads, from its one-line changelog description, as that slice pulled out into its own command: skills only, unused ones flagged, their context cost shown, nothing about PATH or CLAUDE.md files bundled in. That's a reasonable thing to split out, since skill hygiene and installation hygiene are genuinely different maintenance tasks with different audiences: a solo developer curating their own skill folder doesn't necessarily care about PATH problems, and a team lead auditing a shared skill set doesn't need a CLAUDE.md trim recommendation mixed into the same report.
What "unused" most likely means
Claude Code doesn't publish, as of this writing, an exact definition of "unused" scoped to /skill-doctor. But the skill listing's own truncation behaviour gives a strong hint: when the listing overflows its budget, Claude Code drops descriptions "starting with the skills you invoke least." That's usage-based prioritisation baked into the existing mechanism, not a simple installed-or-not check. It would be consistent for /skill-doctor to surface the same underlying invocation data directly, rather than only acting on it silently when the budget is already exceeded.
That distinction matters for how you read a report. A skill flagged as unused isn't necessarily broken or badly written, it may just not have come up in your recent sessions. Whether that's a problem depends on why you installed it: a skill for a task you do quarterly is going to look "unused" most of the time and that's fine, whereas a skill you expected Claude to reach for automatically and never has is a real signal that its description isn't doing its job.
Acting on what it flags
Once you know which skills are costing context without earning their keep, there are two places to act, depending on whether you own the skill:
A skill you maintain. Rewrite the description to be more specific if it should be triggering and isn't, or add disable-model-invocation: true to its frontmatter if you want it manual-only from now on. That's a source change: it affects everyone who installs the skill, not just your local setup. See the SKILL.md format explained for the full frontmatter reference.
A skill you don't maintain, a shared team skill, a plugin-adjacent one, or something installed from a marketplace you don't control. Here skillOverrides is the right tool, since it changes visibility from your settings without touching the file:
{
"skillOverrides": {
"quarterly-report-formatter": "name-only",
"abandoned-migration-helper": "off"
}
}
"name-only" drops the description from the listing while keeping the skill invocable by name, a direct way to free listing budget for a skill you still want available occasionally. "off" hides it everywhere, including the / menu. Both are local, reversible, and don't require forking anything.
If the underlying issue is that your budget itself is too tight for a large, legitimately-used skill set, raising skillListingBudgetFraction is the other lever, at the cost of more context spent on the listing every single turn. /skill-doctor presumably helps you decide which of those two responses, pruning or raising the budget, actually fits what it found, though exactly how its report is laid out wasn't confirmed in dedicated documentation at the time of writing.
/skill-doctor, /doctor and /context side by side
Three commands now touch skill context cost, each at a different level of detail:
| Command | Scope | What it shows |
|---|---|---|
/context | Whole session | The current size of every context category, including the Skills row's post-budget listing size |
/doctor | Whole installation | Unused skills, MCP servers and plugins versus cost, plus PATH, settings, hooks, CLAUDE.md and version checks |
/skill-doctor | Skills specifically | Which loaded skills go unused and what they cost, without the unrelated installation checks /doctor bundles in |
/context answers "how big is my context right now, and which category is using the most of it." /doctor and /skill-doctor both answer a different question, "what could I remove," but at different levels of focus: /doctor as one line item inside a much broader health check, /skill-doctor as the entire point of the command. If you already suspect skills specifically are the problem, from a bloated /context Skills row, say, /skill-doctor is the more direct next step; if you're not sure what's wrong yet, /doctor's wider net is the better place to start.
A worked scenario
Say a project has accumulated fourteen skills over several months: some written for a migration that finished, a couple installed from a marketplace out of curiosity and never used again, and half a dozen genuinely load-bearing ones the team relies on daily. Nobody's audited the list, and lately Claude seems slower to reach for the skills that matter, a classic symptom of a bloated listing crowding out the descriptions that should be triggering automatically.
Running /skill-doctor should, per the changelog's own description, surface exactly which of those fourteen have gone unused and what each one costs. From there the response is mechanical: skillOverrides entries for the ones nobody maintains and nobody's touched, a frontmatter edit for the one or two the team does own but whose description clearly isn't matching real requests, and a decision on whether the remaining, actively-used set still needs the default 0.01 budget or would benefit from a slightly larger one. That's the same triage testing an agent skill before you ship it recommends for a single skill, just run across a whole installed set instead of one at a time.
Troubleshooting
/skill-doctor isn't recognised. It requires Claude Code v2.1.261 or later. Check with claude --version and upgrade if you're behind that.
It's unclear whether a flagged skill is safe to hide. Check who actually uses it before touching skillOverrides. A skill flagged unused on your machine might be someone else's daily driver if the setting is shared in a committed .claude/settings.json; prefer a local .claude/settings.local.json override until you've confirmed nobody else relies on it.
The listing is still over budget after pruning. Confirm the skills you turned off were actually costing meaningful description length, not just a name entry, since names always stay listed regardless of state. Run /context afterwards; its Skills row reports the size of the listing after the budget is applied, so it's the fastest way to see whether pruning actually moved the number.
A skill you use rarely but deliberately keeps getting flagged. That's expected if "unused" is invocation-based, as the existing truncation mechanism suggests. Consider "name-only" rather than "off" for a skill you want available but don't need Claude finding on its own, since that keeps it invocable by name without costing the description's share of budget every turn.
Where to go next
For the mechanics /skill-doctor is auditing, see why Claude Code shortens or drops your skill's description and the full skillOverrides reference. For the broader checkup command it's split out of, /doctor's other responsibilities, PATH issues, settings validation, CLAUDE.md trimming, are worth knowing even if skills are what brought you here. For writing skills that earn their place in the listing rather than needing to be pruned later, start with how to write your own agent skill, and browse what's already installed-worthy at getclaudeskills.com/skills.
