Progressive disclosure
Updated 2026-07-11
Questions this answers
- My Skill or custom instructions are bloating every AI call.
- How do I give my agent a lot of detail without loading it all every time?
- Why is my agent slow or expensive even on simple tasks?
- How should I actually structure a SKILL.md file?
The Fix
When you write a Skill, it's tempting to stuff everything into one big file. The problem is the AI then loads all of it on every call, even the parts it rarely needs. That's slower and more expensive. The fix is a structure called progressive disclosure: give the AI a little up front and let it reach for more only when the task calls for it.
Think of a Skill in three levels. The frontmatter at the top (the name and description) is always loaded, and it's just for routing: it tells the AI when this Skill applies. The body loads when the Skill triggers, so keep it lean, roughly a page, the core of how to do the thing. The details, edge cases, examples, and scripts live in a references folder that loads on demand, only when they're actually relevant.
The point is the same instructions, structured this way, can cut your token cost a few times over. A Skill isn't really a prompt. It's a spec for what enters the AI's context, when, and at what cost.
When to Use It
Use this whenever a Skill grows past a page or starts covering several distinct situations. Push the situational detail into references and keep the top file short. If your Skill is genuinely tiny, one job, a few lines, don't bother splitting it. See the Agent Skills entry for how Skills work in the first place.