The 16K skill budget
Full Lesson Reference
Every skill's description loads into context at the start of every session - even skills you don't invoke. All skill descriptions combined have a 16,000 character limit. Hit that limit and skills silently drop from Claude's awareness. This lesson is about staying under budget.
Why there's a limit
Skill descriptions are what Claude uses to decide "is this the right skill for this instruction?" They need to load upfront so Claude can match intent to skill.
16K characters is the hard cap. Go over and Claude can't see all your skills. Worse, you often don't know - skills just silently stop being suggested.
Check your usage
How much of my 16K skill metadata budget am I using? List each skill with its description length.
Claude tallies every description, shows you the total and per-skill breakdown. If you're over 16K, it tells you which skills are getting dropped.
Typical budget breakdown
- A minimal skill description - 50-100 characters (one line)
- A typical skill description - 200-400 characters (2-4 sentences)
- A verbose description - 800+ characters (too long)
Math: 16,000 / 300 = ~50 skills with good descriptions. 100 skills if you keep them tight.
Writing lean descriptions
Bad (verbose, repeats the name)
description: The weekly-report skill is a comprehensive tool for building performance reports for ecommerce clients. It pulls data from multiple marketing platforms including Google Ads, Meta Ads, and Klaviyo. It applies the agency's brand template and generates an HTML report that is then encrypted and deployed. This skill should be used every week for each client.
Good (tight, specific)
description: Build the weekly performance report for an ecommerce client. Pulls Google Ads + Meta + Klaviyo, applies brand template, outputs encrypted HTML.
Cut
- The skill name (obvious from frontmatter)
- "This skill..." (obvious it's a skill)
- Overly explanatory prose
- When to use it (separate line in the body, not in the description)
Keep: what it does + for what context.
When you're over budget
3 options
1. Trim descriptions Tell Claude
Audit my skill descriptions. For each over 300 characters, suggest a tighter version.
Claude shows before/after for each. Approve bulk changes.
- Remove skills you don't use
List all my skills with their last invocation date based on git history or usage logs. Flag any I haven't used in 3 months.
Remove the unused ones. They can always be reinstalled later.
- Disable context-specific skills
If some skills are only for certain clients, disable them globally and enable per-project:
Disable the [client-name] specific skill globally. I'll re-enable it in that project's .claude/settings.json as needed.
Per-project vs global skills
Skills installed globally (~/.claude/skills/) count against the 16K budget in every session.
Project-specific skills (.claude/skills/ inside a project folder) only count when Claude is working in that project.
Rule of thumb
- Global - skills you use across multiple projects (wrapup, startup, brand guides that span clients)
- Project-specific - skills only relevant to one client or one type of work
Move project-specific stuff out of global to free up the 16K budget.
Monthly skill audit
Part of your monthly CLAUDE.md + memory audit (Modules 02 + 04), add:
Audit my skills. Report
- Total skill metadata usage vs 16K budget
- Any skills I haven't invoked in 60+ days
- Any descriptions over 400 characters
- Duplicates or overlapping skills Give me a prioritised cleanup list.
5 minutes. Keeps your skill library tight.
Power-user tips
- Write the description LAST - once you know exactly what the skill does, the description almost writes itself
- Show, don't tell - "Build X from Y" beats "This skill builds X by using Y"
- Include the output format - "outputs HTML" or "outputs a markdown brief" helps Claude match intent
- Avoid stock phrases - "comprehensive", "powerful", "easy-to-use" eat characters and add no signal
Action items
☐ Run the check: "how much of my 16K skill budget am I using?"
☐ If over 12K, audit descriptions + remove unused skills
☐ Move project-specific skills out of global if you have any
☐ Add skill audit to your monthly maintenance routine
Next lesson: Skills that change how Claude thinks.
Exercises
- Review the concepts covered in this lesson: The 16K skill budget.
- Write down your key takeaway from this lesson.
- Practice running any commands or prompts mentioned above inside your terminal.