Skill Structure

Understanding the anatomy of a skill: SKILL.md, bundled resources, and progressive disclosure

Skill Structure

Every skill is a self-contained folder with a specific structure that enables progressive loading and efficient context management.

Basic Structure

At minimum, a skill requires only one file:

my-skill/
└── SKILL.md (required)

A complete skill with bundled resources follows this structure:

skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter (name, description required)
│   └── Markdown instructions
└── Bundled Resources (optional)
    ├── scripts/    - Executable code for deterministic/repetitive tasks
    ├── references/ - Docs loaded into context as needed
    └── assets/     - Files used in output (templates, icons, fonts)

The SKILL.md File

The SKILL.md file is the heart of every skill. It consists of two parts:

1. YAML Frontmatter

The frontmatter contains metadata that controls skill loading and triggering:

---
name: template-skill
description: Replace with description of the skill and when Claude should use it.
license: Complete terms in LICENSE.txt
compatibility: Required tools, dependencies (optional)
---

Only name and description are required. The description is especially important as it’s the primary triggering mechanism.

2. Markdown Instructions

Below the frontmatter, write instructions in markdown that Claude will follow when the skill is active:

# Skill Title

## Overview
Brief explanation of what the skill does.

## Process
Step-by-step instructions.

## Examples
Concrete examples of usage.

## Guidelines
Best practices and important notes.

Keep SKILL.md under 500 lines. If approaching this limit, move content to reference files in the references/ directory with clear pointers from SKILL.md.

Real-World Example: skill-creator

Here’s how Anthropic’s skill-creator skill is organized:

skill-creator/
├── SKILL.md              # Main instructions (480 lines)
├── LICENSE.txt           # License information
├── agents/              # Subagent instructions
│   ├── grader.md
│   ├── comparator.md
│   └── analyzer.md
├── references/          # Loaded as needed
│   └── schemas.md       # JSON schema definitions
├── scripts/             # Executable helpers
│   ├── aggregate_benchmark.py
│   ├── run_eval.py
│   ├── package_skill.py
│   └── ...
├── eval-viewer/         # Viewer generation
│   └── generate_review.py
└── assets/              # Static resources
    └── eval_review.html # HTML template

Real-World Example: mcp-builder

The mcp-builder skill uses a leaner structure focused on reference documentation:

mcp-builder/
├── SKILL.md              # Main workflow (237 lines)
├── LICENSE.txt
├── reference/           # Detailed guides loaded on demand
│   ├── mcp_best_practices.md
│   ├── node_mcp_server.md
│   ├── python_mcp_server.md
│   └── evaluation.md
└── scripts/             # Helper utilities
    ├── run_eval.py
    └── ...

Notice how mcp-builder keeps SKILL.md concise (237 lines) by moving detailed implementation guides to separate reference files. This allows Claude to load only relevant documentation when needed.

Progressive Disclosure Pattern

Skills use a three-level loading system to optimize context usage:

1. Level 1: Metadata (Always Loaded)

   The name and description fields are always in context (~100 words). Claude uses these to decide whether to trigger the skill.

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

   When Claude decides to use a skill, it loads the full SKILL.md content. Keep this under 500 lines for optimal performance.

3. Level 3: Bundled Resources (Loaded as Needed)

   Scripts, references, and assets are loaded only when explicitly referenced. Scripts can execute without being loaded into context.

Domain Organization Pattern

When a skill supports multiple frameworks or variants, organize by domain with clear navigation:

cloud-deploy/
├── SKILL.md              # Workflow + provider selection guide
└── references/
    ├── aws.md           # AWS-specific instructions
    ├── gcp.md           # Google Cloud instructions
    └── azure.md         # Azure instructions

In SKILL.md, provide clear pointers:

## Deployment Workflow

1. Identify the cloud provider from user requirements
2. Load the appropriate reference:
   - AWS: Read `references/aws.md`
   - GCP: Read `references/gcp.md`
   - Azure: Read `references/azure.md`
3. Follow the provider-specific deployment steps

This pattern ensures Claude loads only the relevant documentation for each use case.

File Naming Conventions

SKILL.md

Must be exactly SKILL.md (all caps). This is the entry point that skill loaders expect.

scripts/

Python scripts (.py), shell scripts (.sh), or other executables. Use descriptive names like aggregate_benchmark.py or package_skill.py.

references/

Markdown files (.md) with descriptive names. For large files (>300 lines), include a table of contents.

assets/

Any file type: templates (.html, .docx), images (.png, .svg), fonts (.ttf), etc.

Skill Size Guidelines

Component	Recommended Size	Rationale
SKILL.md frontmatter	~100 words	Always in context, keep concise
SKILL.md body	<500 lines	Loaded on trigger, affects performance
Reference files	Unlimited	Loaded selectively, can be extensive
Scripts	Unlimited	Execute without loading into context
Assets	Reasonable	Embedded in outputs, consider file sizes

These are guidelines, not hard limits. The skill-creator SKILL.md is 480 lines and works well. If your instructions are genuinely complex, it’s fine to exceed 500 lines.

Next Steps

Frontmatter

Learn about YAML frontmatter fields and their purposes

Bundled Resources

Deep dive into scripts, references, and assets