[DOCS] Skills docs omit the 250-character cap for `/skills` descriptions

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

description frontmatter and the Claude doesn't see all my skills troubleshooting guidance, especially how long descriptions are represented in the /skills listing

Current Documentation

The docs currently say:

Every skill needs a SKILL.md file with two parts: YAML frontmatter (between --- markers) that tells Claude when to use the skill, and markdown content with instructions Claude follows when the skill is invoked. The name field becomes the /slash-command, and the description helps Claude decide when to load it automatically.

The frontmatter reference also says:

| 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. |

The troubleshooting section further says:

Skill descriptions are loaded into context so Claude knows what's available. If you have many skills, they may exceed the character budget. The budget scales dynamically at 2% of the context window, with a fallback of 16,000 characters. Run /context to check for a warning about excluded skills. To override the limit, set the SLASH_COMMAND_TOOL_CHAR_BUDGET environment variable.

And the environment variables reference says:

| SLASH_COMMAND_TOOL_CHAR_BUDGET | Override the character budget for skill metadata shown to the Skill tool. The budget scales dynamically at 2% of the context window, with a fallback of 16,000 characters. Legacy name kept for backwards compatibility |

No current page explains that each skill description in the /skills listing is now capped at 250 characters.

What's Wrong or Missing?

Changelog v2.1.86 says:

Skill descriptions in the /skills listing are now capped at 250 characters to reduce context usage

The current docs explain what the description field does and document the overall metadata character budget, but they do not explain the new per-description limit.

That leaves three user-visible details undocumented:

A. The per-skill 250-character cap is undocumented

Users authoring long skill descriptions cannot tell that only the first 250 characters are included in the /skills listing.

B. The docs do not explain how this affects skill authoring

Because the description field drives automatic skill selection, authors need to know to front-load the most important trigger words and usage cues instead of assuming the full description will always be visible.

C. The relationship between the overall character budget and the per-description cap is unclear

The docs describe SLASH_COMMAND_TOOL_CHAR_BUDGET as the way to increase the skill-metadata budget, but they do not clarify that this adjusts the total budget across skills rather than removing the new 250-character cap for any single description.

Suggested Improvement

Add a short note to the skills authoring docs and mirrored slash-command docs explaining the new constraint. For example:

Claude Code caps each skill description in the /skills listing at 250 characters. If your description is longer, only the first 250 characters are included in the listing/skill metadata. Put the most important trigger words and task summary near the start of the description. SLASH_COMMAND_TOOL_CHAR_BUDGET increases the overall metadata budget across skills, but it does not remove the per-description cap.

This would give users concrete guidance for writing descriptions that still work well after truncation.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/skills | Primary description frontmatter reference and skill-metadata troubleshooting |
| https://code.claude.com/docs/en/slash-commands | Mirror page with the same skill authoring and troubleshooting guidance |
| https://code.claude.com/docs/en/env-vars | SLASH_COMMAND_TOOL_CHAR_BUDGET currently documents only the overall metadata budget |
| https://code.claude.com/docs/en/features-overview | Explains that skill descriptions load at session start, but not that each entry is capped |

Total scope: 4 pages affected

Source: Changelog v2.1.86

Changelog entry: Skill descriptions in the \/skills\ listing are now capped at 250 characters to reduce context usage