Claude Skill Directory Structure: Complete Guide to SKILL.md Layout

A Claude Skill is a self-contained folder with a mandatory SKILL.md file at the root and optional scripts/, templates/, or resources/ subdirectories that Claude loads on-demand.

The ComposioHQ/awesome-claude-skills repository establishes a standardized, portable layout that all Claude agents recognize. Understanding the directory structure for a Claude Skill ensures your custom workflows integrate seamlessly with Claude Code and remain efficient in the context window.

Core Directory Layout

Every skill follows a predictable folder hierarchy defined in the repository’s Skill Structure specification. The canonical structure consists of one required file and three optional asset folders:

skill-name/                 # Top-level folder for the skill

├─ SKILL.md                # Required: YAML front-matter + markdown instructions

├─ scripts/   (optional)   # Helper scripts (bash, python, etc.)

├─ templates/ (optional)   # Document or code templates

└─ resources/ (optional)   # Static assets (images, CSVs, PDFs, etc.)

This layout appears in ComposioHQ/awesome-claude-skills/blob/master/README.md as the official standard for skill organization.

The Required SKILL.md File

The SKILL.md file serves as the entry point and brain of the skill. It must reside at the root of the skill folder.

File Specifications

• YAML Front-Matter: Must start with metadata fields including name and description
• Instruction Body: Contains the detailed workflow, steps, and examples Claude follows
• Token Efficiency: Claude loads only the metadata (~100 tokens) initially; the full file streams in when the skill becomes relevant

---
name: my-skill
description: Demonstrates the minimal Claude Skill layout
---

# My Skill

This skill shows how to echo a message and run an optional helper script.

## Instructions

1. Say hello to the user.
2. If a `scripts/hello.sh` exists, execute it and include its output.

Optional Asset Directories

While SKILL.md contains the logic, these three subdirectories house auxiliary files that the skill references:

scripts/

Stores executable helpers invoked by the skill workflow. Common contents include bash automation, Python data processors, or Node.js utilities.

Example path: tailored-resume-generator/scripts/ (as seen in the repository)

templates/

Holds reusable starter files such as email drafts, markdown skeletons, or configuration snippets that Claude copies and populates during execution.

Example path: tailored-resume-generator/templates/

resources/

Contains static reference material the skill reads but does not execute: CSV datasets, brand color palettes, legal boilerplate PDFs, or font files.

Example path: tailored-resume-generator/resources/

Real-World Example: Tailored Resume Generator

The repository’s tailored-resume-generator skill demonstrates the directory structure in practice:

• tailored-resume-generator/SKILL.md — Core instructions defining the resume customization workflow
• tailored-resume-generator/scripts/ — Helper utilities for processing job descriptions
• tailored-resume-generator/templates/ — Resume layout templates
• tailored-resume-generator/resources/ — Static styling guides or example data

This organization keeps the skill modular: the main logic lives in SKILL.md while specific implementations stay separated in subdirectories.

Creating a Skill from Scratch

Follow these commands to instantiate a new skill with the proper directory structure:

# 1️⃣ Create the folder

mkdir -p my-skill

# 2️⃣ Add the required SKILL.md with YAML front-matter

cat > my-skill/SKILL.md <<'EOF'
---
name: my-skill
description: Demonstrates the minimal Claude Skill layout
---

# My Skill

This skill shows how to echo a message and run an optional helper script.

## Instructions

1. Say hello to the user.
2. If a `scripts/hello.sh` exists, execute it and include its output.

## Examples

User: “Run my‑skill”
Assistant: “Hello! Here’s what the script says: …”
EOF

Adding Optional Scripts

mkdir -p my-skill/scripts
cat > my-skill/scripts/hello.sh <<'EOS'
#!/usr/bin/env bash
echo "👋 Script says: Welcome to Claude Skills!"
EOS
chmod +x my-skill/scripts/hello.sh

Installing for Claude Code

# Copy the skill into the local Claude Code directory

mkdir -p ~/.config/claude-code/skills/
cp -r my-skill ~/.config/claude-code/skills/

# Verify the metadata

head ~/.config/claude-code/skills/my-skill/SKILL.md

When you type /my-skill in Claude Code, the agent loads the metadata first, then streams the full SKILL.md and executes scripts/hello.sh if present.

Loading and Execution Flow

Claude agents handle skills through a two-phase loading process to maintain context window efficiency:

1. Metadata Phase: Claude reads only the YAML front-matter from SKILL.md (~100 tokens) to display the skill name and description in command palettes
2. Execution Phase: When triggered, Claude streams the full instruction set from SKILL.md and loads any referenced files from scripts/, templates/, or resources/ on-demand

This architecture prevents unused skills from consuming context tokens while providing rich functionality when activated.

Summary

• Every Claude Skill is a self-contained folder with a required SKILL.md file at the root
• The SKILL.md must contain YAML front-matter (name, description) followed by detailed markdown instructions
• Optional subdirectories include scripts/ (executables), templates/ (starter files), and resources/ (static assets)
• Skills install into ~/.config/claude-code/skills/ for local Claude Code usage
• Claude loads only metadata initially (~100 tokens), streaming full content on-demand to preserve context window space

Frequently Asked Questions

What happens if a skill is missing the SKILL.md file?

Claude cannot load or recognize the skill. The SKILL.md file is mandatory for discovery; without it, the folder contents remain invisible to Claude agents even if scripts or resources are present.

Can a skill function without the scripts, templates, or resources folders?

Yes. These directories are strictly optional. A skill containing only a properly formatted SKILL.md file is valid and functional, though it cannot reference external files for complex operations.

How does Claude prioritize which files to load from optional directories?

Claude loads files on-demand based solely on references within the active SKILL.md instructions. If the skill workflow does not mention scripts/helper.py, that file remains unloaded, preventing unnecessary token consumption.

Is the YAML front-matter in SKILL.md validated by Claude?

Claude reads the name and description fields for skill registration and display purposes. While Claude is forgiving with parsing, including properly formatted YAML front-matter ensures consistent behavior across different Claude Code versions and agent implementations.

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