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

Good catch. The 250-character truncation in /skills listings is undocumented but affects how users write skill descriptions.
Keep your description frontmatter under 250 characters. Put the most important trigger keywords first:

---
name: my-skill
description: This skill provides comprehensive utilities for managing database migrations, schema versioning, rollback procedures, and data integrity validation across PostgreSQL, MySQL, and SQLite databases in development and production environments...
description: Database migration management. Use for schema changes, rollbacks, and data integrity checks. Supports PostgreSQL, MySQL, SQLite.
---

The description serves two purposes: (1) Claude's auto-detection of when to load the skill, and (2) the /skills listing display. Both work better with concise descriptions.

---

Issue #40121 Verification

Title: [DOCS] Skills docs omit the 250-character cap for /skills descriptions
Issue Date: 2026-03-28
Verification Date: 2026-04-01
Status: PARTIALLY RESOLVED

---

Issue Summary

This issue reports that Claude Code documentation did not explain that /skills descriptions are capped at 250 characters in the listing, did not tell authors to front-load the most important trigger words near the start of the description, and did not clearly distinguish the per-description cap from the overall SLASH_COMMAND_TOOL_CHAR_BUDGET metadata budget across the affected skills pages.

---

Verification Results

Claim 1: The skills page does not document the 250-character cap or the authoring guidance that follows from it

Status: RESOLVED

At https://code.claude.com/docs/en/changelog, line 93: Skill descriptions in the "/skills" listing are now capped at 250 characters to reduce context usage.

At https://code.claude.com/docs/en/skills, line 194: `| 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. |`.

At https://code.claude.com/docs/en/skills, line 689: `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.`

Verdict: The skills page now documents the 250-character cap, tells authors to front-load the key use case, and explicitly says the cap still applies even when the overall metadata budget is increased.

---

Claim 2: The slash-commands page does not mirror the same 250-character-cap guidance

Status: RESOLVED

At https://code.claude.com/docs/en/slash-commands, line 194: `| 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. |`.

At https://code.claude.com/docs/en/slash-commands, line 689: `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.`

Verdict: The mirrored slash-commands page now carries the same cap and authoring guidance as the skills page.

---

Claim 3: The env-vars reference does not clarify that SLASH_COMMAND_TOOL_CHAR_BUDGET changes the total budget but does not remove the 250-character per-description cap

Status: UNRESOLVED

At https://code.claude.com/docs/en/env-vars, line 181: `| SLASH_COMMAND_TOOL_CHAR_BUDGET | Override the character budget for skill metadata shown to the Skill tool. The budget scales dynamically at 1% of the context window, with a fallback of 8,000 characters. Legacy name kept for backwards compatibility |`.

Verdict: This page still documents only the overall metadata budget. It does not say that each skill description remains capped at 250 characters regardless of that budget.

---

Claim 4: The features-overview page still explains that skill descriptions load at session start, but does not mention the 250-character cap

Status: UNRESOLVED

At https://code.claude.com/docs/en/features-overview, line 180: `| **Skills** | Session start + when used | Descriptions at start, full content when used | Low (descriptions every request)* |`.

At https://code.claude.com/docs/en/features-overview, lines 207-211: `By default, descriptions load at session start and full content loads when used, Claude sees names and descriptions in every request, and Claude matches your task against skill descriptions to decide which are relevant`.

Verdict: The page explains when descriptions load and how Claude uses them, but it still does not mention that each description is capped at 250 characters in the /skills listing.

---

Current State

| Claim | Status |
|-------|--------|
| Skills page lacks the 250-character cap and authoring guidance | RESOLVED |
| Slash-commands page lacks the same mirrored guidance | RESOLVED |
| Env-vars page does not explain total budget vs. per-description cap | UNRESOLVED |
| Features-overview page does not mention the 250-character cap | UNRESOLVED |

---

Suggested Fix

Add a short clarification to https://code.claude.com/docs/en/env-vars stating that SLASH_COMMAND_TOOL_CHAR_BUDGET increases only the total metadata budget across skills and does not remove the 250-character cap for any single description. Add a brief note to https://code.claude.com/docs/en/features-overview explaining that model-invocable skill descriptions load at session start but each /skills listing entry is capped at 250 characters, so the most important trigger words should appear first.

---

References

• URL: https://code.claude.com/docs/en/changelog
• Line 93: changelog entry introducing the 250-character cap for /skills descriptions
• URL: https://code.claude.com/docs/en/skills
• Line 194: frontmatter reference says descriptions longer than 250 characters are truncated and should front-load the key use case
• Line 689: troubleshooting section says each entry is capped at 250 characters regardless of budget
• URL: https://code.claude.com/docs/en/slash-commands
• Line 194: mirrored frontmatter reference says descriptions longer than 250 characters are truncated and should front-load the key use case
• Line 689: mirrored troubleshooting section says each entry is capped at 250 characters regardless of budget
• URL: https://code.claude.com/docs/en/env-vars
• Line 181: SLASH_COMMAND_TOOL_CHAR_BUDGET still describes only the overall metadata budget
• URL: https://code.claude.com/docs/en/features-overview
• Line 180: context-cost table says skill descriptions load at session start
• Lines 207-211: skills section explains when descriptions load and how Claude uses them, but does not mention the 250-character cap

---

Conclusion & Recommendation

Primary Concern: The issue reported that Claude Code documentation did not tell users that /skills descriptions are capped at 250 characters or clearly explain how that interacts with authoring guidance and the overall metadata budget.

Resolution Status: PARTIALLY RESOLVED

Recommendation: KEEP OPEN

The main skills and slash-commands pages now document the cap and the related authoring guidance. However, the env-vars and features-overview pages named in the issue still omit the per-description cap and its relationship to the overall budget, so the issue is not fully resolved.

---

We bumped this up to ~1.5k for now, and have more granular control via .claude/settings.json coming soon!

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.