Table of contents

"Install too many skills and they crowd out your context." You hear it constantly. Half of it is right and half of it is wrong.

According to the official documentation, the skill listing draws on a fixed budget of 1% of the model's context window, and no matter how many skills you add, it stops there. It does not grow. What happens instead is that skills stop being called. When the listing overflows the budget, Claude Code drops descriptions starting with the least frequently invoked skills and keeps only their names. A skill that has lost its description no longer connects to what you asked for.

There is no error. Nothing gets slower. The skill just quietly stops being used. This article covers how to see what is actually occupying your context, with numbers instead of guesses, and what to cut first once you have looked.

What actually happens when you add more skills

The listing budget is fixed at 1% of the context window. What overflows costs you descriptions, not tokens

WITHIN BUDGET
Every skill keeps its description

Name and description load in full. Even when your wording is a little off, keywords still find the skill

JUST PAST THE LIMIT
Descriptions go in order of use

Frequently used skills keep their full text. The ones you rarely reach for lose their descriptions first

NAME ONLY
Present, but never chosen

It stays in the listing. But nothing says what it is for, so it never connects to a request

Source: Claude Code documentation, Skills

1. Skills do not grow forever: the listing caps out at a 1% budget

So that Claude knows which skills are available, Claude Code loads a listing of skill names and descriptions into the context. That is where the budget starts to matter. The documentation states that the listing always includes every skill name, but when there are many skills, Claude Code shortens the descriptions to fit the listing's character budget, and it sets that budget at 1% of the model's context window.

Numbers make it concrete. On a model with a one-million-token context window, the skill listing gets 1% of that. The remaining 99% is there for the conversation, files and tool results. Install 50 skills or install 100, and that 1% does not move.

So where does the extra go? Into shortened descriptions. The documentation even spells out the order in which they are trimmed: when the listing overflows, Claude Code drops descriptions starting with the least frequently invoked skills, so the ones you use most keep their full text.

That is the frightening part in practice. The skills that take the hit are the ones you use only occasionally, and those are usually the same ones you need right after you have forgotten about them. A quarterly migration procedure, a release process you run a few times a year: exactly those lose their descriptions first.

The budget is adjustable. Write a fraction of the context window into skillListingBudgetFraction (for example 0.02 for 2%) and the listing gets more room. There is also a per-skill cap on the text: 1,536 characters covering the description and its triggering conditions by default (changeable via skillListingMaxDescChars). The reason the documentation tells you to put the primary use cases first is that this cap truncates from the end.

2. Three tools for measuring, each with a different job

Three tools let you replace guesswork with numbers. /context has been around for a while, but the prompt cache line in /usage arrived in v2.1.251 (August 28, 2026) and /skill-doctor in v2.1.252 (August 31). They do different jobs, so all three are worth keeping in mind.

/context
What is loaded right now

Breaks down what is occupying the window. The Skills line reports the size after the budget has been applied, so it matches what the model actually receives

/usage
What that consumed

Session tokens and cost, plus the state of the prompt cache and a usage breakdown by skill, subagent and MCP server

/skill-doctor
Which ones earn their keep

Reports cost and invocation frequency per skill and flags the ones that were never called. It points at where to cut

There is an order to this. Read the breakdown with /context, confirm what it actually spent with /usage, then identify cut candidates with /skill-doctor. Start from the other end and you delete things with no evidence behind the decision.

On the Skills line of /context, the documentation also records how the command used to behave: before v2.1.196 it counted the character length of every description and could report a figure several times larger than the configured budget. If your sense that skills are eating your context comes from an older memory, that number itself may have been larger than reality.

3. Make Claude Code name the skills nobody uses

/skill-doctor is available in Claude Code v2.1.252 (August 31, 2026) and later. The official description is that you can see the cost and invocation frequency of each skill and decide which ones to cut. Four things about its behavior are worth knowing.

What /skill-doctor assumes

  • In an interactive session it opens the Stats tab of the /plugin manager. In non-interactive mode with -p it prints text instead
  • Bundled skills and organization-distributed skills are out of scope. Only what you added yourself is listed
  • Skills that were never invoked are flagged, along with where to cut them
  • It cannot run over remote control from a phone or a browser, and returns an error

Keep one thing in mind when reading the results and you will not go wrong. "Never invoked" is not a synonym for "unnecessary." As the previous section showed, one reason a skill never gets called is that its description was trimmed away, so nothing can find it.

Before you cut, the reliable move is to call the skill by name. If it works when named but never gets picked automatically, it is not unnecessary: its description is losing to the budget. The fix is not deletion but rewriting the description (primary use cases first) or raising the budget.

4. Cache misses hurt more than size does

From here the topic moves off the axis of how big your context is. Two conversations of the same size can bill completely differently depending on whether the cache is working.

Since Claude Code v2.1.251 (August 28, 2026), the session panel of /usage carries a prompt cache line. Here is the example the documentation shows.

Prompt cache (main):   14 requests · 91% of input tokens from cache ·
2 misses (last 6m 10s ago, 310.2k tokens re-cached) ·
1 expected rebuild (compaction or tool-result clearing) ·
warm (1h TTL, last activity 40s ago)

Three things matter when reading it.

MISSES
5% and 2,000 tokens

A request counts as a miss when it re-reads more than this much content that the cache could have served. A small swap does not qualify

EXPECTED REBUILD
The part you broke yourself

When Claude Code rewrites the conversation itself through compaction or clearing old tool results, that is counted separately as an expected rebuild, not a miss

WARM / COLD
Inside the lifetime, or past it

Whether the cached prefix is still alive. When it has gone cold, the line shows how long you left it idle

From v2.1.260 on, when there is a plausible explanation for a recent miss, the line names it (for example likely cause: tool definitions changed). Adding an MCP server or swapping a skill rewrites something near the front of the conversation, which invalidates the cache for everything after it. That is why changing your setup before you start work is the cheap way to do it.

One caveat. This line only looks at the main conversation, and it does not include subagents. If your workflow pushes heavy processing to subagents, these numbers are not the whole picture.

5. The cache does not always live for an hour

This one is tied directly to your bill and yet it is not widely known. The lifetime of the prompt cache changes with your plan and your situation.

Subscription
1 hour

Break for lunch and the cache is still alive when you come back

After usage credits kick in, or via API key and cloud providers
5 minutes

Step away briefly and it goes cold. The next single message re-reads the entire context

Source: Claude Code documentation, Manage costs effectively (the rules for cache lifetime)

The documentation states that the lifetime is one hour on a subscription and drops to five minutes once you start consuming usage credits, and that it defaults to five minutes through an API key or a cloud provider. The moment you hit your limit and cross into extra usage, the cache lifetime shrinks to a twelfth of what it was. In other words, "after you hit the limit" changes more than the unit price: it changes how the cache behaves. The documentation also points to setting the TTL yourself as the way to keep a one-hour lifetime while running on usage credits.

6. MCP is lazy-loaded by default, and CLIs are still lighter

"MCP servers eat your context" also rests on assumptions that have changed. According to the documentation, MCP tool definitions are lazy-loaded by default, and until Claude uses a specific tool, only the tool names and the server description go into the context.

Even so, the documentation says that CLI tools such as gh, aws, gcloud and sentry-cli are still more context-efficient. The reason is plain: a CLI adds no tool listing at all. Claude can run the command directly, so not even the names need to load.

The practical conclusion follows. If a CLI can do the same job, your reason for choosing MCP should live outside the context budget (centralized authentication, structured results, permission control). A server you installed because it looked handy is a candidate to cut, and /mcp shows you the list.

7. What loads on every single turn: CLAUDE.md and the conversation itself

Skills and MCP load conditionally, but two things load unconditionally, every time.

One is CLAUDE.md. It is read into the context when the session starts, so the workflow procedures you wrote there sit in the window the whole time you are working on something unrelated. As a remedy, the documentation recommends moving detailed instructions for specific workflows into skills, and it goes as far as a concrete target: keep CLAUDE.md under 200 lines and to the point. The logic is that a skill loads only when it is called, so the same content stops being a permanent cost.

The other is the conversation itself. The documentation puts it precisely: Claude Code sends the entire conversation with every request, and each time Claude uses a tool it sends another request carrying that tool result. So a one-line question in a session you have had open all day still triggers usage for the whole conversation. Caching brings the unit price down, but not to zero.

This is exactly where the choice between /clear and /compact comes in. The documentation says that /compact reads the conversation it is summarizing, so compacting a large context is itself a large request, and if you want a fresh start rather than continuity, /clear costs nothing. "Just compact it" is not free. Deciding when to press it is covered in detail in Should you run /compact on a schedule in Claude Code?

8. Usage climbs while you are doing nothing

"I only stepped away and my usage went up." There are concrete reasons for that, and the documentation lists them. They all share one shape: a new turn starts and sends the full context even while the session is idle.

What advances usage while you are idle

  • Scheduled tasks: they fire on their interval even when the session is doing nothing, and each firing sends the full context
  • Messages from other sessions: delivered as a new turn while you are idle. Set crossSessionInbound to hold to queue them instead
  • Goal progress checks: while background work is pending, a check turn runs, up to three times between prompts
  • Each member of an agent team: they keep consuming tokens until they finish
  • Cache expiry: the first message after a break re-reads the entire context

Agent teams come with a concrete multiplier. The documentation says that an agent team uses roughly 7x the tokens of a normal session when its members run in plan mode. Each member holds its own context window, so it scales roughly with headcount. The official advice is equally plain: use Sonnet for members, keep the team small, and shut it down when the work is finished.

As a yardstick, the documentation puts the average for enterprise deployments at about $13 per person per working day, or $150 to $250 per month, and says that 90% of users stay under $30 per working day. If your own numbers sit well outside that band, one of the items above is probably in play.

9. Once you have measured, what do you cut first

With numbers in hand, start where the effect is largest. Reordering the countermeasures the documentation lists, from the fastest payoff down, gives you this.

FREE, RIGHT NOW
/clear when you switch to unrelated work

Old context keeps getting billed on every message that follows. Run /rename before you clear and you can come back later with /resume

FIX THE SETUP ONCE
Get CLAUDE.md under 200 lines

Move task-specific procedures into skills. Less loads permanently, and it applies to every session

NARROW THE OUTPUT
Hooks and subagents

Instead of feeding in a 10,000-line log, let a hook return only the lines that matter. Keep verbose processing inside a subagent

LOWER THE UNIT PRICE
Match the model and the effort to the job

Sonnet is enough for most coding. For simple work, dial the thinking down with /effort

The order carries meaning. The first one works from today, and it is free. The second you fix once and it applies to every session. The third and fourth are matters of configuration and habit, so they take a little time to show up. Deleting skills is not near the top because, as the earlier sections showed, that is rarely the biggest factor.

What does not move is that you measure before you touch anything. The official /usage flags any behavior that accounts for 10% or more of recent usage (an overlong context, cache misses and so on). Cutting something that carries no flag will not change what you feel.

FAQ

Q1. How many skills is it safe to have?
There is no cap on the count. What matters is whether they fit the listing's character budget, which is 1% of the context window. The same ten skills will overflow it with long descriptions and fit inside it with short ones. Reading the Skills line of /context and running /skill-doctor is more accurate than counting.

Q2. Can I delete a skill that has never been invoked?
Call it by name before you delete it. If it works when named but never gets picked automatically, it is not unnecessary: its description is losing to the budget. In that case the fix is not deletion but rewriting the description (primary use cases first) or raising the budget.

Q3. Does pressing /compact often make things cheaper?
No. Compaction reads the conversation it is summarizing, so on a large context it is itself a large request. When you do not need continuity, /clear is cheaper (it costs nothing) and more reliable.

Q4. What cache hit rate should I be aiming for?
The documentation gives no pass mark, so watch the change rather than the absolute value. If the rate drops while you work the same way, you probably changed your configuration (MCP, skills, tool definitions) just before. From v2.1.260 on, the line reports its best guess at the cause.

Q5. Should I cut down on MCP servers?
Tool definitions are lazy-loaded by default, so the cost of merely having one installed is lower than it used to be. That said, if a CLI such as gh can do the same job, the CLI is lighter (it adds no tool listing whatsoever). Servers you are not using can be switched off with /mcp.

Q6. Do subagents save context?
They do. The documentation also recommends handing verbose processing (running tests, fetching documentation, chewing through logs) to a subagent, keeping the details in its context and returning only a summary. Note, though, that the cache line in /usage only looks at the main conversation, so in a subagent-heavy workflow those numbers are not the whole picture.

Q7. I cannot run /skill-doctor.
You need Claude Code v2.1.252 or later. It also cannot run over remote control from a phone or a browser, where it returns an error. In an interactive session it opens the Stats tab of the /plugin manager, so if you want text output, run it in non-interactive mode with -p.

Sources