claude-code - 💡(How to fix) Fix Skill descriptions silently dropped from system prompt above some cumulative-size threshold

Summary

When the total size of all SKILL.md description: fields exceeds some internal threshold, Claude Code silently strips descriptions from individual skill entries in the available-skills section of the system prompt. The skill name stays in the list, but its description is replaced with nothing. This degrades auto-triggering for affected skills (the model no longer sees what they do or when to invoke them).

Environment

• Claude Code: 2.1.143
• Platform: darwin 23.0.0 (macOS, arm64)
• Local install: ~/.claude/local/node_modules/@anthropic-ai/claude-code/bin/claude.exe
• 63 user skills under ~/.claude/skills/
• 90 plugin SKILL.md files (vercel, stripe, frontend-design, etc.)

Reproduction

1. Install enough skills that the cumulative description text is "large" (in my case 63 user skills plus 90 plugin skills triggers it consistently).
2. Start a Claude Code session and inspect the available-skills system reminder.
3. Observe that many entries appear as - skillname (no colon, no description) even though the SKILL.md file has a valid description: field.

Verified by reading the affected SKILL.md files directly: the YAML frontmatter is well-formed, description: is present, the field parses correctly. The drop happens at the rendering stage, not at parse.

Evidence the threshold is cumulative

I edited ar24-send/SKILL.md to add a long description: (about 800 characters). After that edit, claude-code-update's description disappeared from the available-skills list, even though I never touched its file. When I shortened ar24-send's description back down to about 250 characters, claude-code-update's description came back. This is consistent across multiple reload cycles. The threshold behaves like a single shared budget for the section, not a per-skill cap.

Affected entries in my install (snapshot)

User skills with valid frontmatter that appear without descriptions:

• ralph-loop, mcp-builder, rg-ai-impact-yoy, docx, indy-agent, debug, news-forensics, implementation-integrity, claude-code-update (intermittently)

Plugin skills (almost all vercel:* and stripe:*) appear without descriptions:

• vercel:deploy, vercel:env, vercel:marketplace, vercel:status, vercel:vercel-agent, vercel:auth, vercel:routing-middleware, vercel:vercel-storage, vercel:vercel-functions, vercel:vercel-firewall, vercel:next-forge, vercel:verification, vercel:shadcn, vercel:env-vars, vercel:next-cache-components, vercel:ai-sdk, vercel:turbopack, vercel:chat-sdk, vercel:next-upgrade, vercel:vercel-sandbox, vercel:nextjs, vercel:ai-gateway, vercel:react-best-practices, vercel:knowledge-update, vercel:runtime-cache, vercel:workflow, vercel:vercel-cli, vercel:deployments-cicd, frontend-design:frontend-design, stripe:test-cards, stripe:stripe-projects, stripe:upgrade-stripe, stripe:stripe-best-practices

Built-in slash commands also affected: review, security-review.

About 36 entries dropped in total.

Impact

• Skill auto-triggering relies on the model seeing the description. With the description stripped, the model has only the name to go on, which is insufficient for non-obvious names.
• Plugin skills are disproportionately affected because they tend to appear later in the list. Users installing the vercel, stripe, or frontend-design plugins effectively lose auto-trigger for most of those skills.
• Silent failure mode. Users have no way to know it is happening without diffing the system prompt against the SKILL.md files on disk.

Suggested fixes (in order of preference)

1. Do not silently truncate. If the budget is exceeded, either log a warning to the user or surface a /skills diagnostic showing which descriptions were dropped.
2. Raise the budget or compute it relative to the model's context window.
3. If a budget is unavoidable, truncate each description proportionally rather than dropping some entries entirely. A skill with a 50-character description fragment is more useful than one with no description at all.
4. Expose the budget as an env var so power users with many skills can opt into a larger one.

Workaround I am using

Trimming the longest user-skill descriptions to free budget for the smaller ones. Not viable for plugin skills (they are external) or for the review / security-review built-ins.