Progressive Disclosure¶
Summary¶
A context management strategy where information is revealed in layers — showing only metadata at first, then revealing full details only when the agent decides it's needed. This prevents context window overload while giving access to hundreds or thousands of knowledge sources.
How It Works in Agent Skills¶
- At startup — Agent sees only skill name + short description (like book titles on a spine)
- At runtime — When agent decides a skill is relevant, it reads the full
SKILL.md - On demand — Rest of the skill folder (scripts, templates, examples) is organized for easy access
Why It Matters¶
Without progressive disclosure, giving an agent hundreds of skills would consume the entire context window with instructions before any work begins. With progressive disclosure, the agent pulls only what it needs, when it needs it.
Analogy¶
Like a library: you see the catalog (metadata), pull a book from the shelf (full instructions), and read the appendices (scripts and templates) only if needed.
Contrast with Prompts¶
| Prompts | Skills with Progressive Disclosure | |
|---|---|---|
| Context usage | Everything loaded at once | Only metadata loaded initially |
| Scalability | Gets messy fast with many instructions | Scales to hundreds/thousands of skills |
| Organization | Flat text | Structured folders |
| Agent control | Agent receives everything | Agent chooses what to load |
Applications Beyond Skills¶
- MCP server metadata (showing available tools without loading full schemas)
- Documentation navigation (table of contents → section → detail)
- Agent memory systems (summary → detail → raw data)