Progressive Disclosure
What it is
Writing skills so the agent sees only the detail needed at the current level.
In plain terms
A museum audio guide only plays its deeper commentary when you press ‘tell me more’ on a painting, rather than reciting the full curator’s essay the moment you walk up. A well-built skill works the same way: the agent sees a one-line description by default, and only pulls in the full instructions — or a reference file buried inside — once the task actually calls for that level of detail.
Why it matters
A well-structured SKILL.md shows the agent only the depth of detail relevant to what it’s currently doing — that’s progressive disclosure, and it’s the opposite of dumping an entire procedure’s worth of instructions into every turn regardless of relevance. This keeps skill-heavy sessions from bloating turn context with instructions that don’t apply yet, which matters given how much of a turn’s token budget context construction already consumes. Skill config variables often make disclosure practical, since a single variable can gate an entire section until it’s actually needed.
How it works
The skills_list() function (tools/skills_tool.py) returns only each skill’s name, description, and category for the whole library at once — roughly 3,000 tokens total for the current set of skills, not the full instructions for any single one. Once the agent picks one, skill_view(name) loads that skill’s full SKILL.md into the conversation. If the skill’s instructions point to a supporting file, skill_view(name, file_path=…) fetches just that one file — these references/, templates/, scripts/, and assets/ folders (agent/skill_utils.py) are excluded from the top-level skill scan precisely because they’re meant to load only on this explicit third request, not sit in context by default.
A concrete example
Hermes has 175 skills installed. At the start of a turn it only sees the compact index — each one’s name and one-line description, about 3,000 tokens for that entire list rather than per skill. You ask it to fine-tune a model with Axolotl, so it calls skill_view on the axolotl skill to pull the full SKILL.md into context. That file points to a longer example buried in its references/ folder; only if the task genuinely needs that specific example does Hermes make a second, narrower call to load it too.
How it connects
This note belongs to the Skills family. Its closest neighboring concepts are: Skill Config Variables, Self-Improving Skills, Agent Runtime, Personal OS.
Source evidence
vendor/hermes-agent/agent/skill_utils.py#<file>— Structural Source Map fallback for agent/skill_utils.py. A core source file in the Skill Discovery and Invocation structure within Skills and Plugins.
Workflows
- No first-pass workflow mapping yet; this concept still appears in the vault graph through articles and source evidence.
Related articles
- How to Use Hermes Better Than Most People: Architecture, Project Isolation, and Scalable Workflows