Skill description budget silently truncates routing information, causing skill routing failures

Summary

The skill description budget system (skillListingBudgetFraction = 0.01) silently truncates or removes skill descriptions from the system prompt when the total exceeds ~8,000 characters. This causes Claude to lose routing information and fall back to manual implementations instead of using available skills.

Power users with 20+ custom skills per project consistently hit this limit without any warning. The result is that Claude ignores well-documented skills and writes custom scripts — exactly the opposite of the intended skill system behavior.

Evidence

Budget calculation (from binary analysis, v2.1.159)

budget = contextWindow * bytesPerToken * skillListingBudgetFraction
       = 200,000 * 4 * 0.01
       = 8,000 chars

Real-world impact

| Project | Skills | Total desc chars | vs Budget |
|---|---|---|---|
| ai-video-pipeline | 25 | 12,274 | 153% (over) |
| ppc-factory | 56 | 8,311 | 104% (over) |
| content-publishing | 41 | 6,542 | 82% |
| web-factory | 22 | 2,801 | 35% |

When over budget, the system enters "truncate" or "names-only" mode — skill descriptions are silently removed. Claude can see the skill names but not when to use them.

Observed behavior

With a project containing 25 skills (each ~490 chars, within the recommended 400-500 char guideline):

1. Claude ignores project-specific skills (e.g., avp-runpod with detailed routing rules)
2. Claude writes custom scripts instead of invoking available skills
3. Claude violates operational rules that ARE documented in skill descriptions (e.g., region pinning, network volume requirements)
4. This leads to costly mistakes: wrong GPU regions, orphaned cloud resources, API key exposure

The user sees no indication that descriptions were truncated

There is no warning, log message, or status indicator that skill descriptions were removed. The user writes detailed skill descriptions following the recommended guidelines, and the system silently discards them.

Root cause

The formatCommandsWithinBudget function (pk8 in minified source) implements four modes:

1. "fits" — all descriptions fit → no truncation
2. "priority" — low-priority descriptions removed
3. "truncate" — descriptions uniformly shortened
4. "names-only" — descriptions removed entirely (threshold: uk8 = 20 chars)

The default skillListingBudgetFraction = 0.01 (1%) is far too low for power users with domain-specific skill libraries.

Workaround

Setting SLASH_COMMAND_TOOL_CHAR_BUDGET in settings.json env overrides the budget:

"env": {
  "SLASH_COMMAND_TOOL_CHAR_BUDGET": "30000"
}

This is undocumented and was found only through binary analysis.

Asks

1. Increase the default budget — 1% of context is too restrictive for the skill system to function as designed
2. Add a visible warning when skill descriptions are truncated — currently this is completely silent
3. Document the budget settings — SLASH_COMMAND_TOOL_CHAR_BUDGET, skillListingBudgetFraction, skillListingMaxDescChars are not in any user-facing documentation
4. Consider dynamic budget allocation — scale the budget based on actual skill count rather than using a fixed fraction

Environment

• Claude Code: v2.1.159
• Model: claude-opus-4-6
• OS: macOS (Darwin 25.5.0)
• Installation: Homebrew cask (claude-code@latest)

Related issues

• #62562 — Opus 4.7 tool-use compliance cliff (may be partially caused by this budget system)
• #64520 — autocompact silently disabled in v2.1.159
• #56760 — CLAUDE.md contradictory system instructions