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

# 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:

```yaml theme={null}
---
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)
---
```

<Note>
  Only `name` and `description` are required. The description is especially important as it's the primary triggering mechanism.
</Note>

### 2. Markdown Instructions

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

```markdown theme={null}
# 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.
```

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

## 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
    └── ...
```

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

## Progressive Disclosure Pattern

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

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## 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:

```markdown theme={null}
## 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

<Accordion title="SKILL.md">
  Must be exactly `SKILL.md` (all caps). This is the entry point that skill loaders expect.
</Accordion>

<Accordion title="scripts/">
  Python scripts (`.py`), shell scripts (`.sh`), or other executables. Use descriptive names like `aggregate_benchmark.py` or `package_skill.py`.
</Accordion>

<Accordion title="references/">
  Markdown files (`.md`) with descriptive names. For large files (>300 lines), include a table of contents.
</Accordion>

<Accordion title="assets/">
  Any file type: templates (`.html`, `.docx`), images (`.png`, `.svg`), fonts (`.ttf`), etc.
</Accordion>

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

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

## Next Steps

<CardGroup cols={2}>
  <Card title="Frontmatter" icon="code" href="/creating-skills/frontmatter">
    Learn about YAML frontmatter fields and their purposes
  </Card>

  <Card title="Bundled Resources" icon="box" href="/creating-skills/bundled-resources">
    Deep dive into scripts, references, and assets
  </Card>
</CardGroup>