How to Reduce Claude Code Skill Context Cost

You can now see which Claude Code skills charge context rent without doing useful work, then remove that rent without throwing away instructions your real workflows still need. The new /skill-doctor report turns skill cleanup from a guess into a measured, reversible operating habit.

The short answer is: run /skill-doctor, sort each unused skill by how painful it would be to lose, apply the least destructive visibility change, and test in a fresh session. Do not begin by deleting folders. A skill that is quiet for a week may still be the thing that keeps a deployment or incident response safe.

Claude Code 2.1.261, released on September 4, 2026, added /skill-doctor to show which loaded skills go unused and what each one costs in context. That matters because every listed skill contributes a name and usually a description to every turn, even when Claude never invokes its full instructions.

What skill context cost actually means

Skill context has two bills, and confusing them leads to bad pruning.

The first is the listing bill. Before you type anything, Claude sees the available skill names and descriptions so it can decide which skill fits your request. Anthropic caps this listing at 1% of the model's context window by default, and each skill's combined description and when_to_use text is capped at 1,536 characters by default.

The second is the invocation bill. The full SKILL.md body loads only when you or Claude invokes that skill. Once loaded, it stays in the conversation across later turns. After compaction, Claude Code can reattach up to 5,000 tokens from each invoked skill, with a 25,000-token combined budget for reattached skills.

Think of the listing as a shop window and the skill body as inventory brought to the counter. Every shop sign occupies space on the street. The inventory costs far more space, but only after someone asks for it.

This distinction changes the fix. An unused skill with a long description creates recurring listing cost. A frequently invoked skill with a huge body creates persistent session cost. /skill-doctor is strongest on the first problem, while good skill architecture handles the second.

The business math is per turn, not per install

An idle skill is not a one-time setup expense. Its listing text is presented again as the conversation advances. A useful working estimate is:

Avoidable context per day = unused listing tokens per turn × Claude turns per day

For example, if the report identifies 2,000 tokens of unused listing context and your work generates 40 model turns, that is 80,000 input tokens presented across the day. This is an example, not a benchmark. Prompt caching can reduce the billed rate for repeated text, but it does not make the context disappear.

For API and cloud-provider users, those extra tokens affect the bill. For subscription users, they consume plan capacity and leave less working room before compaction. Anthropic says enterprise Claude Code deployments average about $13 per developer per active day and $150 to $250 per developer per month. Skill waste is only one part of that spend, but it is now one of the few parts you can isolate by name.

The budget line that breaks is not just model spend. It is developer throughput. A crowded listing can force Claude Code to drop descriptions for the least-used skills, which saves space but also makes those skills harder for Claude to select automatically.

The prune, rerun, and restore workflow

The safest workflow has seven moves.

1. Start from a current terminal session

Update to Claude Code 2.1.261 or newer and verify the installed version with claude --version. Anthropic's reference says /skill-doctor requires 2.1.252 or later, while 2.1.261 is the changelog release that announced the command.

Run /skill-doctor in the terminal on the machine hosting the session. In an interactive session, the report opens in the /plugin manager's Stats tab. In non-interactive mode with -p, it prints as text, which makes it practical to capture for a local audit. Remote Control cannot return the report.

2. Record the baseline

Save three things before changing anything: the total skill listing cost, the largest unused contributors, and the skills or plugins you intend to change. Also run /context to see the post-budget Skills row, and /doctor to identify the listing's biggest contributors.

Do not translate the token count straight into dollars unless you know your model, cache behavior, and contracted rates. Use tokens as the stable unit and calculate money separately.

3. Sort candidates by failure cost

Put each candidate into one of three buckets:

This is where the report needs judgment. “Never invoked” measures frequency, not value. A fire extinguisher can be unused and still worth keeping.

4. Use the least destructive control

For local, personal, project, or synced skills, the /skills menu can write a reversible skillOverrides change to .claude/settings.local.json.

• Use name-only when Claude should know the skill exists but does not need its full description in the listing.
• Use user-invocable-only when you want /skill-name available but never want automatic selection.
• Use off only when neither you nor Claude should see it.
• Use on to restore the original behavior.

If you own the skill, disable-model-invocation: true is the portable author-level version of a user-only policy. It removes the description from Claude's listing while keeping direct invocation available.

Plugin skills are different. skillOverrides does not affect them. Disable the plugin without uninstalling it using /plugin disable plugin-name@marketplace-name, then restore it with /plugin enable plugin-name@marketplace-name. Remember that a plugin may also supply agents, hooks, MCP servers, or language tooling, so inspect its components before switching it off.

5. Shrink bodies without shrinking capability

If a useful skill has a large body, keep SKILL.md as the routing card and move detailed examples, API references, and edge cases into supporting files. Anthropic recommends keeping SKILL.md under 500 lines. Supporting files load only when Claude needs them, and helper scripts can execute without placing their source in the prompt.

Put the job, trigger, non-negotiable rules, and map to supporting files near the top. That also protects the important part after compaction, when only the first 5,000 tokens of each reattached skill are retained.

6. Test in a fresh session

Changing a skill does not erase instructions already loaded into the current conversation. Start a fresh session, run a few prompts that should trigger the skill, and compare them with the same prompts while the skill is hidden. Measure task success first, tokens second.

Anthropic recommends fresh-session comparisons because leftover authoring or skill context can mask what the skill actually contributes. If plugin changes need /reload-plugins, expect the next request to have a token cost, and possibly a prompt-cache rebuild when the plugin exposes non-deferred MCP tools.

7. Restore misses, then rerun the audit

If quality drops, restore one step: off to user-invocable-only, user-only to name-only, or a disabled plugin to enabled. If quality holds, keep the leaner state and rerun /skill-doctor after a representative stretch of real work.

That last pass matters. The goal is not the smallest possible skill list. It is the cheapest list that still routes your recurring jobs correctly.

Who profits most from this

These use cases are ranked by likely economic impact.

1. Platform teams maintaining a shared Claude Code setup

A platform lead with dozens of developers can ask a pilot group to export local /skill-doctor reports, identify skills that appear everywhere but trigger nowhere, and move optional workflows to user-only or project-specific availability. The payoff compounds across every developer turn, while the restore file keeps the experiment reversible. Enterprise-managed skills are excluded from the report, so this works as a local fleet sample rather than a complete policy audit.

2. Plugin-heavy engineering teams

A team may install a plugin for one migration and leave its skills, agents, hooks, and MCP tools enabled for months. /skill-doctor surfaces recently unused plugins, and the plugin manager can disable them without uninstalling them. The payoff is broader than the skill description alone because an unused plugin may add several context-bearing components. The catch is equally broad: disabling it can remove useful non-skill components too.

3. Consultants who move between client stacks

A consultant may carry frontend, data, ecommerce, and infrastructure skills globally even though only one group fits the current client. They can keep named profiles in local settings, expose the relevant group, and leave rare safety workflows user-only. The payoff is a clean starting context for each engagement without rebuilding the toolkit every Monday.

4. Large monorepo maintainers

Claude Code can discover nested skills as it reads deeper directories, and those skills stay available for the rest of the session. A monorepo maintainer can audit after a cross-package task, move package-specific instructions into the correct nested directory, and shorten root-level descriptions. The payoff is better routing: backend work does not carry a parade of frontend workflow descriptions.

5. Teams with rare, high-stakes commands

Deployment, rollback, data migration, and incident skills may not trigger for weeks. They should not be deleted simply because the report calls them unused. Marking them manual-only removes their descriptions from Claude's recurring listing while preserving the exact /skill-name escape hatch. The payoff is lower normal-session context with no need to recreate the runbook during an emergency.

6. Skill authors with reference-heavy instructions

A skill author can use the report to find an expensive skill, then split its long examples and specifications into supporting files. The main file becomes a concise decision map. The payoff is delayed context cost: detail arrives only when the job reaches the branch that needs it.

7. Solo builders on a subscription limit

A solo builder may not see a direct dollar reduction because Pro and Max include usage in the subscription. The useful outcome is more work inside the same allowance and more room before compaction. Pair /skill-doctor with a clean Claude Code setup, and clear the session when switching to unrelated work.

Three products worth building

The search market is bigger than the new query makes it look. DataForSEO reports 12,100 US searches a month for claude code skills, with an $8.26 CPC. The narrow phrases about reducing skill context returned no suggestions, which makes this a freshness opportunity inside an established skill market, not a mature standalone category.

1. Skill Budget Guard, the strongest bet

Build a local-first CLI and CI check that reads repository skills, visibility settings, and an exported /skill-doctor report, then shows the context delta of every pull request. Platform teams pay because the tool turns one developer's cleanup into a repeatable team budget.

The demand signal is unusually clear: claude code skills gets 12,100 monthly searches, carries an $8.26 CPC, and Anthropic reports average enterprise Claude Code cost of $150 to $250 per developer per month. The smallest sellable version needs a local parser, a checked-in budget file, a GitHub Action, and reversible suggestions such as “move to user-only” or “split references.”

The honest catch is platform risk. Anthropic can expand /skill-doctor, and its Analytics API is already free for eligible organizations. The defensible layer is policy history, cross-repository comparison, and proof that a context reduction did not reduce task success.

2. Project Skill Profile Switcher

Build named profiles such as frontend, data, incident, and release that apply skillOverrides plus plugin enable or disable changes, then restore the previous state in one command. Consultants and monorepo teams are the buyer.

DataForSEO reports 590 monthly searches for best claude code skills, with commercial intent and an $11.91 CPC. The MVP is a manifest, a diff preview, safe writes to local settings, plugin commands, and a restore checkpoint. The catch is a thin moat. Claude Code's own menus already expose the underlying controls, and plugin reloads can add a one-turn cache cost.

3. Skill Outcome Lab

Build a test runner that sends the same realistic prompt through fresh sessions with a skill on and off, then compares pass rate, time, and token use. Skill authors and internal enablement teams pay for evidence that an instruction earns its context.

DataForSEO reports 110 monthly searches for claude code skills best practices, with commercial intent and top-of-page bids from $4.14 to $6.01. A useful MVP needs prompt fixtures, expected-output checks, fresh-session isolation, and a simple before-and-after report.

The catch is decisive: Anthropic's official skill-creator plugin already benchmarks with-skill versus without-skill runs. This should be a feature inside Skill Budget Guard, not a standalone company.

If your team distributes skills across products or agents, this comparison of Notion Skills and Claude Skills API adds the governance side of the decision.

What /skill-doctor does not solve

/skill-doctor is a profiler for skill-listing waste, not a complete Claude Code cost optimizer.

• It does not audit bundled or enterprise skills.
• It does not remove a skill body already loaded into the current conversation.
• It does not measure CLAUDE.md, old conversation history, model choice, thinking tokens, verbose tool output, or MCP overhead.
• It cannot return usage reports over Remote Control.
• It cannot tell you whether a rare skill prevented an expensive mistake.
• It does not make cached context free. Cache pricing and context occupancy are separate questions.

Do not start by lowering skillListingBudgetFraction. When the listing exceeds its budget, Claude Code keeps the names but drops descriptions beginning with the least-used skills. That can reduce listing text while making the right skill less likely to trigger. Remove or hide low-value entries deliberately instead.

The other wrong move is uninstalling plugins on sight. Disable first, test, then uninstall only when you know the plugin's other components are unnecessary.

Your Monday move

Pick one real repository and one developer who uses Claude Code heavily. Run /skill-doctor, record the five largest unused contributors, and change only two: put one rare workflow into user-only mode and disable one genuinely irrelevant plugin. Start a fresh session, repeat three normal tasks, then restore anything that changes the outcome. That gives you a defensible context-saving policy by Friday, not a tidier configuration that quietly made the agent worse.

How to make a Claude code use less context?

Run /skill-doctor to find unused skill-listing cost, use /context for the overall breakdown, hide irrelevant skills, make rare workflows user-only, move long references into supporting files, and use /clear between unrelated tasks.

How to minimize Claude code cost?

Reduce recurring context first, then address model choice, long sessions, thinking settings, verbose tool output, and unused MCP servers. /skill-doctor covers only the skill slice of that bill.

Are Claude Code skills free?

Anthropic's skill documentation does not list a separate fee for a local SKILL.md, but its name and description can consume context on every turn, and its full body consumes context after invocation. API users pay according to token usage; subscription users draw from their included allowance.

How to compact Claude code context?

Use /compact when you need continuity in a long task and /clear when you are switching to unrelated work. Invoked skill bodies can be reattached after compaction, capped at 5,000 tokens per skill and 25,000 tokens in total.

Should I clear context in a Claude code?

Yes, when you are moving to an unrelated task. For a skill-pruning test, a fresh session is important because a skill body already loaded into the old conversation can hide the effect of disabling it.

If you want a measured skill-governance workflow built for your engineering team, see AI production systems.