# How Progressive Disclosure Minimizes Token Usage in Agent-Skills > Learn how progressive disclosure minimizes token usage by loading essential skill entry points first and deferring large files until needed. Optimize your agent workflows now. - Repository: [Addy Osmani/agent-skills](https://github.com/addyosmani/agent-skills) - Tags: performance - Published: 2026-04-16 --- **Progressive disclosure minimizes token usage by loading only the essential [`SKILL.md`](https://github.com/addyosmani/agent-skills/blob/main/SKILL.md) entry point initially, while deferring large reference files until they are explicitly requested by the workflow.** The **addyosmani/agent-skills** repository implements a token-conscious architecture that uses progressive disclosure to keep baseline prompt sizes minimal. By structuring each skill around a lightweight entry point and supporting files that load on demand, the system dramatically reduces token consumption without sacrificing access to comprehensive documentation. ## The Architecture of Progressive Disclosure in Agent-Skills ### The SKILL.md Entry Point Every skill in the repository follows a strict file structure where [`SKILL.md`](https://github.com/addyosmani/agent-skills/blob/main/SKILL.md) serves as the sole entry point. According to the project documentation in [`docs/skill-anatomy.md`](https://github.com/addyosmani/agent-skills/blob/main/docs/skill-anatomy.md) (lines 109-110), this file contains only the most essential information: the skill overview, when-to-use guidelines, and the core step-by-step process. The [`README.md`](https://github.com/addyosmani/agent-skills/blob/main/README.md) (lines 35-36) reinforces this design principle, stating that the [`SKILL.md`](https://github.com/addyosmani/agent-skills/blob/main/SKILL.md) acts as the entry point while supporting references load only when needed, keeping token usage minimal. ### Supporting Files and Deferred Loading When a skill requires extensive reference material—such as large tables, exhaustive checklists, long code snippets, or auxiliary scripts—this content is moved into **supporting files** that reside alongside [`SKILL.md`](https://github.com/addyosmani/agent-skills/blob/main/SKILL.md). These may include files like [`supporting-file.md`](https://github.com/addyosmani/agent-skills/blob/main/supporting-file.md) or scripts stored in a `scripts/` directory. Crucially, these files are **not loaded automatically** into the context window. Instead, the agent reads them only when the workflow explicitly calls for them, such as when the instructions state "see the full checklist in [`supporting-file.md`](https://github.com/addyosmani/agent-skills/blob/main/supporting-file.md)." ## How Progressive Disclosure Reduces Token Consumption The token savings become clear when examining a concrete implementation like the `test-driven-development` skill. The directory structure follows the progressive disclosure pattern: ```markdown skills/ └─ test-driven-development/ ├─ SKILL.md ← tiny core workflow (~150 tokens) └─ references.md ← long checklist, only read on demand (~200+ lines) ``` The [`SKILL.md`](https://github.com/addyosmani/agent-skills/blob/main/SKILL.md) contains a streamlined process: ```markdown ## Process 1. Write a failing test. 2. Implement the minimum code to make the test pass. 3. Refactor while keeping the test green. 4. **If you need the full checklist, open `references.md`.** ``` When the agent reaches step 4, it executes an internal `readFile('references.md')` call, pulling the extra 200-plus lines **only at that moment**. All earlier steps required only the lightweight [`SKILL.md`](https://github.com/addyosmani/agent-skills/blob/main/SKILL.md), maintaining a minimal token footprint for the majority of interactions. ## Implementation Details from the Source Code The progressive disclosure principle is formally documented in the project's specification files. The [`docs/skill-anatomy.md`](https://github.com/addyosmani/agent-skills/blob/main/docs/skill-anatomy.md) file explicitly defines this architecture: > "Progressive disclosure. Main [`SKILL.md`](https://github.com/addyosmani/agent-skills/blob/main/SKILL.md) is the entry point. Supporting files are loaded only when needed." Similarly, the [`README.md`](https://github.com/addyosmani/agent-skills/blob/main/README.md) provides the high-level rationale: > "Progressive disclosure. The [`SKILL.md`](https://github.com/addyosmani/agent-skills/blob/main/SKILL.md) is the entry point. Supporting references load only when needed, keeping token usage minimal." This design ensures that the agent operates within efficient token budgets during routine tasks while retaining access to comprehensive documentation for complex scenarios. ## Summary - **Progressive disclosure** in Agent-Skills structures documentation so that only essential [`SKILL.md`](https://github.com/addyosmani/agent-skills/blob/main/SKILL.md) content loads initially, while large supporting files remain deferred. - The [`SKILL.md`](https://github.com/addyosmani/agent-skills/blob/main/SKILL.md) entry point contains minimal token counts (~150 tokens), while exhaustive references reside in separate files like [`supporting-file.md`](https://github.com/addyosmani/agent-skills/blob/main/supporting-file.md) or `scripts/`. - Supporting files load only when explicitly requested by the workflow, dramatically reducing baseline token consumption without limiting access to detailed documentation. - This architecture is formally defined in [`docs/skill-anatomy.md`](https://github.com/addyosmani/agent-skills/blob/main/docs/skill-anatomy.md) and [`README.md`](https://github.com/addyosmani/agent-skills/blob/main/README.md), ensuring consistent implementation across all skills in the repository. ## Frequently Asked Questions ### How does Agent-Skills determine when to load supporting files? The agent loads supporting files only when the [`SKILL.md`](https://github.com/addyosmani/agent-skills/blob/main/SKILL.md) workflow explicitly instructs it to do so. For example, when the process includes a step like "see the full checklist in [`references.md`](https://github.com/addyosmani/agent-skills/blob/main/references.md)," the agent executes a `readFile()` call at that specific moment, pulling the additional content into the context window only when required. ### What types of content belong in supporting files versus SKILL.md? **SKILL.md** should contain the skill overview, when-to-use guidance, and the core step-by-step process—content essential for every interaction. **Supporting files** should house large tables, exhaustive checklists, extended code snippets, auxiliary scripts, or detailed reference material that the agent only needs for specific edge cases or complex scenarios. ### Does progressive disclosure limit the agent's access to documentation? No. Progressive disclosure does not restrict access; it optimizes timing. The agent retains full access to all supporting files and can load them instantly when the workflow demands. The architecture simply prevents large, rarely-needed files from consuming tokens during routine interactions where they provide no value. ### Where is the progressive disclosure pattern documented in the codebase? The pattern is formally documented in two key locations: [`docs/skill-anatomy.md`](https://github.com/addyosmani/agent-skills/blob/main/docs/skill-anatomy.md) (lines 109-110) defines the structural principle that supporting files load only when needed, and [`README.md`](https://github.com/addyosmani/agent-skills/blob/main/README.md) (lines 35-36) explains the token-saving rationale behind keeping [`SKILL.md`](https://github.com/addyosmani/agent-skills/blob/main/SKILL.md) as the minimal entry point.