> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/anthropics/skills/llms.txt
> Use this file to discover all available pages before exploring further.
# Progressive Disclosure Loading System
> Understand the three-level loading system that enables skills to provide extensive capabilities while minimizing context window usage.
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
```yaml theme={null}
---
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:**
```markdown theme={null}
# 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:**
```yaml theme={null}
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:
```markdown theme={null}
---
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:
```yaml theme={null}
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:
```yaml theme={null}
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:**
```markdown theme={null}
## 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:
````markdown theme={null}
## 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](./reference/api_endpoints.md)
````
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:**
```markdown theme={null}
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:**
````markdown theme={null}
Run the validation script:
```bash
python scripts/validate_json.py output.json
````
```
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.
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
```yaml theme={null}
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
```markdown theme={null}
# 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
Learn how to structure SKILL.md files
Build skills with effective progressive disclosure
Organize scripts, references, and assets