You add a skill. It triggers. You add ten more, and the first one quietly stops firing — same file, same description, same request. Nothing errored, so there is nothing to fix.
This is not a prompt problem. It is a budget problem, and Claude Code exposes every number involved.
What Claude actually sees
Claude Code loads a listing of skill names and descriptions into context so the model knows what is available. The listing always contains every skill name. Descriptions are the part under pressure.
Two limits stack:
-
Per entry. The combined
descriptionandwhen_to_usetext is truncated at 1,536 characters in the listing.when_to_useis appended todescriptionand counts toward the same cap. - Across all entries. The whole listing has a character budget that scales at 1% of the model's context window.
The second one is what changes when you grow from 8 skills to 30. Your description did not get worse; it got crowded out.
What gets dropped first
When the listing overflows, Claude Code drops descriptions starting with the skills you invoke least. The skills you use most keep their full text.
Read that ordering carefully, because it is the opposite of what you want when debugging. The skill that stopped triggering is, by definition, one you have not been invoking — so it is first in line to lose its description, which makes it even less likely to trigger. It is a ratchet.
A skill with no description in the listing is still there and still invokable by name. It just no longer advertises what it is for, so Claude cannot match it to a request on its own.
Measuring it instead of guessing
Two commands, and they answer different questions.
/doctor gives an estimate of the listing's context cost and its biggest contributors. Start here: it tells you which skills are eating the budget, which is what you need before deciding what to trim.
/context has a Skills row that reports the size of the listing after the budget is applied, so it matches what the model actually receives. This matters if you have older habits: before v2.1.196, that row counted the full text of every description and could show a value several times larger than the configured budget. If you remember the Skills row being alarmingly big and stopped looking at it, look again.
When the listing exceeds its budget, Claude Code also writes a warning to the debug log, visible with --debug.
Three ways to fix it
Trim at the source, front-loading the use case. Each entry is capped at 1,536 characters regardless of budget, and truncation takes the tail. That makes sentence order functional rather than stylistic: the concrete trigger case belongs in the first sentence, the caveats and background at the end where they are cheapest to lose. If you cap out at 1,536 characters on a single skill, that skill's description is doing a job the skill body should be doing.
Demote the skills you always call by name. skillOverrides controls skill visibility from settings rather than the skill's own frontmatter, which is what you want for skills checked into a shared repo you would rather not edit. Setting an entry to "name-only" lists the skill without a description: it stays invokable as /thing, it just stops spending description budget. "off" removes it from the listing entirely.
{
"skillOverrides": {
"release-checklist": "name-only",
"legacy-migration": "off"
}
}
A skill absent from skillOverrides is treated as "on". The /skills menu writes this file for you — highlight a skill, press Space to cycle states, Enter to save to .claude/settings.local.json. Plugin skills are not affected by skillOverrides; manage those through /plugin.
Raise the budget, once you know why. skillListingBudgetFraction takes a fraction of the context window (0.02 for 2%), or SLASH_COMMAND_TOOL_CHAR_BUDGET sets a fixed character count. The per-entry cap is separately configurable with skillListingMaxDescChars.
Raising the budget is the right move when you genuinely have many distinct skills. It is the wrong move when you have six skills that overlap, because you will pay context on all six every session to avoid choosing between them.
The overlap question
Which brings up the failure mode a budget increase cannot fix. If two skills could plausibly answer the same request, the listing is now a coin flip, and the model resolves it from names and descriptions alone.
The cheapest test: write down the request in the user's words, then read both descriptions and ask which one you would pick. If you hesitate, Claude will too. Either merge them, or add the negative case — "not for X, use /y for that" — to whichever one loses more often. A sentence that says who a skill is not for is usually worth more listing budget than another sentence about what it does.
One more place descriptions matter
Auto-compaction carries invoked skills forward within a token budget: when the conversation is summarized, Claude Code re-attaches the most recent invocation of each skill after the summary, keeping the first 5,000 tokens of each, with a combined budget of 25,000 tokens. It fills that budget starting from the most recently invoked skill.
So in a long session where you invoked many skills, the oldest ones can be dropped entirely after compaction. If a skill's behavior seems to evaporate mid-session rather than never appearing at all, that is a different mechanism from the listing budget — and re-invoking it is the fix.
The short version
- Descriptions are capped at 1,536 characters per entry and share a listing budget of ~1% of the context window
- Overflow drops descriptions from your least-invoked skills first, which makes a quiet skill quieter
-
/doctorfinds the biggest contributors; the/contextSkills row shows the post-budget size -
"name-only"inskillOverridesfrees budget without deleting anything - Raise the budget only after you have ruled out overlap between skills
All behavior above is from the Claude Code skills documentation as of July 2026; version-gated details (/context accuracy in v2.1.196, /doctor remaining typable in v2.1.205) are called out where they apply.
I maintain Rulestack — packs of rules, skills, and hooks for Claude Code, Cursor, and Codex, kept current with each tool's actual behavior.
I post one of these findings a day on Bluesky at @ai-shop.bsky.social — mostly the small mechanics that decide whether your config does anything.
Top comments (22)
Skill listing budgets are going to matter more as people add more specialized workflows. A skill that exists but is never surfaced is functionally missing.
The hard part is making descriptions do two jobs at once: precise enough to trigger at the right moment, but compact enough to survive retrieval and listing constraints. That turns skill authoring into information architecture, not just prompt writing.
"Information architecture, not just prompt writing" is a good way to put it — and those two jobs really do trade against each other, since widening a description to catch more cases tends to make it collide with a neighbour.
I gave up on judging mine by reading them and started scoring them instead — a small corpus of prompts with the skill I expect for each, including negatives where nothing should fire. The negatives turned out to be where the collisions showed up: a skill that matches everything looks fine on recall, right up until I counted the turns it was taking from its neighbours.
Yes, and once skills become numerous, discovery becomes part of correctness. A good skill that never makes the active context is effectively unavailable. I think teams will need skill catalogs with budgets, tests, and pruning rules, not just more markdown.
"Discovery becomes part of correctness" is a great way to put it. The part I keep bumping into: pruning is the lever that reliably helps at scale, because every extra borderline description doesn't just cost budget — it adds one more wrong-trigger candidate. Curious what a skill catalog test would assert for you — trigger precision on a fixed prompt set, or something more structural?
I’d probably treat it like a search evaluation problem rather than a unit test.
Trigger precision and recall on a representative prompt corpus would be the baseline, but I’d also measure overlap. If adding or editing one skill significantly changes which other skills fire, that’s a regression even if the edited skill itself improves.
Another useful metric is trigger stability. Small wording changes to the same user intent shouldn’t completely change the selected skill. If they do, the descriptions are probably encoding lexical cues rather than semantic intent.
So I’d end up with three signals: precision/recall, overlap regression, and trigger stability. Together they tell you whether the skill catalog is becoming more predictable as it grows.
The overlap-regression signal is the one I'd have missed, and it's extra sneaky in this specific context: because the listing budget is shared, lengthening one skill's description can evict a different skill from what Claude sees at all. So skill B's triggering can regress without any semantic interaction between the two — pure budget displacement. Your trigger-stability point also doubles as a lint for descriptions: if paraphrasing the intent flips the selection, the description is keying on words, not the task. Have you tried running anything like that corpus in CI, or is this framework aspirational for you too?
Not in CI yet—it’s more of a design framework than a production pipeline today.
If I were to automate it, I’d treat the skill catalog almost like a retrieval benchmark. A fixed corpus of prompts, expected skills, paraphrases, and negative cases would become part of CI. Any PR that changes trigger precision, overlap regression, or trigger stability beyond an acceptable threshold would require review, just like a performance regression.
The interesting part is that, in your case, I’d also add a budget regression check. Since the listing budget is shared, a PR shouldn’t only be evaluated for semantic changes—it should also report which skills lost description coverage because of the new budget distribution. At that point, “context budget” becomes a first-class resource, much like CPU, memory, or latency in traditional systems.
A budget regression check is the piece I would not skip. Skill catalogs fail in weird ways because one improved description can crowd out a different skill entirely. Treating that as a shared retrieval budget makes the evaluation more realistic than testing each skill alone.
That shared-budget failure mode is sneaky enough that it probably deserves its own metric. A skill can get better locally while making the catalog worse globally. I would want CI to show both: did this skill trigger better, and what did it displace?
I have not seen many teams running that kind of corpus seriously yet, but I think it is the right test shape. The negatives are especially important because over-triggering feels helpful during demos and expensive during real work.
Search evaluation is the right analogy. I would also save the prompt corpus over time instead of constantly rewriting it, because regressions only show up when the same intents keep hitting the catalog across changes.
Saving the corpus over time is the piece I'd underline — a rewritten corpus can't tell you what regressed, because the baseline moved with it. Pinned intents plus the fixed expected-skill pairs @merbayerp described would make the eviction metric comparable across changes: same queries, did the catalog's answer change, what got displaced. Do you keep a corpus like that versioned next to the skills it tests, or somewhere separate?
I’d keep it versioned next to the skills, ideally in the same repository but in a separate test directory.
That way, every change to a skill description and its expected retrieval behavior lands in the same PR, so the regression is visible and reviewable. I’d only move the corpus to a separate repository if multiple teams or products shared the same catalog and needed an independent benchmark.
For a single catalog, proximity wins: skills, prompts, expected matches, negatives, and budget snapshots should evolve together.
Proximity wins is the right call — the moment the corpus lives in another repo, description changes and their expected-retrieval updates stop landing in the same PR, and the benchmark quietly diverges from the catalog it's supposed to guard. The budget-snapshot point is the part I'd underline: retrieval regressions are often caused by other skills' descriptions growing, so a snapshot of the whole listing at test time is what makes a failure explainable. Thanks — this is a cleaner setup than the one I sketched in the post.
That “catalog drift” point is the one I would keep close to the tests. A retrieval benchmark that is not tied to the current listing can pass while the real agent experience gets worse. Whole-corpus snapshots make the failure much easier to explain.
That is a solid boundary. For one catalog, keeping skills, negative examples, expected matches, and budget snapshots together makes review much more honest. A separate repo only starts to make sense when multiple products need the same benchmark contract.
Agreed on the boundary — the benchmark contract only earns its own repo once a second product actually wants it; before that it's speculative structure. And drift is the failure mode that hides best: green benchmark, worse real listing. Have you had a snapshot diff catch a regression the benchmark itself missed?
I think this is a classic precision vs. recall problem. As the number of skills grows, optimizing each skill independently isn’t enough—you need to optimize the entire skill ecosystem. Sometimes deleting, merging, or narrowing a skill improves the overall trigger quality more than adding another description.
The precision/recall framing matches what I've seen — and merging is the underrated one of your three. In my case two skills with adjacent descriptions didn't just split recall, they kept competing for the same trigger and losing to each other; merging them made the combined skill fire more often than the pair had separately. Have you found a good heuristic for when to merge vs narrow?
A heuristic that has worked well for me is this:
Merge when two skills share the same user intent, differ mostly by implementation detail, and would usually require the same initial context. If choosing between them depends on information the user has not provided yet, they probably belong behind one router skill.
Narrow when the intent is genuinely different, but the wording overlaps. In that case, each description should include a clear positive trigger and a negative boundary: “Use this for X, not Y.”
I also look at correction patterns. If the model frequently chooses one skill and then has to switch to the other, merge them. If it triggers both for requests that should clearly belong to only one, narrow the boundaries.
So for me: repeated handoff suggests merge; repeated ambiguity suggests narrow.
That correction-pattern lens is the piece I was missing — repeated handoff vs repeated ambiguity gives you an observable signal to act on, instead of a design-time guess about intent. And the negative boundary in descriptions ("Use this for X, not Y") is underrated; I've seen very few skill authors state what a skill is not for, even though that's exactly what the model needs when two descriptions overlap. Definitely stealing both framings — thanks for taking the time to write this up properly.
good!