Progressive disclosure
Loading a skill's metadata first, its full instructions on activation, and any supporting files only when needed.
- Published
- Sep 27, 2026
- Checked
- Sep 27, 2026
How far we checked this page
Signed by Ravalika Korthiwada, Sep 27, 2026. Passing one check says nothing about the next.
- FormatNot checkedThe file format was not checked for this page.
- InstallsNot checkedInstallation was not checked for this page.
- LoadsNot checkedLive loading was not checked for this page.
- HelpsNot checkedA with/without task comparison was not run.
Progressive disclosure is the loading pattern the Agent Skills specification describes for skills: a host first loads only a skill’s frontmatter (name and description) for every installed skill, so it can decide which one, if any, applies to the current task. Only once a skill is activated does the host load the rest of SKILL.md. Any files the instructions point to (a references/checklist.md, a helper script) load only when the instructions actually call for them. The specification recommends keeping SKILL.md itself under roughly 5,000 tokens of instructions and 500 lines, though these are recommendations, not universal host limits.
We saw this staged loading directly in our Codex tests on September 27, 2026: for our explain-error skill, a matching prompt produced a tool trace showing cat SKILL.md followed by cat references/checklist.md. The reference file was only read once the skill was triggered. An unrelated prompt produced neither call. When we renamed references/checklist.md so the reference no longer existed, the cat failed silently in the trace, and Codex fell back on the instructions already present in SKILL.md itself, without telling the user anything was missing.
Related: Agent skill, Skill activation, Agent skill vs MCP server.