Skill Directory Structure

Standard organization for a Claude skill package

graph TD Root["skill-name/"]:::rootNode Skill["SKILL.md
Entry point & workflow"]:::skillNode Scripts["scripts/"]:::dirNode Templates["templates/"]:::dirNode Refs["references/"]:::dirNode Examples["examples/"]:::dirNode Root --> Skill Root --> Scripts Root --> Templates Root --> Refs Root --> Examples Scripts --> S1["analyze-graph.py"]:::scriptNode Scripts --> S2["csv-to-json.py"]:::scriptNode Scripts --> S3["validate.py"]:::scriptNode Templates --> T1["report-template.md"]:::templateNode Templates --> T2["output-format.json"]:::templateNode Refs --> R1["reading-levels.md"]:::refNode Refs --> R2["taxonomy-guide.md"]:::refNode Examples --> E1["sample-input.csv"]:::exampleNode Examples --> E2["sample-output.json"]:::exampleNode Skill -.->|Executes| Scripts Skill -.->|Uses| Templates Skill -.->|Loads| Refs Skill -.->|References| Examples classDef rootNode fill:#4facfe,stroke:#333,stroke-width:3px,color:#fff,font-size:16px classDef skillNode fill:#ffd700,stroke:#333,stroke-width:3px,color:#333,font-size:16px classDef dirNode fill:#667eea,stroke:#333,stroke-width:2px,color:#fff,font-size:16px classDef scriptNode fill:#43aa8b,stroke:#333,stroke-width:1px,color:#fff,font-size:14px classDef templateNode fill:#9b59b6,stroke:#333,stroke-width:1px,color:#fff,font-size:14px classDef refNode fill:#f77f00,stroke:#333,stroke-width:1px,color:#fff,font-size:14px classDef exampleNode fill:#e74c3c,stroke:#333,stroke-width:1px,color:#fff,font-size:14px linkStyle 9,10,11,12 stroke:#999,stroke-width:1px,stroke-dasharray:5

Directory Structure

A well-organized Claude skill follows a standard directory structure that separates workflow definition, executable code, templates, documentation, and examples.

Core Components

SKILL.md (Required)

Purpose: Entry point defining the skill's workflow, capabilities, and usage

Contains: YAML frontmatter (name, description), workflow steps, tool usage, examples

Color: Gold (primary importance)

Subdirectories

scripts/ (Optional)

Purpose: Executable automation code (Python, Bash, etc.)

Examples: Data processing, validation, conversion utilities

Best practice: Make scripts executable and include shebang lines

templates/ (Optional)

Purpose: Reusable content patterns and output formats

Examples: Markdown templates, JSON schemas, HTML boilerplates

Usage: SKILL.md loads and populates templates with actual content

references/ (Optional)

Purpose: Context documents that inform skill behavior

Examples: Style guides, taxonomy definitions, standard requirements

Usage: Skill reads these to understand domain-specific rules

examples/ (Optional)

Purpose: Sample inputs and outputs for testing and documentation

Examples: Sample CSV input, expected JSON output, test cases

Usage: Demonstrates skill capabilities and validates correctness

File Relationships

Executes: SKILL.md runs Python scripts from scripts/ directory

Uses: SKILL.md populates templates from templates/ directory

Loads: SKILL.md reads reference documents for context

References: SKILL.md points users to examples for guidance

Minimal Skill Structure

At minimum, a skill needs only SKILL.md. Add subdirectories as complexity grows:

simple-skill/
└── SKILL.md    # Self-contained workflow

complex-skill/
├── SKILL.md
├── scripts/
│   ├── process.py
│   └── validate.py
├── templates/
│   └── output.md
└── references/
    └── standards.md