On progressive disclosure for AI context

The first version of a personal skill usually starts as a single giant markdown file. Every principle, recipe, framework snippet and edge case ends up in one place because that’s how the essay was written, and it feels thorough while you’re drafting it. The file does teach the model. It also burns context on details the current task doesn’t need. Progressive disclosure changes the packaging rather than the opinion. Keep a thin always-visible description, a compact activated SKILL.md, and deeper references the agent opens only when the task calls for them. Three layers A skill that scales has three costs: Metadata: name, description, license. Cheap, and always available for discovery. Activated instructions: decision rules and review checks. Paid when the skill matches the task. References: long examples, tuning tables, framework recipes. Paid only on demand. skills/fluid-design/ ├── SKILL.md # rules + checklist └── references/ ├── motion-recipes.md # Motion / CSS / SwiftUI ├──…