A Claude skill is a folder. That is the whole thing. The Claude skill folder structure has exactly one required file, SKILL.md, and everything else is optional weight you add only when the skill earns it. If you have been picturing some elaborate config tree with a manifest and a lockfile and three layers of indirection, drop that mental model now. The minimum viable skill is one directory with one markdown file inside it, and that file's first job is to describe itself well enough that Claude knows when to reach for it.
Here is the shape of it.
summarize-changes/
└── SKILL.md
That runs. Claude Code picks it up, the description loads, and you can invoke it with /summarize-changes. The folder name becomes the command in Claude Code, which is worth knowing before you name anything cute.
What SKILL.md actually contains
The Claude skill file structure inside that one file is simple. SKILL.md has two parts: YAML frontmatter at the top between --- fences, and a markdown body below it. The frontmatter is the metadata. The body is the instructions Claude follows once the skill triggers. That two-part skill md structure, metadata then prose, is the same whether the skill is ten lines or a folder of bundled references.
Two frontmatter fields carry the load: name and description. The name is capped at 64 characters and must be lowercase letters, numbers, and hyphens only, no anthropic or claude as reserved words. The description is capped at 1024 characters, has to be non-empty, and should say both what the skill does and when to use it, written in third person. That second field is the one people underwrite. Claude reads the description to decide whether to load the skill at all, so a vague one ("helps with documents") gets your skill ignored. Writing a description that actually triggers is its own discipline, and I am not going to cram it in here. See how to write a SKILL.md description for that. If you want a copy-paste starting point for the whole file, grab the SKILL.md template.
A minimal frontmatter block:
---
name: summarize-changes
description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff.
---
Below that, the body. Keep it under 500 lines. Anthropic's own guidance is blunt about this: every line in the body is a recurring token cost once the skill loads, so write standing instructions, not a tutorial.
The optional folders, and when each one earns its place
Past the single file, you add directories as the skill grows. The Claude skill directory structure that Anthropic's docs show, most consistently, uses two conventions.
scripts/ holds executable helpers. Python, bash, whatever Claude runs via the shell. Why put code in scripts/ rather than ask Claude to write it inline every time? A pre-made script is deterministic, and its source never enters the context window. Claude runs python scripts/validate.py, reads the output, and the 200 lines of script body cost zero tokens. For a real walk through what goes in here, see Claude skill scripts.
The second convention is a folder for reference docs the model reads on demand. The Anthropic best-practices examples name this reference/ and fill it with files like finance.md or sales.md, one per domain, so a question about revenue pulls in only the finance file and leaves the rest on disk. You will also see references/ and an assets/ folder for templates and sample outputs in the wild, including in Anthropic's public skills repository. None of these names are enforced by the runtime. Only SKILL.md is special. The subdirectories are organizing conventions for your own sanity. The model finds bundled files because your SKILL.md links to them by relative path. A folder named reference/ has no magic the runtime respects; the link is what does the work.
That last point matters more than the exact spelling of the folder. A reference/api.md that nothing in SKILL.md points to just sits there. Claude never opens it. So link your supporting files from the body, one level deep, and name them so the filename tells Claude what is inside.
Why the Claude skill folder structure maps to progressive disclosure
The structure is not arbitrary. It mirrors how Claude loads a skill, in three tiers, and once you see the tiers the folder layout stops looking like a style choice.
Tier one is the frontmatter. At startup, Claude loads only the name and description from every installed skill, roughly 100 tokens each, into the system prompt. Nothing else. This is why you can install fifty skills without paying for fifty skills worth of context. Claude knows they exist and knows when each applies, and that is all.
Tier two is the SKILL.md body. It loads when the skill triggers. Your request matches that description, Claude reads the file off the filesystem with a bash call, and the body enters context then and not a moment before. That timing is the whole reason long reference material in a skill costs almost nothing until something needs it. Anthropic targets this tier under 5k tokens.
Tier three is everything bundled: the scripts, the reference markdown, the assets. These load only when Claude follows a link or runs a command. A skill can carry a dozen reference files and a folder of scripts, and on any given task Claude reads the one file the task needs and leaves the rest untouched on disk, consuming nothing. That is progressive disclosure, and it is the reason the folder is split the way it is. Metadata stays tiny so discovery stays cheap, the body holds the procedure, and the bundled files hold the depth you reach for once in a while. Because each tier loads on its own trigger, you pay for what a task actually touches. Pack a hundred reference files if you want. The ones a task never opens cost you nothing.
A fuller tree, with all three tiers visible:
pdf-processing/
├── SKILL.md # tier 2: body, loads when triggered
├── reference/
│ ├── forms.md # tier 3: read on demand
│ └── api.md # tier 3: read on demand
├── assets/
│ └── template.docx # tier 3: template, read on demand
└── scripts/
├── fill_form.py # tier 3: executed, source never loaded
└── validate.py # tier 3: executed, source never loaded
Where the folder lives once it is built
In Claude Code, a personal skill installs at ~/.claude/skills/<skill-name>/SKILL.md, available across all your projects. A project-scoped skill lives at .claude/skills/<skill-name>/SKILL.md and ships with the repo when you commit it. The folder name in that path becomes the slash command. That is the detail that trips people up most. claude.ai takes the same folder as a zip upload, and the Claude API takes it through the Skills endpoints, so one well-formed folder travels across surfaces. The Claude skill file format is the open Agent Skills standard, which is why the same skill md file structure runs in Claude Code, the Claude apps, and other tools that adopted it. Which tools honor which fields is a separate question with a real answer; the SKILL.md compatibility matrix lays out cross-tool support.
Building this tree by hand is fine once you know it cold. The frontmatter rules are strict, the description is fussy, and a typo in a folder reference is a silent failure you only notice when the skill quietly does nothing. Knack generates the entire folder for you from a short interview: valid name and description, the body, the right directory layout, the relative links wired up. You answer questions about the workflow you want to capture and get back a folder that drops straight into .claude/skills/ and runs.
One file is required. The rest is structure you add when the skill is big enough to need it, and the structure exists so Claude pays for depth only when a task reaches that deep.