Anthropic Skills Folder Structure and SKILL.md File Format: Complete Guide

An Anthropic skill is a self-contained directory containing a mandatory SKILL.md file with YAML front matter and Markdown instructions, plus optional scripts/, references/, and assets/ subdirectories that optimize Claude's context window usage.

The anthropics/skills repository defines a strict convention for packaging capabilities that Claude can discover and invoke on demand. Understanding the skill folder structure and SKILL.md file format ensures your custom skills are discoverable, maintainable, and optimized for context efficiency.

Required Skill Folder Structure

Every skill begins with a root folder named after the capability it provides. According to the Skill Creator guide in skills/skill-creator/SKILL.md (lines 47-63), this directory must contain at least one mandatory file to be valid.

The SKILL.md file is the only required element. It serves as the entry point that Claude reads after the skill triggers, containing both metadata and procedural instructions. Without this file, Claude cannot discover or load the skill.

Optional Subdirectories for Modular Design

To keep prompts lightweight while providing deep functionality, the skill folder structure supports three optional subdirectories. As illustrated in the canonical guide (lines 47-63), these directories separate deterministic code from documentation and static assets.

scripts/ houses deterministic, reusable code written in Python, Bash, or other languages. These scripts execute without loading the entire source into the prompt, preserving context window space. For example, the PDF skill stores rotate_pdf.py and merge_pdfs.py in this directory.

references/ contains large documentation, schemas, or examples that Claude loads only when explicitly requested. This prevents bloating the initial prompt with reference material that may not be needed for every invocation.

assets/ stores files that the skill copies or embeds in its output, such as templates, images, or fonts. These are typically static resources referenced by the skill's procedural logic.

Anatomy of the SKILL.md File

The SKILL.md file follows a strict two-part structure documented in the Skill Creator guide (lines 65-70). It combines YAML front matter for machine-readable metadata with a Markdown body for human-readable instructions.

The front matter must include:

• name: The skill identifier
• description: A brief but complete trigger description that helps Claude recognize when to invoke the skill
• license (optional): SPDX identifier or link to LICENSE.txt

Following the closing --- of the front matter, the Markdown body contains the procedural instructions, examples, and links to optional resources that Claude reads after the skill triggers.

Minimal SKILL.md Skeleton

---
name: your-skill-name
description: Brief but complete trigger description.
license: (optional) SPDX or link to LICENSE.txt
---

## Instructions

Procedural steps and examples go here.

Practical Implementation Examples

Creating a new skill using the provided initialization script ensures compliance with the folder structure standards. The init_skill.py script located in skills/skill-creator/scripts/ generates the complete directory layout.

# In the repo root

python skills/skill-creator/scripts/init_skill.py pdf --path skills/pdf

This command creates the skills/pdf/ directory with a pre-populated SKILL.md containing the required front matter.

Adding Deterministic Scripts

Adding scripts to the skill keeps the prompt lightweight while providing complex functionality. For example, adding a PDF rotation script:

# skills/pdf/scripts/rotate_pdf.py

from pypdf import PdfReader, PdfWriter

def rotate(input_path: str, output_path: str, angle: int = 90):
    reader = PdfReader(input_path)
    writer = PdfWriter()
    for page in reader.pages:
        page.rotate(angle)
        writer.add_page(page)
    with open(output_path, "wb") as f:
        writer.write(f)

Reference this script from the SKILL.md body without loading the full source into the prompt context:

## Rotate a PDF

Use the bundled script `scripts/rotate_pdf.py`:

```bash
python scripts/rotate_pdf.py input.pdf rotated.pdf

### Linking Large Reference Files

For large documentation that should not load automatically, place it in `references/` and link conditionally:

```markdown

### Form filling

See the detailed guide in `references/FORMS.md` for step-by-step form population.

Claude loads references/FORMS.md only when the user explicitly requests form filling information, optimizing context window usage.

Summary

• A valid skill requires exactly one mandatory file: SKILL.md containing YAML front matter (name, description, optional license) and a Markdown instruction body.
• The skill folder structure supports three optional subdirectories: scripts/ for deterministic code, references/ for on-demand documentation, and assets/ for static output resources.
• Use the init_skill.py script in skills/skill-creator/scripts/ to generate compliant folder layouts automatically.
• Place large reference materials in references/ rather than the main SKILL.md to prevent prompt bloat and optimize Claude's context window.

Frequently Asked Questions

What happens if I omit the YAML front matter in SKILL.md?

Claude will not recognize the file as a valid skill. The front matter containing name and description is mandatory because it provides the machine-readable metadata required for skill discovery and triggering according to the skills/skill-creator/SKILL.md specification.

Can I use subdirectories inside the scripts/ folder?

Yes. While the canonical structure places scripts directly in scripts/, you may organize them into subdirectories for complex skills. Reference them using relative paths (e.g., scripts/utils/helpers.py) when invoking from the SKILL.md body.

How does Claude decide when to load files from the references/ directory?

Claude loads reference files only when explicitly requested by the user or when the procedural logic in SKILL.md specifically includes them. This on-demand loading prevents the context window from being consumed by documentation that is not relevant to the current task.

Is the license field in SKILL.md front matter required?

No. The license field is optional. If omitted, the skill defaults to the repository's overall license terms. When specified, use an SPDX identifier or a relative path to a LICENSE.txt file within the skill directory.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}