Claude Code Skills Folder Structure Explained

The skills directory

On macOS and Linux, Claude Code looks for skills in ~/.claude/skills/. On Windows, it's %USERPROFILE%\.claude\skills\. Each skill gets its own subdirectory inside that folder. Claude reads all of them at startup.

The directory itself can hold as many skill folders as you want. There's no limit, and skills don't interfere with each other.

The only required file: SKILL.md

Every skill must have a SKILL.md file at the root of its folder. That's the only hard requirement. Everything else is optional.

SKILL.md has two parts: a YAML frontmatter block and the instruction body.

YAML frontmatter

The frontmatter sits at the top of the file, delimited by ---. At minimum, it should include:

---
name: Env Doctor
description: Audits environment variables before a deploy. Catches missing, duplicated, and malformed values.
version: 1.0.0
author: Alessio Marcone
---

The description field is the most important one. Claude reads it to decide whether to invoke the skill when you make a request. A vague description like "helps with environment" will miss more triggers than a specific one like "audits environment variables before a deploy, catches missing and duplicated values."

Instruction body

Below the frontmatter is where you write what Claude should actually do. This is plain Markdown. You can include step-by-step instructions, example inputs and outputs, limitations, and any context Claude needs to do the job well.

Claude doesn't run code from here — it reads these instructions and follows them. Think of it as a detailed brief, not a script.

Optional directories

Beyond SKILL.md, a skill folder can contain three standard subdirectories:

scripts/

Executable helpers that the skill's instructions reference. For example, a shell script that checks for required environment variables, or a Python script that validates a config file. Claude can tell you to run these, or (in Claude Code) can invoke them directly if instructed to do so in SKILL.md.

references/

Long reference documents that would be too verbose to include in SKILL.md itself. API specs, required variable lists, format documentation — anything Claude might need to consult rather than memorize. The SKILL.md instructions can point to these files by relative path.

templates/

Reusable output templates. If the skill produces a report, a config file, or a structured document, put the template here. SKILL.md can tell Claude to populate it rather than generating the structure from scratch each time — which improves consistency.

A concrete example

Here's what a fully structured skill looks like on disk:

~/.claude/skills/
└── env-doctor/
    ├── SKILL.md                    ← required
    ├── scripts/
    │   └── check-env.sh            ← checks for required vars
    └── references/
        └── required-vars.md        ← list of vars the skill validates

And a simpler skill that only needs instructions:

~/.claude/skills/
└── regex-therapist/
    └── SKILL.md                    ← that's it

How Claude discovers and uses skills

At startup, Claude Code scans ~/.claude/skills/ and reads every SKILL.md it finds. It stores the descriptions internally. When you make a request, Claude checks whether any skill description matches the task you're describing.

This matching is semantic, not exact. You don't need to say the skill's name. Saying "check my env before the deploy" can trigger Env Doctor if its description mentions deploy-time environment auditing.

If no skill description matches, Claude just responds normally without invoking any skill.