TL;DR: Claude Code has an undocumented ~16,000 character budget for skill metadata. With typical 263-char descriptions, only ~42 skills fit. To show more skills, compress descriptions to ≤130 characters. Note: This is a skills-specific limit—the Tool Search Tool's
defer_loadingfeature does NOT apply to skills.
When using Claude Code with 63 installed skills, the system prompt showed:
<!-- Showing 42 of 63 skills due to token limits -->
21 skills (33%) were completely hidden from the agent—it couldn't discover or invoke them.
This investigation revealed an important architectural distinction:
┌─────────────────────────────────────────────────────────────┐
│ TOOLS (API-level) │
│ • Bash, Read, Write, Grep, MCP tools, etc. │
│ • defer_loading: true CAN apply here │
│ • Solved by: Tool Search Tool beta │
├─────────────────────────────────────────────────────────────┤
│ SKILLS (Claude Code-specific) │
│ • SKILL.md files in ~/.claude/skills/ │
│ • Appear in <available_skills> section │
│ • defer_loading: DOES NOT APPLY │
│ • Needs: skill-specific solutions (hidden flag, compression)│
└─────────────────────────────────────────────────────────────┘
Why this matters: The Tool Search Tool beta (defer_loading) solves context bloat for MCP tools, but it does NOT help with skill visibility. Skills require their own solution.
| Metric | Value |
|---|---|
| Empirical budget | ~15,500-16,000 characters |
| Official documentation | None exists |
| Configurable? | No evidence of configuration options |
Each skill in available_skills consumes approximately:
| Component | Characters |
|---|---|
| XML tags | ~85 |
| Skill name (avg) | ~20 |
| Location field | ~4 |
| Total overhead | ~109 |
| + Description | Variable |
Total per skill = description_length + 109
Budget fills at ~15,700 characters total
| Description Length | Skills That Fit |
|---|---|
| 263 chars (observed avg) | ~42 skills |
| 200 chars | ~52 skills |
| 150 chars | ~60 skills |
| 130 chars | ~67 skills ✅ |
| 100 chars | ~75 skills |
| Category | Count | Total Chars | Avg Length |
|---|---|---|---|
| Shown skills | 42 | 11,071 | 264 chars |
| Hidden skills | 21 | 5,506 | 262 chars |
| All skills | 63 | 16,577 | 263 chars |
Critical observation: Hidden skills had nearly identical average description length (262 vs 264 chars). This proves truncation is based on cumulative total, not individual description length.
Until Anthropic implements hidden: true (#11045), the only working solution is to reduce description lengths.
Target: ≤130 characters per description for collections of 60+ skills.
Before (264 chars):
description: "Provide evidence proportional to stakes for all claims.
Use when: making assertions, declaring completion, presenting findings,
reporting conclusions. Never assert without proof. Calibrate depth to
verification level (deep/standard/trust)."After (128 chars):
description: "Provide evidence for claims proportional to stakes.
Use when: asserting, completing, presenting. Calibrate to stakes."Why This Works:
63 skills × (130 char desc + 109 overhead) = 15,057 chars
15,057 < 16,000 budget ✅
Strategy by Collection Size:
| Skills | Strategy |
|---|---|
| <40 | No action needed |
| 40-60 | Compress to ~150 chars |
| 60-75 | Compress to ≤130 chars |
| >75 | Compress + reduce skill count |
| Strategy | Does It Solve Visibility? | Why |
|---|---|---|
| CLAUDE.md orchestration | ❌ No | CLAUDE.md doesn't affect skill budget |
| Tiered architecture | ❌ No | Personal + project skills share same budget |
defer_loading / Tool Search Tool |
❌ No | Only applies to tools, not skills |
| MCP alternatives | ❌ No | MCP provides tools, not expertise injection |
| Project-specific loading | Only helps if you reduce personal skills | |
| Subagent-exclusive skills | ❌ No | Not currently possible (see below) |
Subagents CAN specify which skills to load:
---
name: db-admin
description: Database administration tasks
tools: Bash, Read
skills: database-migration, postgres-ops # Auto-load these skills
---BUT this is one-way opt-in only:
- ✅ Subagent can say "load these skills for me"
- ❌ Skill cannot say "only show me to these agents"
- ❌ All skills have metadata loaded into main agent regardless
Workaround: Embed specialized knowledge directly in the subagent's .md file instead of creating separate skills. Trade-off: Loses skill benefits (progressive disclosure, reusability, composability).
From #11045:
# Hidden skills - don't consume budget until invoked
name: python-engineering:async-debugging
description: Deep async/await debugging patterns
hidden: true # Proposed, not implemented
# Router priority - checked first during discovery
name: python-engineering
description: Routes to specialized Python skills
router: true # Proposed, not implemented- Keep descriptions ≤130 characters if you have 50+ skills
- Front-load trigger keywords in first 50 characters
- Move details to SKILL.md body—descriptions are for discovery only
description: "[Verb] [domain]. Use when: [trigger1], [trigger2]."All issues have been consolidated to #11045.
| Issue | Status | Key Contribution |
|---|---|---|
| #11045 | Open - Canonical | Proposes hidden: true and router: true flags |
| #12782 | Closed (dup) | First budget calculation (~15K chars, ~371 chars/skill) |
| #13044 | Open | Reports 60% of skills hidden (36/92) |
| #13099 | Closed (dup) | Documentation request (this research) |
| #13100 | Closed (dup) | Feature request for configurable budget (this research) |
| Issue | Status | Request |
|---|---|---|
| #12633 | Open | main-agent: false - Subagent-exclusive skills |
| #6915 | Open | MCP tools only for subagents |
| #6587 | Open | Selective MCP access for subagents |
Want this fixed? Upvote #11045 (hidden skills) and #12633 (subagent-exclusive skills).
Note: Issue #12836 (Tool Search Tool support) is about tools, not skills. It will not solve the skill visibility problem.
- Observation: Noted "Showing 42 of 63 skills" message in system prompt
- Documentation Search: Searched official docs, Anthropic blog, community resources—no documentation found
- Empirical Measurement: Extracted descriptions from all 63 SKILL.md files, measured character counts
- Calculation: Computed per-skill overhead (~109 chars), deduced budget from observed behavior
| Limit | Value | Source |
|---|---|---|
| Description max | 1,024 chars | Claude Code Docs |
| Skill name max | 64 chars | Official docs |
| SKILL.md body | ~500 lines (soft) | Official docs |
| Metadata cost | ~100 tokens/skill | Anthropic Blog |
| available_skills budget | Not documented | — |
| Finding | Confidence | Evidence |
|---|---|---|
| Budget is ~15,500-16,000 chars | HIGH | Direct calculation, matches #12782 |
| No official docs exist | HIGH | Exhaustive search |
| Compression solves it | HIGH | Mathematical certainty |
defer_loading doesn't help skills |
HIGH | Architectural analysis |
| 130-char target works | MEDIUM | Calculated, not tested |
| Truncation order | LOW | Filesystem-dependent |
- Can hidden skills be invoked by name? Unknown—if yes, manual invocation could work
- Is the budget configurable? No evidence found
- Does budget vary by model? Unknown
- Will Anthropic implement
hidden: true? Proposed in #11045, no timeline
- Install 60+ skills in
~/.claude/skills/ - Start a new Claude Code session
- Examine Skill tool for "Showing X of Y" message
- Extract descriptions:
grep -h "^description:" ~/.claude/skills/*/SKILL.md - Calculate:
total_chars + (skill_count × 109)
- Based on single observation (42/63 split)
- XML overhead estimated from observed format
- No source code access for verification
- Filesystem ordering may vary
- Budget calculation independently verified by #12782
Official
- Agent Skills - Claude Code Docs
- Equipping agents for the real world
- Advanced Tool Use (defer_loading) - Note: tools only, not skills
GitHub Issues
- #11045 - Skills Context Overflow (canonical - upvote here!)
- #12633 - Subagent-exclusive skills
- #11045 comment with this research
Community
Research conducted December 4-5, 2025 using Claude Opus 4.5 Findings contributed to #11045 - the canonical issue for this problem