Document the available_skills character budget limit

Documentation Gap

The available_skills section in Claude Code's system prompt has an undocumented character budget of approximately 15,500-16,000 characters. When users install many skills, some become completely invisible to the agent without any warning about why.

Observed Behavior

With 63 installed skills, the system prompt showed:

<!-- Showing 42 of 63 skills due to token limits -->

This means 21 skills (33%) were hidden from the agent—it could not discover or invoke them.

What Should Be Documented

1. The budget limit - Approximately 16,000 characters for skill metadata
2. How it's calculated - Each skill consumes ~109 chars of XML overhead plus the description length
3. How to stay within budget - Compress descriptions to ≤130 characters for large collections
4. Truncation behavior - Skills are truncated based on cumulative total, not individual description length

Current Documentation

The official skill documentation mentions:

• Description max: 1,024 chars
• Skill name max: 64 chars
• SKILL.md body: ~500 lines (soft)

But does not mention:

• The cumulative budget for available_skills
• That skills can be completely hidden from the agent
• Guidelines for users with many skills

Research

Detailed empirical research with calculations: https://gist.github.com/alexey-pelykh/faa3c304f731d6a962efc5fa2a43abe1

Suggested Documentation Addition

Add a section like:

Skill Budget Limit: Claude Code displays skill metadata in the system prompt with a ~16,000 character budget. Each skill uses approximately 109 characters of overhead plus its description length. With many skills installed, some may be hidden from the agent. To maximize visibility: - Keep descriptions under 130 characters for collections of 60+ skills - Keep descriptions under 150 characters for collections of 40-60 skills - Front-load trigger keywords in the first 50 characters