Progressive Disclosure: How Claude Loads Skills
The Context Problem Skills Solve
Claude's context window is finite. If every skill's full instructions loaded into every conversation, your context would fill instantly and most of it would be irrelevant to the task at hand. Progressive disclosure is the mechanism that keeps skills lightweight: Claude reveals only what it needs, only when it needs it.
The key idea
At startup, Claude loads only each skill's NAME and DESCRIPTION — not the full content. It's like a table of contents in context, rather than every document. The body of a skill costs almost nothing until the moment it's actually used.
Three Levels of Disclosure
Think of skill loading as three expanding levels. Each level only opens when the previous one signals it's relevant — so context grows precisely in step with need.
Progressive disclosure in three levels: name+description always; full body on match; supporting files only when the body asks for them.
- 1.Level 1 — Always in context: just the skill's name + description (a lightweight 'menu').
- 2.Level 2 — On a match: Claude loads the full SKILL.md body and follows its instructions.
- 3.Level 3 — When the body points to them: supporting files (references, examples) and scripts load only if the task reaches for them.
How Matching Works
When you send a request, Claude compares your message against the descriptions of all available skills using semantic matching — the intent has to overlap. For example, 'explain what this function does' would match a skill described as 'explain code with visual diagrams' because the meanings align. Once a match is found, Claude loads the full skill and applies it.
The description budget
Because descriptions sit in context, they share a budget (about 1% of the model's context window). With many skills, lower-priority descriptions get trimmed — which can strip the keywords Claude needs to match. Each skill's description (+ when_to_use) is also capped at 1,536 characters. Put your key use case FIRST, and run /doctor to see if the budget is overflowing.
Why Scripts Are Special
Progressive disclosure has a powerful corollary for code: scripts in a skill directory run WITHOUT loading their contents into context. The script executes, and only its OUTPUT consumes tokens. The trick is to instruct Claude to RUN the script, not read it — so a 500-line validator costs you only its result, not its source.
| Approach | Context cost |
|---|---|
| Claude reads a 500-line script | All 500 lines fill context |
| Claude runs the script (progressive disclosure) | Only the output (often a few lines) |
Telling Claude to RUN a bundled script keeps deterministic logic out of context entirely — only the result lands.
Next
You understand how skills load efficiently. Next we place skills among Claude Code's other customization tools — CLAUDE.md, slash commands, subagents, hooks, MCP — so you always pick the right one.
Key Takeaways
- ✓Progressive disclosure is the mechanism that keeps skills lightweight: Claude reveals only what it needs, when it needs it.
- ✓At startup Claude loads only each skill's name + description (a 'table of contents'), not the full body.
- ✓Three levels: (1) name+description always in context, (2) full SKILL.md on a match, (3) linked files/scripts only when the body reaches for them.
- ✓Matching is semantic — Claude compares your request's intent against skill descriptions; overlap triggers a match.
- ✓Descriptions share a context budget (~1% of the window) and are capped at 1,536 chars each; put the key use case first and check /doctor if matching fails.
- ✓Scripts run without loading their source — only the output consumes tokens — so instruct Claude to RUN a script, not read it.
Check Your Understanding
Test what you learned in this lesson.
Q1.At startup, what does Claude load for each available skill?
Q2.What are the three levels of progressive disclosure?
Q3.Why do scripts bundled in a skill keep context efficient?
Q4.Why should you put a skill's key use case first in its description?
Practice This Lesson