Progressive Disclosure

Agents do not load every skill into memory the moment they start. Doing so would be wasteful: a project might have dozens of skills, each with extensive instructions and supporting files. Instead, most agent platforms use a 3-tier loading system that progressively discloses skill content only when it is needed. Understanding this system helps you write skills that are performant and context-window friendly.

Why Progressive Disclosure Matters

An agent's context window is a finite resource. Every token loaded into context is a token that cannot be used for reasoning, code generation, or conversation. If the agent loaded the full body of every available skill at startup, a project with 30 skills averaging 500 tokens each would consume 15,000 tokens before the user even typed a question.

Progressive disclosure solves this by following a simple principle: load the minimum information needed at each stage. Skills start as lightweight descriptions and only expand to full instructions when the user actually invokes them.

The Three Tiers

Tier 1: Description Only

When the agent starts a session, it scans all skill locations and reads only the description field from each skill's frontmatter. This is the cheapest possible representation of a skill — typically a single sentence.

---
description: Generate a concise commit message for staged changes
allowed-tools:
  - Bash(git diff --cached)
---

Look at the currently staged git changes...
(this body is NOT loaded at Tier 1)

At Tier 1, the agent only sees the description string: "Generate a concise commit message for staged changes". The body, the allowed-tools list, and everything else is invisible. This is what powers the autocomplete list when you type / in the agent prompt.

Tier 2: Full Instructions

When a user invokes a skill (e.g., types /commit-msg), or when the agent determines that a skill is relevant to the current task, it loads the entire skill file into context. This includes:

• All frontmatter fields (allowed-tools, description, etc.)
• The complete Markdown body with instructions
• Any inline code examples or templates in the body

---
description: Generate a concise commit message for staged changes
allowed-tools:
  - Bash(git diff --cached)
  - Bash(git log --oneline -5)
---

# Commit Message Generator

Look at the currently staged git changes using `git diff --cached`.

## Rules
1. Use conventional commit format: type(scope): description
2. Keep the subject line under 72 characters
3. Use imperative mood ("add feature" not "added feature")
4. Include a body if the diff is complex

## Types
- feat: new feature
- fix: bug fix
- docs: documentation only
- refactor: code restructuring
- test: adding or fixing tests
- chore: maintenance tasks

At this stage, the agent has everything it needs to execute the skill. The instructions become part of the agent's active context and guide its behavior for the duration of the task.

Tier 3: Supporting Files

Some skills reference external files — templates, scripts, configuration snippets, or reference documentation. These files live alongside the SKILL.md in the skill's directory and are only loaded when the skill body instructs the agent to read them.

---
description: Scaffold a new API endpoint with tests
allowed-tools:
  - Read
  - Write
  - Bash(npm test)
---

# New API Endpoint

Read the template files from the skill directory:

1. Read the route template: ${SKILL_DIR}/templates/route.ts.hbs
2. Read the test template: ${SKILL_DIR}/templates/route.test.ts.hbs
3. Read the validation schema: ${SKILL_DIR}/templates/schema.ts.hbs

Use these templates to create the new endpoint files.

The template files referenced above are not loaded when the skill is invoked. They are loaded individually when the agent executes the Read tool to access each file. This keeps the initial context cost at Tier 2 and only adds Tier 3 content as needed.

Context Budget Implications

Understanding the tier system helps you make smart decisions about where to put information:

• Tier 1 (description) — Pennies of context. You can have hundreds of skills without meaningful overhead.
• Tier 2 (instructions) — Hundreds to low thousands of tokens. Keep skill bodies focused and concise. If a skill is over 2,000 tokens, consider whether some content belongs in supporting files instead.
• Tier 3 (supporting files) — Variable cost, loaded on demand. Large templates or reference docs belong here because they only enter context when actually needed.

Design Principles

The progressive disclosure model suggests several best practices for skill authors:

1. Front-load the most important instructions. Put critical rules and constraints at the top of the skill body. If context gets tight, agents prioritize earlier content.
2. Move large reference material to supporting files. A 200-line template does not belong inline in the skill body. Put it in a separate file and reference it with ${SKILL_DIR}.
3. Write descriptions that stand alone. The description must make sense without the body, because at Tier 1 the body does not exist in context.
4. Use conditional loading. If a skill has multiple templates for different scenarios, instruct the agent to read only the relevant one rather than all of them.

---
description: Create a new React component with the appropriate pattern
---

Ask the user what type of component they need.

- If they want a **page component**, read ${SKILL_DIR}/templates/page.tsx.hbs
- If they want a **UI component**, read ${SKILL_DIR}/templates/ui.tsx.hbs
- If they want a **layout**, read ${SKILL_DIR}/templates/layout.tsx.hbs

Only read the template you need. Do not load all three.

What's Next

Now that you understand how skills are loaded into context, the next lesson covers string substitutions — the variable system that lets skills accept arguments and access runtime information.