Progressive Disclosure for Documentation
Restructure large documentation files (500+ lines, 5k+ tokens) into slim indexes with on-demand detail directories. Reduces always-included context by 40-60% while preserving full accessibility. Ideal for documentation auto-included in every agent context window.
npx skills add agentskillexchange/skills --skill progressive-disclosure
# Progressive Disclosure for Documentation
What this skill actually does
A pattern for restructuring large documentation files into slim indexes with on-demand
subdirectories, reducing always-included context by 40-60%.
## Problem
Large documentation files (500+ lines, 5k+ tokens) that are always included in context:
– Waste context budget on rarely-needed content
– Slow down response times
– Crowd out more relevant information
– Create cognitive overload
## Solution
Split monolithic docs into:
1. **Slim index** (~20% of original) – Always included, provides overview + navigation
2. **Detail directories** – On-demand loading when specific topics needed
## Structure
Before:
TOOLS.md (~11k tokens always included)
├── Section 1 (rarely needed)
├── Section 2 (rarely needed)
├── ... (15+ sections)
└── Section N (rarely needed)
After:
tools/
├── README.md (~4k tokens always included) # Slim index
├── topic1/README.md # Detailed docs (~1k tokens each)
├── topic2/README.md # Loaded on-demand
└── .../README.md # etc.
## When to Use
**Good candidates for progressive disclosure:**
– Files > 500 lines or 5k tokens
– Files always included in context (via config or auto-load)
– Files with distinct sections that are rarely needed together
– Documentation with both overview and detailed reference content
**Keep as single file when:**
– File is 10) | Group related sections into one subdir |
| Inconsistent depth (some sections slim, others still huge) | Apply pattern uniformly |
| Forgetting to update config/imports | Always audit auto-include lists after restructuring |
| Splitting files that are always read together | Only split genuinely independent sections |
## Installation
### Claude Code
Copy this skill directory:
cp -R skills/progressive-disclosure ~/.claude/skills/progressive-disclosure
Then invoke with `/progressive-disclosure` before restructuring a large documentation file.
### Manual
The pattern is pure documentation design — no tools required. Read the Implementation
Guide above and apply the structure to any large file in your project.
## Related
– `autonomous-session-workflow` (in this catalog) — auto-include optimization helps agents stay within context budget
– `five-element-spec` (in this catalog) — scope documentation before restructuring