progressive-disclosure

Progressive disclosure optimizes context window usage by organizing skill content into three tiers: concise metadata, a compact entry point document under 500 lines, and detailed reference files loaded only when needed. This reduces token consumption and prevents information overload.

Use a 3-tier architecture: move metadata and overview to a primary document, then extract detailed content into separate reference files of 200–300 lines each. This keeps the AI's active context lean while preserving full information availability on demand.

Progressive disclosure separates concerns into a one-level-deep reference hierarchy. Place API docs, workflows, and examples in standalone reference files linked from your main skill document, keeping the entry point focused and scannable.

Yes. Extract overly verbose sections—API documentation, detailed examples, or edge cases—into new reference files. Update your main skill to link to these references. This reduces context bloat and improves AI processing speed without losing detail.

Apply it when creating new skills to prevent context sprawl, when reviewing performance to identify token waste, when debugging context bloat, or when a skill exceeds ~500 lines. It scales skills efficiently as they grow.

Tier 1 metadata has a 1024-character limit. Tier 2 (SKILL.md) stays under ~500 lines as an overview. Tier 3 references are 200–300 lines each with frontmatter-driven discovery, enabling efficient on-demand loading without deep nesting.