Too many Claude Code skills? How the listing budget decides which descriptions Claude sees

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:

1. Per entry. The combined description and when_to_use text is truncated at 1,536 characters in the listing. when_to_use is appended to description and counts toward the same cap.
2. 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
• /doctor finds the biggest contributors; the /context Skills row shows the post-budget size
• "name-only" in skillOverrides frees 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.

Comments

[Alex Shev]

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.