---
title: "Progressive Disclosure"
description: "Providing context and tooling to AI agents in staged layers on-demand rather than up front."
section: "concepts"
type: "concept"
created: "2026-08-22"
updated: "2026-08-30"
confidence: "high"
tags: ["agents", "context-engineering", "skills"]
canonical: "https://pyweb.dev/wiki/progressive-disclosure"
---
# Progressive Disclosure

**Progressive Disclosure** is an architectural pattern where an agent system loads lightweight pointers or indexes first, and only retrieves full documentation, schemas, or tool definitions when a specific trigger condition is met.


```text
L1  name + description          (always loaded)
L2  SKILL.md body               (loaded on use)
L3  supporting files/scripts    (loaded on explicit need)
```

## The Problem It Solves
If an agent has 100 available skills or API endpoints, injecting all 100 skill bodies into the root prompt consumes tens of thousands of tokens on every turn, risking [context rot](/wiki/context-rot) and [prompt bloat](/wiki/prompt-bloat).

## Three Layers of Disclosure
1. **Tier 1: The Catalog Index:** A compact list of names and 50-character descriptions loaded into the initial context.
2. **Tier 2: The Actionable Manifest:** When an intent matches, the agent invokes a discovery tool (like `skill_view` or `tool_describe`) to load the full contract.
3. **Tier 3: The Deep Primary Source:** The agent inspects supporting scripts, reference docs, or API specs only while executing that sub-phase.

## Benefits
- Drastically lowers baseline token consumption per turn.
- Prevents attention dilution across irrelevant tools.
- Allows agent systems to scale to hundreds of modular skills without degrading reasoning quality.
- Complements [editorial diagrams and visual explanations](/wiki/editorial-diagrams-and-visual-explanations) by routing high-level structural overviews first before loading deep implementation schemas.

## Failure Modes

| Symptom | Root cause | Fix |
|---|---|---|
| Everything loaded up front | Context treated as free | Load levels on demand: metadata always, body on use, files on need (Skill L1/L2/L3 pattern) |
| Critical info hidden too deep | Disclosure without escape hatch | Keep a visible index of what exists so agents know what to request |
| Progressive = fragmented | Levels cut across the wrong seam | Split at natural usage boundaries, not arbitrary file sizes |

## Rule of Thumb

Default to the smallest context that answers the current step; every
always-loaded token must justify itself on every request.

## Related
[prompt bloat](/wiki/prompt-bloat), [context engineering](/wiki/context-engineering), [agents md spec](/wiki/agents-md-spec), [smart zone](/wiki/smart-zone).

---

## Agent Navigation

cluster: person (170 pages) | betweenness: 233.8

### References (outbound)
- [Context Rot](https://pyweb.dev/wiki/context-rot.md)
- [Editorial Diagrams and Visual Explanations](https://pyweb.dev/wiki/editorial-diagrams-and-visual-explanations.md)
- [Prompt Bloat](https://pyweb.dev/wiki/prompt-bloat.md)

### Referenced by (inbound)
- [Agent Harness Engineering](https://pyweb.dev/wiki/agent-harness-engineering.md)
- [Agent-Native Infrastructure](https://pyweb.dev/wiki/agent-native-infrastructure.md)
- [AI Coding Taxonomy & Agent Experience](https://pyweb.dev/wiki/ai-coding-taxonomy.md)
- [Constraint Layering](https://pyweb.dev/wiki/constraint-layering.md)
- [Context Budget Audit](https://pyweb.dev/wiki/context-budget-audit.md)
- [Context Engineering](https://pyweb.dev/wiki/context-engineering.md)
- [Editorial Diagrams and Visual Explanations](https://pyweb.dev/wiki/editorial-diagrams-and-visual-explanations.md)
- [Evals Skills](https://pyweb.dev/wiki/evals-skills.md)
- [Skill Treatment Effect](https://pyweb.dev/wiki/skill-treatment-effect.md)
- [Cathryn Lavery](https://pyweb.dev/wiki/cathryn-lavery.md)
- [Matt Pocock](https://pyweb.dev/wiki/matt-pocock.md)

### Evidence (verified primary sources)
- [aihero-dev-homepage-2026](https://pyweb.dev/wiki/raw/articles/aihero-dev-homepage-2026.md) | origin: https://www.aihero.dev/ | ingested: 2026-08-22 | sha256: 231157fed45f82922924a050e09b5b81a443891814fc1d72c874d864a6075419
- [volcengine-openviking-2026](https://pyweb.dev/wiki/raw/articles/volcengine-openviking-2026.md) | origin: https://github.com/volcengine/OpenViking | ingested: 2026-08-23 | sha256: d0d0207f2fcffc44f6286ee5b8b8fdaf2f8d68683353c2d3e83b40c4944fdb3a

### Machine endpoints
- Knowledge graph: https://pyweb.dev/api/graph.json
- Graph analysis: https://pyweb.dev/api/graph-analysis.json
- Context index: https://pyweb.dev/llms.txt