Claude Code 2.1.261 added /skill-doctor, a maintenance command to find skills that remain loaded in context even though they’re almost never used.
It seems small until your setup accumulates months of skills, plugins, experiments, and project helpers. Skills are better than dumping every procedure into CLAUDE.md, because the full body only loads when needed. But the skills list still costs context on every turn: Claude needs names and descriptions to know what tools it has available.
/skill-doctor makes that cost visible.
How to know what skills Claude Code uses?
To know what skills Claude Code uses, run /skill-doctor in the terminal session where Claude Code is running.
Anthropic’s documentation says the command shows how much each skill costs and how often it’s used, so you can decide which ones to disable. In an interactive session, the report opens in the Stats tab of the /plugin manager. In non-interactive mode with -p, Claude Code prints the report as text.
That difference matters for advanced users. If you manage a single local workstation, the visual report is enough. If you maintain a shared setup, a template repository, a devcontainer, or a team plugin package, the text output looks more like an auditable artifact.
The report doesn’t cover everything. At the time of publishing this note, September 7, 2026, the documentation says it covers the skills in your session except bundled skills and enterprise skills. It also requires Claude Code v2.1.252 or later, depends on feature flag load, and isn’t available from Remote Control sessions on phone or browser. Run it from the terminal on the machine where the session actually runs.
Why do skills you don’t use cost context?
Skills you don’t use cost context because Claude Code includes a skills list in the model context on every turn.
The important nuance: it doesn’t load the full body of every SKILL.md all the time. That’s precisely why skills are cleaner than turning every reusable workflow into an always-active instruction file. But Claude does need the list: names, descriptions, and enough metadata to decide if a skill is relevant.
As your setup grows, that list can become noisy.
Maybe you installed a plugin for a test and forgot about it. Maybe a project skill made sense three months ago, but no longer fits the repo. Maybe a skill synced from claude.ai competes with something local. Maybe a team plugin exposes twenty skills, but only three matter in this codebase.
Each one adds friction. Not just token cost, but selection cost: more names, more descriptions, more chances for Claude to pick the wrong helper or miss the right one because the list became too broad.
What should you do after running /skill-doctor?
After running /skill-doctor, treat the result as a pruning queue, not an automatic deletion list.
There are four practical decisions:
- Keep skills that are frequently used and clearly tied to real workflows.
- Move to
name-onlyskills that are rarely used and whose full description doesn’t deserve context space. - Disable skills that were experiments, obsolete project helpers, or one-time research.
- Manage skills that come from plugins through
/plugin, becauseskillOverridesdoesn’t affect plugin skills.
Claude Code already exposes skillOverrides to control skills from settings. The documentation describes states like on, name-only, user-invocable-only, and off. That gives you more nuance than “delete it or keep it forever”.
A useful cleanup pass looks like this:
- Run
/skill-doctor. - Identify skills that were never invoked.
- Check whether they’re personal, project, synced, or plugin skills.
- Disable the obsolete ones.
- Collapse the marginal ones to
name-only. - Run some real prompts again and confirm that important skills still activate.
The goal isn’t minimalism for its own sake. The goal is to make the map of tools available to Claude smaller, clearer, and cheaper.
What’s the difference between /doctor and /skill-doctor?
/doctor checks the health and configuration of your Claude Code environment; /skill-doctor focuses on skills usage and its context cost.
That separation is useful.
A general doctor command can tell you something is misconfigured. A skills doctor answers a different operational question: what loaded skills are earning their place in the context budget.
The skills documentation also says /doctor can estimate the context cost of the skills list and its biggest contributors. /skill-doctor is the next step: once you know skills cost context, it helps you find which ones are worth disabling.
For developers who install every interesting plugin that appears, this was the maintenance step that was missing. The ecosystem invites experimentation. Context demands discipline. /skill-doctor is where those two realities meet.
What else changed in Claude Code 2.1.261 besides /skill-doctor?
Claude Code 2.1.261 also added bashOutputMaxChars and taskOutputMaxChars, two settings to increase how much command output and background task output Claude receives inline before it gets saved to a file.
According to the changelog published September 4, 2026, both settings can go up to 128K characters.
This is the sister function of /skill-doctor: it’s not about skills, but about context control. A shell command can create the same problem as an inflated skills list. Too little output and Claude loses useful details. Too much output and the session fills with logs, stack traces, test noise, build output, and repeated lines that should have been summarized or saved to a file.
The new settings give advanced users finer control.
If you’re debugging a test suite where the useful clue appears after a long stack trace, a larger inline window can help. If you run noisy build tools all day, a larger window might just push more noise into the model. The right setting depends on the workflow.
That’s why this part belongs in the same maintenance note as /skill-doctor: both functions are about deciding what deserves to stay inline.
When should you increase bashOutputMaxChars or taskOutputMaxChars?
You should increase these limits when command or background task output is being saved to files before Claude sees enough useful context.
Good candidates:
- Long test failures where the actionable error appears late.
- Type-checking output where the first error isn’t the only relevant one.
- Background agents that produce structured reports.
- Build logs where the final summary matters.
- Migration scripts that print a useful validation section at the end.
Bad candidates:
- Too-verbose watch processes.
- Dependency installations with repetitive logs.
- Test suites that print thousands of passing cases.
- Commands that include secrets or sensitive runtime output.
- Anything a script should summarize before showing Claude.
The limit matters because 128K characters isn’t small. It can be useful for real debugging, but it can also make a session heavier. Larger output windows aren’t automatically better. They’re a way to spend context intentionally.
Why does this matter for teams?
This matters for teams because Claude Code setups are becoming shared infrastructure.An individual developer can tolerate some messiness. A team shouldn’t let every experiment become permanent context overhead. When skills live in project repositories, plugin marketplaces, synced accounts, and managed settings, someone needs an operational rhythm to keep the agent’s tool surface clean.
That rhythm is simple:
- Review loaded skills.
- Remove or hide what’s obsolete.
- Keep high-value workflows easy to invoke.
- Tune output windows for commands that matter.
- Revisit after major changes to plugins or project templates.
This connects directly to yoDEV’s earlier coverage of Claude Code skills. Record a Skill makes it easier to create skills. Matt Pocock’s skills showed how quickly a personal skills directory can become a useful artifact. Caveman showed that a focused skill can spread fast.
/skill-doctor is half of that maintenance story.
If creating skills is now easy, pruning skills has to become normal.
What’s the practical workflow?
The practical workflow is making skills cleanup part of your Claude Code maintenance.
Run /skill-doctor after a batch of plugins, after adding a shared set of project skills, or when a session starts to feel loaded. Look for skills that were never invoked, plugins that haven’t been used recently, and descriptions that take up space without helping Claude choose well.
Then make small changes:
- Disable obsolete skills.
- Move marginal skills to
name-only. - Keep frequently used skills visible.
- Manage plugin skills from
/plugin. - Tune command output only for workflows that really need more inline logs.
Don’t treat it as a one-time cleanup. Treat it like dependency pruning. The first pass removes obvious waste. The second pass, after a week of real work, tells you what actually mattered.
The biggest signal is that Claude Code is adding more tools to operate the agent, not just to prompt it. Hooks control behavior. Plugins package workflows. Skills teach reusable procedures. /skill-doctor shows how much it all costs.
That’s healthy.
A powerful agent shouldn’t just gain capabilities. It should also help you see which capabilities became dead weight.