Progressive Disclosure: Efficient Skill Loading

The Context Budget Problem

Every token loaded into context has a cost: computation time, API spend, and most critically, space that is no longer available for the actual task. A large language model has a finite working memory. The more of that memory occupied by loaded skill content, the less is available for reasoning about the current problem.

This is why naive skill loading — copy-pasting every skill into the system prompt — does not scale past a handful of simple procedures. A library of 50 skills could easily consume 100,000 tokens of context before a single line of work is done. The progressive disclosure architecture solves this by loading skill content in stages, exposing only as much information as the current stage of reasoning requires.

Level 0: The Metadata Scan

At the start of every session, Hermes calls skills_list() to build a directory of available skills. This call returns approximately 3,000 tokens of data regardless of how many skills are installed or how large each skill is. What comes back is metadata only: the name, description, and category of each skill.

From this ~3,000-token snapshot, the agent builds a mental map of what procedures are available. No skill content is loaded. No procedure steps are in context. Only enough information to answer the question: "Is there a skill that might be relevant here?"

This is why the description field is so critical. The agent's relevance decision at Level 0 depends entirely on what the 60-character description says. A vague description ("helps with git tasks") gives the agent weak signal — it cannot tell whether this skill is for creating branches, resolving conflicts, or managing remotes. A specific description ("submit PR with squash and team labels") gives the agent a clear trigger condition. When you see that description in a code review context, the match is obvious.

Designing good Level 0 metadata is the highest-leverage skill authoring skill. Everything else flows from whether the agent can correctly identify which skills are relevant from the metadata alone.

Level 1: Full Content Retrieval

When the agent determines a skill is relevant, it calls skill_view(name) to retrieve the full SKILL.md content. This includes the complete frontmatter, all four body sections, and any inline code blocks. The token cost at Level 1 varies with the size of the SKILL.md file.

Level 1 is where the agent reads the Procedure steps, the Pitfalls it should watch for, and the Verification steps it will run. This is the level at which the skill actually does its job — providing the agent with the instructions it needs to execute a complex, multi-step procedure correctly.

A well-designed skill keeps Level 1 to a manageable size. Aim for SKILL.md files that are comprehensive enough to be actionable but not so long that loading them crowds out task context. As a rough guide: if your Procedure section exceeds 20 steps, the skill is probably covering too much ground and should be split into smaller, more focused skills.

Level 2: Reference File Access

Some skills reference large amounts of supporting material — API specifications, lookup tables, configuration schemas, or sample templates — that would bloat the SKILL.md body if included inline. Level 2 solves this by keeping those materials in separate files within the skill directory.

The agent calls skill_view(name, path) to retrieve a specific file from the skill directory. For example, a skill for working with a complex API might have its main SKILL.md explain the overall procedure, and a file at references/api-endpoints.md listing every endpoint with parameters and response shapes. The agent only fetches that reference file when it reaches the step in the procedure that requires it.

The three standard Level 2 directories are references/ for documentation and lookup tables, templates/ for boilerplate files the skill generates, and scripts/ for shell commands the procedure invokes via the terminal tool. Each file in these directories is individually retrievable at Level 2.

Designing Skills for Progressive Disclosure

Building a skill that works well across all three levels requires intentional decisions about what goes where.

At Level 0, you control the description field. Make it tell the story of when to invoke the skill, not what the skill contains. Use the category field to help with coarse filtering. Tags improve searchability in the Hub but do not affect Level 0 scanning.

At Level 1, your SKILL.md body should be complete enough to execute the main procedure without requiring Level 2 lookups for the happy path. The Procedure steps should work end-to-end in the common case. Level 2 files are for detail that only certain procedure branches need.

At Level 2, organize reference files to match the structure of your procedure. If step 4 of your procedure might need API reference material, put that reference material in references/ under a name that clearly corresponds to step 4. The agent fetches Level 2 files by name — clear naming makes retrieval reliable.

How the Agent Decides Which Level to Load

The loading decisions are made by the agent based on what it needs at each stage of task execution. You cannot directly control which level the agent loads, but you can influence the decision through skill design.

The agent loads Level 1 when it has determined a skill is relevant and needs the procedure steps. It loads Level 2 when a specific step in the procedure references a supporting file, or when the Level 1 content indicates that additional reference material exists and is needed for the current branch of execution.

The practical implication: if your skill's Procedure section says "see references/api-endpoints.md for the full parameter list," the agent will know to fetch that file when it reaches that step. If the reference exists but is never mentioned in the Procedure, the agent may never retrieve it. Make Level 2 references explicit in the procedure steps that need them.