[DOCS] Skills docs still describe a 250-character description cap and omit the truncation startup warning

Documentation Type

Incorrect/outdated documentation

Documentation Location

https://code.claude.com/docs/en/skills

Section/Topic

The skill frontmatter description field docs and the "Skill descriptions are cut short" troubleshooting section

Current Documentation

The skills docs currently say:

description | Recommended | What the skill does and when to use it. Claude uses this to decide when to apply the skill. If omitted, uses the first paragraph of markdown content. Front-load the key use case: descriptions longer than 250 characters are truncated in the skill listing to reduce context usage.

And later in troubleshooting:

Skill descriptions are loaded into context so Claude knows what's available. All skill names are always included, but if you have many skills, descriptions are shortened to fit the character budget, which can strip the keywords Claude needs to match your request. The budget scales dynamically at 1% of the context window, with a fallback of 8,000 characters. To raise the limit, set the SLASH_COMMAND_TOOL_CHAR_BUDGET environment variable. Or trim descriptions at the source: front-load the key use case, since each entry is capped at 250 characters regardless of budget.

The same 250-character cap wording also appears on https://code.claude.com/docs/en/slash-commands.

What's Wrong or Missing?

Changelog v2.1.105 says:

Improved skill description handling: raised the listing cap from 250 to 1,536 characters and added a startup warning when descriptions are truncated

The current docs are outdated in two ways:

A. The documented per-skill cap is wrong

The docs still say each skill description is capped at 250 characters, but v2.1.105 raised that listing cap to 1,536 characters.

B. The truncation warning behavior is undocumented

The docs explain that descriptions may be shortened, but they do not mention the new startup warning that appears when descriptions are truncated.

Suggested Improvement

Update the skills documentation and the mirrored slash-commands page to:

1. Replace the old 250-character cap with the current 1,536-character listing cap.
2. Clarify how that per-skill cap interacts with the overall SLASH_COMMAND_TOOL_CHAR_BUDGET metadata budget.
3. Add a short note in the troubleshooting section that Claude Code now shows a startup warning when skill descriptions are truncated, so users know why matching may be worse than expected.

Suggested wording for the troubleshooting note:

Skill descriptions can still be truncated when the metadata budget is exceeded. Claude Code now shows a startup warning when this happens. If matching degrades, shorten descriptions or raise SLASH_COMMAND_TOOL_CHAR_BUDGET.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/skills | Frontmatter table for description, plus the "Skill descriptions are cut short" troubleshooting section |
| https://code.claude.com/docs/en/slash-commands | Mirrored skill frontmatter/troubleshooting content with the same outdated 250-character cap text |

Total scope: 2 pages affected

Source: Changelog v2.1.105

Exact changelog entry: Improved skill description handling: raised the listing cap from 250 to 1,536 characters and added a startup warning when descriptions are truncated