[Bug] Skill listing truncated with descriptions dropped due to context budget constraints

Status Fixed / completed
Reported on v2.1.153
Maintainer reply ✓ Yes — bcherny
Activity 3 comments · opened Jun 13, 2026 · closed Aug 19, 2026
💡 Likely answer: A maintainer (bcherny, collaborator) responded on this thread — see the highlighted reply below.

Bug Description
Skill listing will be truncated
81 descriptions dropped (full descriptions kept for most-used skills) (3.2%/1% of
context): fixbill, prototype, review, +78 more
run /skills to disable some, or raise skillListingBudgetFraction (currently 1%)
in settings.json
Opting in would cost ~6k tokens for skills every session and uses rate limits
faster

Environment Info

  • Platform: darwin
  • Terminal: Apple_Terminal
  • Version: 2.1.153
  • Feedback ID: 8f485742-ea68-4e9d-87d3-9aa89febeb59

Errors

[]

View original on GitHub ↗

3 Comments

cbragard · 2 months ago

Adding a data point on the silent variant of this truncation (no warning shown at all, unlike the message quoted in this issue).

Setup: repo with ~50 project-level skills under .claude/skills/, no plugins. A local script sums description: field lengths across all SKILL.md frontmatter to track the aggregate character budget.

Observations across sessions on the same repo:

  • At 22,924 cumulative description chars → all 50 skills render fully in the <system-reminder> skills listing, no truncation, no warning.
  • At 23,400 chars (a throwaway probe skill added specifically to test this, description hand-padded to a precise length, name sorted last alphabetically) → the probe skill rendered as a bare name only, description silently dropped. No warning message, no /doctor notice, nothing in the statusline — matches the pattern described in #68677 rather than the explicit warning shown in this issue's report.
  • At 23,928 chars (an earlier session, two different skills) → the two alphabetically-last skills were both bare-name-only, again with no warning.

So on this install/version, the cap sits somewhere in (22,924, 23,400] cumulative description chars, and truncation is happening with zero user-facing signal — which lines up with #64606's "silently truncates ... without any warning" description of the underlying skillListingBudgetFraction mechanism, just without the message this issue shows. Possibly two different code paths (or versions) hit the same budget differently: one warns, one doesn't.

Caveats: char counts are from a repo-local script, not the harness's internal accounting, so the exact threshold value may not transfer to other setups (token-based counting, other context consumers, model/context-window size could all shift it). Not filing as a separate issue since #64606/#68677/#68135 already cover the mechanism and both truncation behaviors — just adding a reproducible bound in case it's useful for narrowing down why the warning fires in some cases and not others.

bcherny collaborator · 1 month ago

This is expected behavior: the skill listing has a context budget (default 1% of the model's context window) and least-used skill descriptions are shortened first — you can raise skillListingBudgetFraction in settings or trim skill descriptions, as described at https://code.claude.com/docs/en/skills#skill-descriptions-are-cut-short. Closing — reply to reopen.

🤖 Generated with Claude Code

github-actions[bot] · 5 days ago

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.