Claude Code reserves roughly 15,000 characters of system prompt space for skill descriptions combined. Each individual skill description has a 1,024-character hard cap. To audit your total: open every SKILL.md in your skills folder, sum the character counts of each description field, and compare against the 15,000-character ceiling. AEM's preflight check runs this audit automatically before every multi-skill deployment.
TL;DR: Add up the description field length of every SKILL.md file in your project. Keep the total under 15,000 characters. If any single description exceeds 1,024 characters, Claude truncates it silently, which breaks trigger matching for that skill. Most developers with 10 to 20 skills are under the limit. Libraries of 30 or more skills cross it regularly.
What Is the System Prompt Character Budget?
The system prompt character budget is approximately 15,000 characters total across all installed skill descriptions, controlled by the SLASH_COMMAND_TOOL_CHAR_BUDGET configuration, with a 1,024-character hard cap per individual skill. Both limits apply simultaneously. Exceed either one and Claude silently truncates or drops skills with no error or warning.
When Claude Code starts a session, it reads the name and description field from every skill's SKILL.md frontmatter and inserts that content into its system prompt. This is how Claude knows which skills are available and when to trigger them. The system prompt has a fixed capacity: the current budget for all skill descriptions combined is approximately 15,000 characters, equivalent to around 4,000 tokens as of Claude Code 2.0.70 (Jesse Vincent, "Claude Code Skills Not Triggering?", blog.fsck.com, December 2025). This is not a soft suggestion. When the total exceeds the budget, skills at the end of the list get truncated or dropped.
Each skill description also has an individual cap of 1,024 characters, including spaces. A description that exceeds 1,024 characters gets cut at the limit. The text after the cut disappears from the system prompt with no error or warning. Claude never tells you it truncated a description.
"Models placed in the middle of long contexts lose track of instructions at a rate that makes mid-context policy placement unreliable for production systems." — Nelson Liu et al., Stanford NLP Group, "Lost in the Middle" (2023, ArXiv 2307.03172)
Skills appended past the budget occupy exactly this mid-to-late position in the context. Activation reliability drops before the skill disappears entirely. The official Claude Code documentation confirms the budget scales dynamically at 1% of the available context window, with a hard fallback floor of 8,000 characters on constrained sessions (Anthropic, Claude Code Skills Documentation, code.claude.com, 2026).
How Do I Count My Total Description Characters?
The manual method works for libraries under 20 skills: open each SKILL.md file, locate the description field in the frontmatter, and count its characters. Sum those counts across every skill in your .claude/skills/ folder and compare the total against the 15,000-character ceiling. Metadata scanning costs approximately 100 tokens per skill at startup, so 10 installed skills consume around 1,000 tokens in system prompt overhead before you write a single line of conversation (Jim Quote, "Claude Skills vs MCP: Complete Guide to Token-Efficient AI Agent Architecture," DEV Community, 2025). A description like this:
description: "Runs the weekly review process for personal brand metrics and pipeline."
Is 75 characters including the quotes. Do this for every skill in your .claude/skills/ folder, add the numbers up, and compare against 15,000.
For teams with 30 or more skills, the shell method is faster:
grep -r "^description:" .claude/skills/ | awk -F'"' '{print length($2), $0}' | sort -rn
This prints each description with its character count, sorted longest first. You'll see immediately which descriptions are approaching the 1,024-character individual limit and which skills together push the total over the ceiling.
The output looks like:
847 ./skills/my-long-skill/SKILL.md:description: "..."
312 ./skills/code-reviewer/SKILL.md:description: "..."
88 ./skills/summarizer/SKILL.md:description: "..."
Sum the first column for the total. Sort by count to find which descriptions to trim.
Real-world measurements confirm the risk is not theoretical. Independent research tracking a 63-skill library found Claude Code displayed only 42 skills, silently hiding 21 (33% of the installed library) with no warning to the developer (Alexey Pelykh, "Claude Code Skill Budget Research," GitHub Gist, 2025).
How Do I Know When I'm Over Budget?
The symptom of exceeding the overall budget is gradual degradation, not a clean failure. We audit total description character count in the preflight check for every multi-skill project. Skills that were reliable start activating less consistently, and the last skills installed are the first ones to fail. No error message, no log entry, no warning from Claude.
The individual 1,024-character limit has a more specific symptom: a skill's trigger matching becomes unreliable even though the description seems correct. The skill activates for some prompts and misses others with no obvious pattern. This is what truncation looks like from the outside. The middle portion of the description (the nuanced trigger conditions) gets cut, and only the opening sentence survives.
The reliability numbers are stark. In structured testing of Claude Code skill activation, skills available without explicit invocation were never triggered in 56% of cases. Even with explicit user instructions, the invocation success rate topped out at 79% (Pere Villega, "Claude Code Skills 2.0: What Changed, What Works, What to Watch Out For," 2026).
The diagnostic: count the description field character by character. If it's over 1,024, you found the cause.
Which Descriptions Should I Trim First?
Start with the longest descriptions, because they carry the most redundancy and shrink the fastest. A description at 800 characters can almost always be rewritten to under 300 without losing trigger precision. A description at 90 characters is already doing its job. Sort by length, then work down the list using this three-step rewrite process:
Separate "what it does" from "when to use it": most bloated descriptions spend too many words on the task and too few on the trigger condition; invert the ratio if the skill isn't activating reliably.
Cut generic context: "This skill helps developers who work with Claude Code to automate their code review process by analyzing code quality, identifying issues, and providing feedback" contains three phrases that repeat the same point. "Runs automated code review: analyzes quality, flags issues, formats feedback as a structured report" says the same thing in 87 characters.
Make the trigger condition specific: generic descriptions activate on too many prompts or too few. "Analyzes Python code when the user asks for a review or mentions code quality" is more specific than "helps with code analysis." Specific descriptions use fewer characters and trigger more reliably.
The payoff from rewriting is measurable. Optimized descriptions improve skill activation rates from 20% to 50%, a 2.5x lift from description changes alone (mellanon, "Claude Code Skills Structure and Usage Guide," GitHub Gist, 2026). Practitioners working with production skill libraries recommend capping active skills per project at 5 to 8, noting that beyond that count, "debugging why a skill didn't fire takes longer than doing the task manually" (Pere Villega, "Claude Code Skills 2.0," 2026). Trimming your highest-character descriptions gets you back under that threshold without culling skills entirely.
For guidance on writing descriptions that trigger correctly after trimming, see The SKILL.md Description Field: The One Line That Makes or Breaks Your Skill.
What Happens to Skills Past the Budget Limit?
Skills installed after the total budget is reached get incomplete or missing descriptions in the system prompt. Claude may still load them via /skill-name explicit invocation because explicit invocations bypass description matching. But automatic triggering stops working because the description that controls automatic activation isn't fully present.
This is the "skill works with /skill-name but not automatically" failure that confuses most developers into thinking the description is wrong, when the real problem is that the description isn't fully in the system prompt at all. The fix is not rewriting the description. It is reducing the total description budget to bring all skills back under the ceiling.
For related debugging on the auto-trigger failure specifically, see My Skill Works via Slash Command but Not When Claude Should Auto-Trigger It.
This pattern does not apply to skills you intentionally keep short. Skills with 60 to 80-character descriptions cost almost nothing toward the budget and can be added to any project without concern. When description budgets are managed correctly, each skill consumes "a few dozen extra tokens" in standing system prompt overhead, making concise skill libraries genuinely lightweight (Simon Willison, simonwillison.net, October 2025).
FAQ
For most skill libraries under 30 skills with descriptions averaging 150 to 250 characters, the description budget is not a constraint. Libraries of 40 or more skills with verbose descriptions regularly hit the ceiling. The questions below address the exact limits, how to measure them, and what silent failure looks like from the outside.
What is the exact character budget for Claude Code skill descriptions?
The total budget is controlled by the SLASH_COMMAND_TOOL_CHAR_BUDGET environment variable, which defaults to approximately 15,000 characters. Individual skill descriptions have a 1,024-character hard cap. Both limits apply simultaneously: a description can be under 1,024 characters but still push the total over 15,000.
How many skills can I have before hitting the budget? At an average description length of 300 characters, 50 skills use 15,000 characters. At 150 characters average, 100 skills fit. At 500 characters average, 30 skills reach the limit. The number depends entirely on description length, not skill count.
Does a skill's body text count against the description budget?
No. The budget applies only to the description field in the SKILL.md frontmatter, not the body. Long SKILL.md files cost tokens when the body loads, but that's a separate issue from the description budget. See Why Can't I Just Put Everything in One Big SKILL.md File? for the body-loading cost model.
Can I check the budget without counting manually?
Yes. The /skills command lists all loaded skills. If a skill you installed doesn't appear in the list, it's either at the wrong path, has broken frontmatter, or was truncated due to budget overflow. Use the shell command in this article to find which skills are consuming the most characters.
Will Claude warn me when I'm approaching the description budget? No. Claude Code provides no warning when skill descriptions approach or exceed the character budget. Budget overflow is a silent failure. The only signal is degraded activation reliability in skills installed toward the end of the list.
Is the 15,000-character budget per project or per user? Per session context. A project-level skill and a user-level skill both count toward the same budget in a given session. If you have both project and user skills active, their descriptions add together against the single 15,000-character ceiling.
Does reordering my skills change which ones stay under budget?
Skills load in filesystem order within the .claude/skills/ directory. Skills that load last are the first to be cut when the budget is exceeded. If you have critical skills that must activate reliably, keep their descriptions short enough to guarantee they're under the individual cap, regardless of total ordering.
Last updated: 2026-04-22