How Progressive Disclosure Minimizes Token Usage in Agent-Skills

Progressive disclosure minimizes token usage by loading only the essential 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 serves as the sole entry point. According to the project documentation in 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 (lines 35-36) reinforces this design principle, stating that the 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. These may include files like 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."

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:

skills/
└─ test-driven-development/
   ├─ SKILL.md            ← tiny core workflow (~150 tokens)
   └─ references.md       ← long checklist, only read on demand (~200+ lines)

The SKILL.md contains a streamlined process:

## 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, 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 file explicitly defines this architecture:

"Progressive disclosure. Main SKILL.md is the entry point. Supporting files are loaded only when needed."

Similarly, the README.md provides the high-level rationale:

"Progressive disclosure. The 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 content loads initially, while large supporting files remain deferred.
• The SKILL.md entry point contains minimal token counts (~150 tokens), while exhaustive references reside in separate files like 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 and 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 workflow explicitly instructs it to do so. For example, when the process includes a step like "see the full checklist in 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 (lines 109-110) defines the structural principle that supporting files load only when needed, and README.md (lines 35-36) explains the token-saving rationale behind keeping SKILL.md as the minimal entry point.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}