TL;DR: A SKILL.md file is the core definition file for a Claude Code skill in the AEM skill engineering system. It sits inside a named folder in .claude/skills/ and tells Claude two things: when to use this skill (the description field in the YAML frontmatter), and what to do when it is used (the markdown body).

What Does a SKILL.md File Actually Contain?

A SKILL.md file has two parts: YAML frontmatter and a markdown body. The frontmatter, enclosed in triple dashes, holds the metadata Claude reads at session start, including the skill name and its trigger description. The body is plain markdown containing the instructions Claude follows when the skill runs.

The frontmatter section holds metadata fields that Claude reads at session start:

  • name: what the skill is called
  • description: when Claude should use this skill (one line; the combined description text is truncated at 1,536 characters in the session-start skill listing to control context costs, per Anthropic's Claude Code documentation)

The body is everything below the frontmatter. It is plain markdown: headings, lists, code blocks, prose instructions. This is where you tell Claude what to do when the skill is triggered.

Here is a minimal, working SKILL.md:

---
name: code-review
description: Use this skill when the user asks for a code review or requests feedback on a code file or pull request.
---

## What This Skill Does

Reviews code for correctness, readability, and potential bugs.

## Steps

1. Read the file or PR the user specifies.
2. Check for: bugs, unclear variable names, missing edge case handling.
3. Output a structured review with findings grouped by severity: Critical, Recommended, Optional.

That is a complete skill. Claude will discover it, trigger on code review requests, and follow those three steps.

Where Does the SKILL.md File Go?

SKILL.md files live inside named skill folders. The folder name becomes the skill identifier Claude uses for discovery: a folder named code-review creates the /code-review slash command automatically. Skills sit in .claude/skills/ at project level for single-project use, or in ~/.claude/skills/ for every project on your machine.

Project-level skills (available only in this project):

your-project/
  .claude/
    skills/
      code-review/
        SKILL.md
      blog-drafter/
        SKILL.md

User-level skills (available in every project on your machine):

~/.claude/
  skills/
    code-review/
      SKILL.md

The folder name matters. If your folder is named code-review, the slash command /code-review is automatically available, and Claude uses "code-review" as the skill identifier. Name it something meaningful and descriptive. Every Claude Code session loads a base payload of approximately 2,900 tokens before any skill content is added, which is why keeping skill descriptions concise matters from the first line. (Anthropic, Claude Code cost documentation, 2024) For more detail on where to put skill files, see Where Do I Put Skill Files in My Project?.

"The failure mode isn't that the model is bad at the task - it's that the task wasn't specified tightly enough. Almost every production failure traces back to an ambiguous instruction." - Simon Willison, creator of Datasette and llm CLI (2024)

What Is the Description Field and Why Does It Matter So Much?

The description field is the trigger condition. Claude reads all skill descriptions at session start and uses them to determine which skill to invoke for a given request. A vague description causes under-triggering; a broad one causes false positives. It must stay under 1,024 characters and start with an imperative phrase like "Use this skill when."

Three rules for a working description:

  1. Start with an imperative: "Use this skill when..." or "Apply this skill to..."
  2. Name the specific trigger conditions in plain terms
  3. Stay under 1,024 characters and keep it on a single line

Write the description wrong and the skill stops working, even if every other part of SKILL.md is correct.

Testing across 650 activation trials showed imperative descriptions achieve 100% activation on relevant prompts, while passive descriptions ("This skill is for...") sit at 77%. (AEM skill engineering research, 2026) That gap is the difference between a skill that works reliably and a skill that works when you invoke it manually and fails when you expect auto-triggering. Analysis of 2,500+ AI agent configuration files found the same pattern: vague descriptions fail, while descriptions that name exact trigger conditions and constraints work. (GitHub Blog, 2025)

"The single biggest predictor of whether an agent works reliably is whether the instructions are written as a closed spec, not an open suggestion." - Boris Cherny, TypeScript compiler team, Anthropic (2024)

The description field is covered in depth at The SKILL.md Description Field: The One Line That Makes or Breaks Your Skill.

What Goes in the Body of a SKILL.md File?

The body is instructions. Write it as you would write a clear procedure for a capable person who is new to the task: specific enough to follow reliably, not so specific that every variation requires a new file. Claude reads it top to bottom.

The most common body sections:

  • What This Skill Does (or equivalent): One paragraph explaining the skill's purpose and scope. What it produces. What it does not produce.
  • Steps (or Process or Methodology): Numbered steps Claude follows in order. Each step is an action. "Read the file the user specifies" is a step. "Think about the code" is not.
  • Rules (optional): Constraints that apply across all steps. "Never modify files outside the directory the user specified" belongs here, not in a step.
  • Output format (optional): How the final output should be structured. If you need a specific format consistently, define it here.

"When you give a model an explicit output format with examples, consistency goes from ~60% to over 95% in our benchmarks." - Addy Osmani, Engineering Director, Google Chrome (2024)

The total body should stay under 500 lines. Beyond that, Claude's attention dilutes and instruction adherence drops. Anthropic's official Claude Code documentation sets this explicitly as the production guideline: "Keep SKILL.md under 500 lines. Move detailed reference material to separate files." (Anthropic, Claude Code docs, 2024) Research on long-context instruction following confirms the underlying issue: models exhibit 30% or greater accuracy drops when critical instructions appear in the middle of large context windows, rather than near the start. (Chroma Research, "Context Rot," 2025) A 2026 ETH Zurich study on repository context files (ArXiv 2602.11988) found that oversized agent instruction files increase inference reasoning tokens by 14-22% without improving task success rates, and in some cases reduce them. If your skill needs more than 500 lines, the excess content belongs in reference files that Claude loads from the same folder on demand.

For a detailed breakdown of every section and what goes in it, see What Goes in a SKILL.md File?.

Can a Skill Have Files Beyond SKILL.md?

Yes. A skill folder can contain reference files for domain knowledge, asset files for templates and examples, and an evals.json file for test cases. SKILL.md remains the required entry point, but production-grade skills for complex workflows use all four components. The folder structure below shows the complete layout:

.claude/skills/your-skill-name/
  SKILL.md          ← required
  references/       ← optional: domain knowledge Claude loads on demand
    style-guide.md
    api-reference.md
  assets/           ← optional: templates, example outputs, scripts
    output-template.md
    approved-examples/
      example-1.md
  evals.json        ← optional: test cases for the skill

Reference files let you keep detailed domain knowledge out of SKILL.md without losing it. SKILL.md instructs Claude to load specific reference files at specific steps, keeping the main file under the 500-line limit while giving Claude access to everything it needs. The official Claude Code docs describe this directly: a skill's body "loads only when it's used, so long reference material costs almost nothing until you need it." (Anthropic, Claude Code docs, 2024)

A skill with only SKILL.md works fine for simple tasks. Production-grade skills for complex workflows use the full folder structure. See What Is a Claude Code Skill? for more on how these pieces fit together.

What Happens When Claude Reads a SKILL.md File?

Claude reads skill metadata at session start. Every description field across all skills in your .claude/skills/ folder loads into Claude's context as metadata. Claude uses this metadata layer to match user requests to skills without reading the full skill body for every session.

When a match is found, Claude loads the full SKILL.md body and follows the instructions. Reference files load only when a step in the body explicitly instructs Claude to read them.

This three-layer loading is what keeps large skill libraries performant. You can have 30 skills without paying the full token cost for all 30 at session start. The design matters because loading all skill bodies simultaneously would place critical instructions in the middle of a long context, where research shows models lose track of them at a rate that makes mid-context policy placement unreliable for production. (Nelson Liu et al., Stanford NLP Group, "Lost in the Middle," ArXiv 2307.03172, 2023) For the full explanation of how this works, see What Is Claude Code and How Does It Work?.

Frequently Asked Questions

SKILL.md files follow strict naming and structure rules. The filename is case-sensitive, one file per folder, and there is no hard size limit, though 500 lines is the practical ceiling before instruction adherence degrades. Markdown formatting is fully supported. Section order matters because Claude reads from top to bottom.

Does SKILL.md have to be named exactly "SKILL.md"?

Yes. The filename is case-sensitive on most systems and must be SKILL.md exactly. Claude Code looks for this specific filename when scanning skill folders. A file named skill.md or Skill.md will not be recognized as a skill definition file.

Can I have more than one SKILL.md in a skill folder?

No. Each skill folder has exactly one SKILL.md. If you need a second skill, create a second folder with its own SKILL.md. The folder structure is one folder per skill, one SKILL.md per folder.

What is the maximum size a SKILL.md file can be?

There is no hard technical limit on file size. The practical limit is 500 lines because Claude's ability to follow instructions from long skill files degrades above that point. Instruction adherence at 200 lines is better than at 500 lines. If your skill needs more than 500 lines of instructions, refactor: move domain knowledge into reference files, break the skill into two separate skills, or remove instructions that duplicate what Claude already knows.

Can I use markdown formatting like bold, tables, and code blocks in SKILL.md?

Yes. SKILL.md is a markdown file and Claude reads markdown formatting. Bold text for emphasis, numbered lists for steps, tables for structured comparisons, and code blocks for examples are all valid and useful. Claude does not render the markdown visually, but it processes the semantic structure. A numbered list reads to Claude as an ordered sequence, which is exactly the right format for step-by-step instructions.

Does the order of sections in SKILL.md affect how Claude follows instructions?

Yes, in practice. Claude reads from top to bottom. Instructions near the top of the body receive more reliable adherence than instructions buried near the bottom of a long file. Critical constraints, like "never write to files outside this directory," belong near the top or explicitly repeated in the relevant step. Do not put your most important rule in paragraph 12 of a 15-paragraph body.

Last updated: 2026-04-30