loading…

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.

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 and 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 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, context engineering, agents md spec, smart zone.