Overflowing Claude Code's skill listing strips the descriptions the model triggers on
One developer found roughly 70 of his 112 installed skills reduced to bare names in the system prompt, and nothing in the tool had flagged it, because the listing budget drops descriptions without erroring.
The Engineer · Build desk
What happened
- Claude Code packs every skill's name and description into the system prompt at session start, and that listing is the model's only inventory of what it can reach for.
- Past the budget the description is evicted while the name is kept, so the skill still answers to /skill-name but can no longer surface on its own.
- The author says he decompiled the local binary and found the budget set to 1 percent of the context window by skillListingBudgetFraction, alongside a 1536-character per-skill cap.
- His own toolbox measured 89 project skills at about 22,700 characters plus 23 global ones at 11,700, roughly 34,400 against a default budget of 8,000.
Why it matters
- What it limits constraint Eviction takes the least-used skills first, so a skill that never fires loses the description that would let it fire, and it stays at the front of the queue the next time the listing overflows.
- Who has to decide decision Pruning on invocation counts stops being defensible until the budget is fixed: 79 of his 89 skills had never been explicitly invoked, a number that mixes dead weight with tools the model was never told about.
- What it costs cost The override is upkeep rather than a one-time config edit, since two weeks after he raised it the listing had refilled and eight more skills lost their descriptions.
- What doesn't add up contradiction These defaults have one witness, the author himself, who says the community write-ups he checked were second-hand and wrong, so anyone relying on the figures is relying on his read of the binary.
Dividing the budget by the toolbox shows why the default is not a ceiling you can just nudge. Eight thousand characters spread across 112 skills [21] gives each about 71 characters, names included [24], while his descriptions average around 307 [23]. The measured listing ran 4.3 times over [22]. The per-skill cap makes the same point from the other end: five skills written up to the 1536-character maximum [11] consume 7,680 characters, about 96 percent of a 200K window's allowance [25].
That is why trimming alone does not clear it. Rewriting every description to under 250 characters [19] still leaves 26,342 characters of listing, roughly 3.3 times the default [27]. The escape hatch is `SLASH_COMMAND_TOOL_CHAR_BUDGET`, which replaces the fraction calculation outright [3], and the author set it to 45,000 across two config files [17].
At that point the listing becomes a standing cost. Work backwards from the published equivalence, 8,000 characters for 1 percent of a 200K-token window, and the implied conversion is about four characters per token [28]. A 45,000-character listing is therefore near 11,250 tokens, roughly 5.6 percent of a 200K context, sitting in the system prompt of every session [29]. Trimming is what keeps that figure from climbing.
The verification step is the part I would copy. He opened a headless sub-session and forced it to quote, verbatim, the description of a skill that had previously been name-only, then compared the words to the file [17]. That separates a config value you edited from text the model can actually see. A skill that can only be reached by typing its name functions as a slash command with a folder around it [9].
Which leaves the A/B. He cut 10,400 characters and reports no systematic decline in trigger rate, while explicitly refusing to claim an improvement, because two cases either way is noise at his sample size [31]. Read it as a result about his 41 tools. For the number to transfer, your descriptions would need a comparable share of what he cut: the same sentence written twice in two languages, long enumerations, and restatements of the SKILL.md body [5]. Your invocations would also need to hinge on the identifiers and symptom phrases he kept, since the description is the entire basis for the model's decision to reach for a skill, and a deleted trigger word simply stops working, with no error and no warning [20]. His first pass, cutting whatever felt redundant, was abandoned for the honest reason: he had no way to prove he had not removed something load-bearing [4].
What to watch
- Whether the defaults skillListingBudgetFraction 0.01 and skillListingMaxDescChars 1536 turn up in published documentation, which would move this off a single reading of the binary.
- Whether the CLI starts reporting how many skill descriptions it evicted at session start, since the eviction currently produces no output.
- A repeat A/B with per-case counts published, which would show whether the trimmed descriptions cost any triggers at all.
Clarity's read
What the record supports and how the coverage leans. The claims behind it follow.
Reality
- Evidence52
- Adoption14
- Hype gap−12
- Incentives34
- Confidence46
Claim ledger
Ranked by verification strength, evidence, and original report placement.
- [1]
The listing budget is 1 percent of the context window, controlled by a setting called skillListingBudgetFraction with a default of 0.01.
- [2]
A 200K-token window yields a budget of approximately 8,000 characters; a 1M-token window yields approximately 40,000.
- [3]
The environment variable SLASH_COMMAND_TOOL_CHAR_BUDGET overrides the whole budget calculation.
- [4]
His first approach was deleting the redundant-feeling parts, which he abandoned because he had no way to prove to himself that he had not cut something load-bearing.
- [5]
His trim targets were the same sentence written twice in two languages, enumerations trimmed down to three items, and restatements of the SKILL.md body; trigger words such as identifiers and symptom phrases were kept.
- [6]
In Claude Code, each skill is a folder containing a SKILL.md file whose frontmatter carries a name and a description field.
- [7]
At session start, every skill's name plus description is packed into the model's system prompt, and that listing is the only way the model knows what tools it has; it cannot see the folders or read the files.
- [8]
The skill listing has a character budget, and when it is exceeded the description is dropped while the name is kept.
- [9]
A skill whose description has been evicted stays on the list and can still be invoked manually as /skill-name, but will never surface on its own, and no error or warning is produced.
- [10]
The author says he decompiled the local Claude Code binary to establish the rule, because the community blog posts describing it were second-hand and wrong.
- [11]
There is a per-skill cap, skillListingMaxDescChars, defaulting to 1536 characters.
- [12]
The author measured 89 project skills at about 22,700 characters plus 23 global skills at about 11,700 characters, roughly 34,400 in total, against a default budget of 8,000.
- [13]
In his available-skills listing, roughly 70 entries were name-only.
- [14]
The documentation states the eviction order, quoted as "starting with your least-used skills."
- [15]
The author describes the resulting loop: never used, description evicted, model cannot see it, used even less, evicted first again.
- [16]
He had separately measured that 79 of his 89 skills had never been explicitly invoked, and says that figure was contaminated by two things at once: skills that were genuinely not useful, and budget overflow that meant the model was never told they existed.
- [17]
He raised the budget by setting the environment variable to 45000 in two config files, then verified end to end by opening a headless sub-session and forcing it to quote verbatim the description of a skill that had been name-only; the quoted words matched the file.
- [18]
Two weeks later the budget was full again as skills kept accumulating, and 8 skills were stripped to names.
- [19]
By his arithmetic, squeezing every description under 250 characters saves 8,058 characters, while deleting all 51 least-used "tier C" skills saves 11,295.
- [20]
The description is the basis on which the model decides whether to invoke a skill, so cutting a trigger word can make it silently stop firing in that situation with no error.
- [21]
His installation totalled 112 skills.
- [22]
A 34,400-character listing is about 4.3 times the default 8,000-character budget.
- [23]
His skill descriptions averaged about 307 characters each.
- [24]
The default 8,000-character budget allows about 71 characters per skill across 112 skills, names included.
- [25]
Five skills written up to the 1536-character per-skill cap consume 7,680 characters, about 96 percent of the default 8,000-character budget.
- [26]
Trimming every description under 250 characters recovers about 71 percent of what deleting the 51 least-used skills would recover.
- [27]
After the sub-250-character rewrite, the listing would still be 26,342 characters, about 3.3 times the default budget.
- [28]
The stated equivalence of 8,000 characters to 1 percent of a 200K-token window implies a conversion of about four characters per token.
- [29]
A 45,000-character listing is roughly 11,250 tokens, about 5.6 percent of a 200K-token context window.
- [30]
Roughly 70 name-only entries out of 112 skills is about 63 percent of the installation.
- [31]
He cut 41 AI tools' self-descriptions, removing 10,400 characters or about 40 percent of the characters, and reports no systematic decline in trigger rate; he states that plus or minus two cases at his sample size is noise, so he does not claim it improved.
Get this ledger inside ChatGPT. Ask about any of our stories and the answer brings its figure, each claim’s verdict and the sources. Free, no account.
Sources
1 independent publisher whose own reporting we read for this story.
- dev.toI cut 41 AI tools' self-descriptions in half, then A/B tested that trigger rate didn't drop
1 article · August 28, 2026
Topics and entities
Follow any of these and your For You feed starts watching them — no settings page required.
Topics
- Agent ObservabilityFollow
- Context Window BudgetingFollow
- Silent Failure ModesFollow
- Claude Code SkillsFollow
- Agent tool selection behaviorFollow