How to Structure a SKILL.md File
Updated September 17, 2026
The structure of a SKILL.md file follows one idea: Claude should load as little as possible until it needs more. The specification calls this progressive disclosure, and it shapes everything from the order of sections to which files sit next to SKILL.md in the folder. This guide gives a section order that works, the folder layout, and the rules for splitting a skill that has grown.
The short answer
- Frontmatter first: name and description, always loaded.
- A short body: what to do, in order, with one example and the edge cases. Under 500 lines.
- Supporting files beside it: references/ for documents Claude reads, scripts/ for code it runs, assets/ for templates it copies.
- Links one level deep: SKILL.md points straight at each file. No chains.
The three loading levels
Every structural decision follows from when each part of a skill enters Claude's context:
| Level | What | When loaded | Budget |
|---|---|---|---|
| 1. Metadata | name and description | At startup, for every installed skill | About 100 tokens each |
| 2. Instructions | The SKILL.md body | When the skill is triggered or invoked | Under 5,000 tokens recommended; under 500 lines |
| 3. Resources | Files in the skill folder | Only when the body points Claude at one | None until read; script code never enters context, only its output |
Level 3 is what makes a skill scalable. Anthropic's documentation notes there is no practical limit on bundled content, because a reference file costs nothing until Claude reads it. The body's job is therefore to be a good table of contents: do the common case inline, and point at files for the rest.
A section order that works
The specification recommends three kinds of content in the body: step-by-step instructions, examples of inputs and outputs, and common edge cases. An order that reflects how Claude reads:
- Quick start or steps. The default path, numbered, with the exact command or template where one exists. This is what Claude needs on most invocations.
- Example. One input and the output you want for it. Add a second only if the first leaves a real ambiguity.
- Rules and edge cases. The things that go wrong and what to do about each. Firm wording for the ones that matter.
- Pointers to deeper material. “For form filling, see references/FORMS.md.” One line each, with the path.
Two conventions from Anthropic's guide are worth adopting. Give Claude a checklist it can copy into its reply for multi-step work, so no step is silently skipped. And when a task branches, write the branch explicitly: “Creating new content? Follow the creation workflow. Editing existing content? Follow the editing workflow.” If a branch is long, move it to its own file.
The folder layout
| Path | Holds | How Claude uses it |
|---|---|---|
| SKILL.md | Frontmatter and the body | Required; read when triggered |
| references/ | Documentation: REFERENCE.md, FORMS.md, domain files like finance.md | Read on demand; keep each file focused |
| scripts/ | Executable code: Python, Bash, JavaScript | Run through Bash; only output enters context |
| assets/ | Templates, images, schemas, lookup tables | Copied or consulted as the task needs |
The folder names are conventions from the specification, not requirements, and any other files or directories are allowed. Three rules do apply. Reference files with relative paths from the skill root using forward slashes, even on Windows. Name files for what they contain (form_validation_rules.md, not doc2.md), since Claude navigates the folder like a filesystem. And when the body mentions a script, say whether Claude should run it or read it as reference; running is usually what you want.
Splitting when the body grows
When SKILL.md approaches 500 lines, split. Anthropic's guide gives three patterns. A high-level guide with references keeps the quick start inline and links a file each for forms, API reference, and examples. Domain-specific organisation gives each area its own file, so a question about sales metrics loads sales.md and not finance.md. Conditional details shows the basic case and links the advanced one: simple edits inline, tracked changes in REDLINING.md.
Whichever pattern, keep references one level deep. Anthropic warns that when a referenced file references another, Claude may preview the second with a partial read and miss information. Every file should be linked directly from SKILL.md. For a reference file longer than about 100 lines, put a table of contents at the top so a partial read still shows what the file covers.
A worked layout
A skill for producing monthly reports from a data warehouse might look like this. SKILL.md, about 80 lines: the frontmatter, five numbered steps, the report template, three rules about filtering, and four pointer lines. references/finance.md, references/sales.md, references/product.md: table names and field definitions for each area, each with a contents list. scripts/validate_query.py: checks a query before it runs, with verbose error messages. assets/report_template.md: the output skeleton. Claude reads the body on every invocation, one reference file per question, and never the script's source.
For a first draft of the SKILL.md part, the SKILL.md Generator produces the frontmatter and a body in roughly this order from a description, and checks the frontmatter as you edit. The folder around it, and the judgment about what to move into it, are yours.
Common questions
- How long should SKILL.md be?
- Under 500 lines, and under about 5,000 tokens for the body, per the specification and Anthropic's guide. Many good skills are far shorter. Move detail into reference files rather than trimming instructions that matter.
- Are the scripts, references, and assets folders required?
- No. Only SKILL.md is required. The three folder names are the specification's recommended conventions, and a skill may contain any other files and directories.
- Should reference files link to each other?
- Avoid it. Anthropic recommends keeping references one level deep from SKILL.md, because Claude may only partially read a file reached through another file. Link every file directly from SKILL.md.
- Does a script's code count against the context window?
- No. When Claude runs a bundled script through Bash, only the script's output enters the context. That is why pre-written scripts are more efficient than asking Claude to generate the same code each time.
- What goes in the body versus a reference file?
- The body holds what most invocations need: the steps, one example, the rules. A reference file holds what only some invocations need: a full API reference, a schema, an advanced workflow. If Claude reads the same reference file on every invocation, move that content into the body.
Try it yourself
These live under Developer tools, alongside the rest of the claude skills & skill.md guides on the guides page.