SYS/DEF
Progressive disclosure
Show the agent only what it needs now: description first, then the body, then files. Spare the context.
Definition
Progressive disclosure, in the Agent Skills spec, is the loading rule: the agent first reads metadata (name, description) to decide whether the skill applies; it injects the Markdown body only on match; annex files come only if they are referenced. It is the opposite of the encyclopaedic system prompt.
In product UX the same words mean an interface that reveals complexity on demand. Here the “user” is the model, and the cost is in tokens.
When it matters
When writing every SKILL.md: the description must be triggerable on its own (“use when you need to check an SRM split”), the body in steps, heavy examples in separate files. It is also the review criterion for an “official” skill: if everything is in the body, it is no longer a skill, it is a pasted manual.
Shamalo’s Agent Skills quiz tests exactly that, not YAML recitation.
Pitfalls
Cramming everything into the description “to be sure it matches”. Repeating the frontmatter in the body. Pointing at ten files “just in case”. Believing the loader will read subfolders with no explicit link.
Related terms
Related tool
Frontmatter, triggerable description, progressive disclosure, budget — scored out of 100: Open Agent Skills quiz.