# Progressive Disclosure

> Revealing AI capability gradually to match user mental models.

- Skill: `gabrielmoreira/progressive-disclosure` (Agent Skill)
- Install (CLI): `npx skillmds@latest add gabrielmoreira/progressive-disclosure`
- Raw SKILL.md: https://api.skillmd.com/api/skills/gabrielmoreira/progressive-disclosure/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: gabrielmoreira (https://skillmd.com/u/gabrielmoreira)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/gabrielmoreira/progressive-disclosure

---

# Progressive Disclosure
Users don't understand what AI can do. Progressive disclosure is how you reveal capabilities at the right pace — preventing both overwhelm and underuse.
## The Mental Model Gap
Users arrive with mental models shaped by previous technology. They may:
- Treat the AI like a search engine (keyword queries)
- Treat it like a form (expecting rigid structure)
- Underestimate what it can do (asking for less than it offers)
- Overestimate what it can do (expecting perfection)
Progressive disclosure bridges the gap between what users think the AI does and what it actually does.
## Disclosure Strategies
- **On-demand hints**: Show capability suggestions contextually ("Did you know you can also ask me to...")
- **Escalating examples**: Start with simple use cases, reveal complex ones as the user gains confidence
- **Feature graduation**: Unlock advanced features after the user demonstrates comfort with basics
- **Contextual teaching**: When the user attempts something inefficiently, show a better approach
- **Capability boundaries**: Clearly communicate what the AI cannot do, not just what it can
## Layered Capability Revelation
Structure capabilities in layers:
1. **Surface layer**: The most obvious, lowest-risk capabilities. Users discover these immediately.
2. **Intermediate layer**: More powerful features revealed through tooltips, suggestions, or first-use prompts.
3. **Power layer**: Advanced capabilities for experienced users — available but not promoted.
## Pacing
- **Too fast**: Users feel overwhelmed, ignore capabilities, or lose trust
- **Too slow**: Users get bored, think the product is limited, churn
- **Just right**: Each new capability feels like a natural next step
## Design Artefacts
- Capability disclosure maps showing what's revealed when
- Mental model progression diagrams
- First-use experience flows with disclosure triggers
- Capability tier definitions (surface, intermediate, power)