A Claude Code skill library that works at 5 skills can behave differently at 20. Activation rates drop. Skills that once fired reliably start missing. Claude's responses feel less precise. The cause isn't usually the skill instructions. It's the system prompt budget. When skill descriptions together exceed the character limit, the excess gets truncated, which means Claude never sees the full description of your last-loaded skills.

TL;DR: Token budget failures in large skill libraries show up as selective activation failures in recently added skills, degraded instruction adherence in long sessions, and skills that work in isolation but fail when the full library is loaded. Diagnose by counting total description characters, checking against the 15,000-character system prompt limit, and running /skills to verify which skills loaded. Fix by trimming descriptions, splitting large skills, or adjusting SLASH_COMMAND_TOOL_CHAR_BUDGET.

What Are the Symptoms of a Token Budget Problem?

Budget issues present differently from instruction failures, which makes them easy to misdiagnose.

Symptom 1: Skills activate in isolation but fail when the full library is loaded. If a skill works correctly in a project with only 3 skills but fails when you have 25, the problem is budget, not the skill itself. The description is being truncated by the competing descriptions of other skills.

Symptom 2: The most recently added skills fail more often than established ones. When skills load into the system prompt, they load in a consistent order. Skills loaded later in that order are the first to be crowded out when the budget is exhausted. New skills fail not because they're worse. They were added last.

Symptom 3: Skill instructions are followed less reliably as sessions grow longer. This is different from description truncation. In long sessions, additional context accumulates and competes with the loaded skill content. Research by Nelson Liu et al. at Stanford found that models lose track of instructions placed in the middle of long contexts at a rate that makes mid-context instruction placement unreliable for production systems (ArXiv 2307.03172, 2023).

Symptom 4: The /skills command shows fewer skills than you have installed. If /skills returns a list that's missing some of your installed skills, they aren't loading at all. Either a frontmatter parsing error or a budget limit cut them from the system prompt.

How Do You Measure Your Total Token Budget Consumption?

Claude Code's system prompt budget for skill descriptions is approximately 15,000 characters. Each skill description costs roughly 100-200 characters (the description field itself) plus overhead for frontmatter parsing. A library of 20 skills with 500-character descriptions uses 10,000+ characters, close to the limit.

The fastest measurement: count description field characters across all skills.

  1. Open each SKILL.md and count the character length of the description: field value.
  2. Sum the counts.
  3. If the total exceeds 12,000 characters, you're in the risk zone. At 15,000 or above, expect truncation.

For a precise count using a script, see How Do I Check the Total Character Count of All My Skill Descriptions?.

The SLASH_COMMAND_TOOL_CHAR_BUDGET environment variable controls the character budget ceiling. The default is 15,000. To raise it, set SLASH_COMMAND_TOOL_CHAR_BUDGET=25000 in your environment. Raising the limit accepts a higher startup token cost in exchange for more available skill space.

How Do You Use the /skills Command for Budget Diagnostics?

The /skills command lists every skill Claude currently has loaded. Run it at session start before any other prompts to get a clean baseline count.

Three diagnostic questions to answer from /skills output:

1. Are all your installed skills listed? If you have 22 skills installed but /skills returns 18, four are excluded. Check the four missing skills for YAML parsing errors first (multi-line descriptions, incorrect indentation). If the frontmatter is valid, the issue is budget.

2. Does the order match your installation order? Skills load from disk in a consistent order. If the skills loaded last are the ones most likely to fail, that confirms budget crowding rather than a skill-specific bug.

3. Does re-running /skills in a new session produce the same list? If the list is inconsistent between sessions, there's a file system or caching issue, not a budget issue.

For the full guide to using /skills for debugging, see What's the /skills Command and How Do I Use It for Debugging?.

What Are the Techniques for Reducing Budget Consumption?

Four approaches in order of effectiveness:

Trim description fields. The description field should be 100-200 characters for standard skills. If any of your descriptions exceed 300 characters, they're using disproportionate budget. Trim to the essential trigger phrase and scope statement. Descriptions over 200 characters show no better activation rates than concise ones in our builds.

Split oversized skills. A skill that handles three distinct workflows should be three skills with focused descriptions. Counterintuitively, three 80-character descriptions use less budget than one 400-character description, and they activate more reliably.

Move domain-specific context to reference files. If your description currently contains context that helps Claude execute the skill rather than trigger it, that context belongs in the SKILL.md body or a reference file. The description's only job is triggering. Everything else is instruction overhead.

Audit for zombie skills. Skills you built and never deleted still consume budget even if you never invoke them. A 20-skill library often contains 5-8 skills that haven't been invoked in weeks. Archive unused skills to a backup folder. They stop consuming budget and can be restored if needed.

"Developers don't adopt AI tools because they're impressive — they adopt them because they reduce friction on tasks they repeat every day." — Marc Bara, AI product consultant (2024)

How Do You Test Whether Budget Reduction Fixed the Problem?

After trimming or reorganizing your skill library:

  1. Count total description characters again. Confirm you're under 12,000.
  2. Load the full library in a fresh session. Run /skills and verify all installed skills are listed.
  3. Run your five most commonly used skills with their typical trigger prompts. Verify each activates correctly.
  4. Check the skills that were failing before the change. Test them with the same prompts that produced failures.

If the previously failing skills now activate correctly, the budget was the cause. If they still fail, the problem is in their description or frontmatter, not the budget.

For the longer view on how token economics shape skill library architecture, see How Does Progressive Disclosure Save Tokens and Improve Performance?.

Frequently Asked Questions

How do I know if SLASH_COMMAND_TOOL_CHAR_BUDGET is actually limiting my skills? Check your total description character count. If the sum is under the current budget ceiling (default 15,000), the environment variable is not the constraint. If the sum exceeds it, raising the ceiling will allow more skills to load, but each loaded skill adds to startup token cost.

Do reference files count toward the system prompt budget? No. Reference files load on demand, not at startup. Only the description field from each SKILL.md frontmatter loads at startup. The SKILL.md body loads when the skill is invoked. Reference files load when the skill body instructs Claude to read them. Budget exhaustion only affects the description layer.

Can I prioritize which skills load first when I'm near the budget limit? Skill load order follows file system order, typically alphabetical by folder name. Skills in folders named with lower letters or numbers load earlier. If a skill must always load, prefix its folder name: 00-critical-skill/ loads before analytics-skill/.

What's the difference between a token budget issue and a context window issue? Token budget issues affect which skills load at session start (the system prompt layer). Context window issues affect Claude's ability to attend to all loaded content during a long session. Budget fixes involve reducing description character counts. Context window fixes involve shortening sessions or using progressive disclosure to keep active context small.

Does the total number of skills matter or just the total character count? Character count is what matters for budget. A library of 50 skills with 100-character descriptions is fine. A library of 10 skills with 1,500-character descriptions is near the limit.

What happens when I add a new skill to an already-full budget? The skill installs but loads inconsistently. It competes for the remaining budget with all other loaded skills. The last-added skill loses that competition most often.

Last updated: 2026-04-23