# Claude Skill Directory Structure: Complete Guide to SKILL.md Layout > Understand the Claude Skill directory structure. Learn the essential SKILL.md layout and optional script template and resource subdirectories for Claude skills. - Repository: [Composio/awesome-claude-skills](https://github.com/composiohq/awesome-claude-skills) - Tags: how-to-guide - Published: 2026-08-29 --- **A Claude Skill is a self-contained folder with a mandatory [`SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/ComposioHQ/awesome-claude-skills/blob/master/README.md) as the official standard for skill organization. ## The Required SKILL.md File The [`SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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 ```yaml --- 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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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: ```bash # 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 ```bash 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 ```bash # 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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/SKILL.md) and executes [`scripts/hello.sh`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/SKILL.md) file at the root - The [`SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/SKILL.md) instructions. If the skill workflow does not mention [`scripts/helper.py`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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.