Progressive Disclosure Loading System

The Agent Skills specification uses a three-level progressive disclosure loading system. This design allows skills to provide extensive capabilities and documentation while minimizing context window usage.

Why Progressive Disclosure?

AI agents have limited context windows. Loading all skill documentation at once would:

Consume valuable context space
Overwhelm the agent with irrelevant information
Reduce the number of skills that can be available simultaneously
Slow down processing and increase costs

Progressive disclosure solves this by loading information only when needed.

The Three Levels

Level 1: Metadata (Always Loaded)

What’s included:

Skill name
Skill description
Optional compatibility requirements

Size: ~50-200 words per skill Purpose: Enable skill discovery and triggering decisions Context impact: Minimal - agents can have awareness of dozens of skills

---
name: mcp-builder
description: Guide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).
---

This metadata is always in the agent’s context, appearing in the available_skills list. The agent uses it to decide when to load the full skill.

Level 2: SKILL.md Body (Loaded on Trigger)

What’s included:

Instructions and workflows
Examples and patterns
Guidelines and best practices
References to bundled resources

Size: <500 lines ideal (can be longer if needed) Purpose: Provide core instructions for executing the skill Context impact: Moderate - loaded only when skill is triggered Example structure:

# MCP Server Development Guide

## Overview
Create MCP servers that enable LLMs to interact with external services...

## Process

### Phase 1: Deep Research and Planning

#### 1.1 Understand Modern MCP Design
API Coverage vs. Workflow Tools: Balance comprehensive API endpoint coverage...

#### 1.2 Study MCP Protocol Documentation
Start with the sitemap to find relevant pages...

#### 1.3 Study Framework Documentation
**For TypeScript (recommended):**
- [⚡ TypeScript Guide](./reference/node_mcp_server.md)

**For Python:**
- [🐍 Python Guide](./reference/python_mcp_server.md)

### Phase 2: Implementation
[Core implementation instructions...]

### Phase 3: Testing
[Testing instructions...]

Notice how the SKILL.md references bundled resources without loading them yet.

Level 3: Bundled Resources (Loaded on Demand)

What’s included:

scripts/ - Executable code
references/ - Detailed documentation
assets/ - Templates, fonts, images

Size: Unlimited (scripts can execute without loading into context) Purpose: Provide detailed reference material and reusable code Context impact: Variable - loaded only when referenced Example resource organization:

mcp-builder/
├── SKILL.md
├── scripts/
│   ├── validate_server.py
│   └── test_mcp_server.js
├── reference/
│   ├── mcp_best_practices.md      # ~400 lines
│   ├── node_mcp_server.md         # ~600 lines
│   └── python_mcp_server.md       # ~500 lines
└── assets/
    └── server_template.ts

Loading Flow Example

Let’s walk through how the system works for a user request:

Step 1: Skill Discovery

User request: “Help me build an MCP server for the GitHub API” Agent’s context includes:

available_skills:
  - name: mcp-builder
    description: Guide for creating high-quality MCP servers...
  - name: skill-creator  
    description: Create new skills, modify and improve existing skills...
  - name: pdf
    description: Create and edit PDF documents...
  # ... other skills

Agent decision: “mcp-builder” matches - load it

Step 2: Load SKILL.md Body

The agent loads the full SKILL.md file into context:

---
name: mcp-builder
description: ...
---

# MCP Server Development Guide

## Overview
Create MCP servers...

## Process

### Phase 1: Deep Research and Planning

#### 1.3 Study Framework Documentation
**For TypeScript (recommended):**
- [⚡ TypeScript Guide](./reference/node_mcp_server.md)
...

The agent now has the workflow and knows references are available.

Step 3: Load Bundled Resources as Needed

Agent follows Phase 1.3: “I need to study the framework documentation. The user wants to use TypeScript, so I’ll read the TypeScript guide.” Agent reads: reference/node_mcp_server.md Only this one reference file is loaded - the Python guide, best practices, and scripts remain unloaded. Later, during implementation: “The skill mentions a validation script. I’ll execute it to check the server.” Agent runs: python scripts/validate_server.py The script executes without loading into context.

Best Practices for Each Level

Level 1: Metadata Design

Make Descriptions Discoverable

Include specific keywords and contexts that users might mention:

description: Format git commit messages following conventional commits specification. Use when creating commits, formatting commit messages, or standardizing repository commit history.

Keywords: git, commit, messages, conventional commits, commit history

Be Pushy About When to Use

Combat under-triggering by explicitly listing use cases:

description: Create new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, update or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.

Keep It Concise But Complete

Target ~50-200 words. Include:

What the skill does (capabilities)
When to use it (contexts, triggers)
What it enables (outcomes)

Avoid:

Implementation details (save for SKILL.md body)
Examples (save for SKILL.md body)
Lengthy explanations

Level 2: SKILL.md Body Design

Target <500 Lines

If approaching 500 lines, consider:

Moving detailed documentation to reference files
Consolidating similar instructions
Using references for framework-specific details

Good pattern:

## Implementation

For language-specific details:
- TypeScript: See [reference/typescript.md](./reference/typescript.md)
- Python: See [reference/python.md](./reference/python.md)

Reference Resources Clearly

Be explicit about when to read each resource:

## Validation

After implementation, run the validation script:
```bash
python scripts/validate_output.py output.json

API Reference

For detailed endpoint documentation, see:

reference/api_endpoints.md

</Accordion>

<Accordion title="Provide Clear Navigation">
For large reference files, include tables of contents:

```markdown
## Reference Documentation

The [best practices guide](./reference/mcp_best_practices.md) covers:
- Tool design patterns (lines 1-150)
- Error handling (lines 151-250)  
- Authentication (lines 251-350)
- Testing strategies (lines 351-400)

Read the relevant section based on your current phase.

Level 3: Bundled Resources Design

Organize by Purpose

Use consistent directory structure:

skill-name/
├── SKILL.md
├── scripts/          # Executable code
│   ├── validate.py
│   └── helper.js
├── references/       # Documentation
│   ├── api.md
│   └── examples.md  
└── assets/          # Templates, resources
    └── template.json

Prefer Scripts Over Instructions

If agents repeatedly write similar code across test cases, bundle it as a script:Instead of instructing:

Write a Python script to validate the JSON output:
Load the JSON file
Check required fields
Validate data types
Report any errors

Provide the script:

Run the validation script:
```bash
python scripts/validate_json.py output.json

</Accordion>

<Accordion title="Domain-Based Reference Organization">
For multi-framework skills, organize references by variant:

cloud-deploy/ ├── SKILL.md # Selection logic └── references/ ├── aws.md # AWS-specific ├── gcp.md # GCP-specific
└── azure.md # Azure-specific

The agent reads only the relevant file.
</Accordion>

<Accordion title="Include Reference File TOCs">
For reference files over 300 lines, include a table of contents:

```markdown
# MCP Best Practices

## Table of Contents

- [Tool Design Patterns](#tool-design-patterns) (lines 1-150)
- [Error Handling](#error-handling) (lines 151-250)
- [Authentication](#authentication) (lines 251-350)  
- [Testing Strategies](#testing-strategies) (lines 351-400)

## Tool Design Patterns
...

Real-World Example

The skill-creator skill demonstrates effective progressive disclosure:

Level 1: Metadata

name: skill-creator
description: Create new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, update or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.

Size: 56 words Purpose: Triggers on skill creation, modification, testing, or optimization requests

Level 2: SKILL.md Body

# Skill Creator

A skill for creating new skills and iteratively improving them.

## Creating a skill

### Capture Intent
1. What should this skill enable Claude to do?
2. When should this skill trigger?
...

### Write the SKILL.md
...

### Test Cases  
...

## Running and evaluating test cases
...

## Improving the skill
...

Size: ~480 lines Purpose: Complete workflow for skill creation and iteration

Level 3: Bundled Resources

skill-creator/
├── SKILL.md
├── agents/
│   ├── grader.md          # Grading instructions (loaded when grading)
│   ├── comparator.md      # Comparison logic (loaded for A/B tests)
│   └── analyzer.md        # Analysis instructions (loaded for analysis)
├── references/
│   └── schemas.md         # JSON schemas (loaded when needed)
├── scripts/
│   ├── aggregate_benchmark.py    # Executes without loading
│   ├── package_skill.py          # Executes without loading
│   └── run_loop.py               # Executes without loading
└── assets/
    └── eval_review.html          # Template loaded when needed

Total size: ~1500 lines across all files Context usage: Only relevant portions loaded when needed

Context Efficiency Metrics

Progressive disclosure dramatically reduces context usage:

Approach	Skills Available	Context Used	Impact
All-at-once	5-10 skills	~50,000 tokens	Can’t fit many skills
Progressive	50+ skills	~5,000 tokens (metadata only)	Efficient discovery
Progressive + Active	50+ with 1 active	~10,000 tokens	Full capabilities when needed

With progressive disclosure, agents can have awareness of dozens of skills while using minimal context. Only when a skill is triggered does it consume significant context.

Implementation Notes

The specification is implementation-agnostic, but here are common patterns:

Metadata Storage

Some implementations parse YAML frontmatter from SKILL.md files
Others maintain separate metadata indexes
Both approaches work with the same SKILL.md format

Resource Loading

References loaded via file read operations
Scripts executed via subprocess/shell commands
Assets copied or loaded as needed

Caching

Metadata typically cached for fast skill discovery
SKILL.md bodies may be cached after first load
Bundled resources loaded fresh each time or cached by implementation

Next Steps

SKILL.md Format

Learn how to structure SKILL.md files

Creating Skills

Build skills with effective progressive disclosure

Bundled Resources

Organize scripts, references, and assets

​Why Progressive Disclosure?

​The Three Levels

​Level 1: Metadata (Always Loaded)

​Level 2: SKILL.md Body (Loaded on Trigger)

​Level 3: Bundled Resources (Loaded on Demand)

​Loading Flow Example

​Step 1: Skill Discovery

​Step 2: Load SKILL.md Body

​Step 3: Load Bundled Resources as Needed

​Best Practices for Each Level

​Level 1: Metadata Design

​Level 2: SKILL.md Body Design

​API Reference

​Level 3: Bundled Resources Design

​Real-World Example

​Level 1: Metadata

​Level 2: SKILL.md Body

​Level 3: Bundled Resources

​Context Efficiency Metrics

​Implementation Notes

​Metadata Storage

​Resource Loading

​Caching

​Next Steps

SKILL.md Format

Creating Skills

Bundled Resources

Why Progressive Disclosure?

The Three Levels

Level 1: Metadata (Always Loaded)

Level 2: SKILL.md Body (Loaded on Trigger)

Level 3: Bundled Resources (Loaded on Demand)

Loading Flow Example

Step 1: Skill Discovery

Step 2: Load SKILL.md Body

Step 3: Load Bundled Resources as Needed

Best Practices for Each Level

Level 1: Metadata Design

Level 2: SKILL.md Body Design

API Reference

Level 3: Bundled Resources Design

Real-World Example

Level 1: Metadata

Level 2: SKILL.md Body

Level 3: Bundled Resources

Context Efficiency Metrics

Implementation Notes

Metadata Storage

Resource Loading

Caching

Next Steps