Skip to main content
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

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
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.
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

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)
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:
</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

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
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:
1. Load the JSON file
2. Check required fields
3. Validate data types
4. 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:
ApproachSkills AvailableContext UsedImpact
All-at-once5-10 skills~50,000 tokensCan’t fit many skills
Progressive50+ skills~5,000 tokens (metadata only)Efficient discovery
Progressive + Active50+ with 1 active~10,000 tokensFull 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

Build docs developers (and LLMs) love

Get started for freeTalk to us