title: "What Goes in a SKILL.md File?" description: "SKILL.md has two parts: YAML frontmatter and a body (process steps, output contract, rules). Learn every section, what belongs where, and what to offload." pubDate: "2026-04-13" category: skills tags: ["claude-code-skills", "skillmd-anatomy", "beginner"] cluster: 5 cluster_name: "SKILL.md File Anatomy" difficulty: beginner source_question: "What goes in a SKILL.md file?" source_ref: "5.Beginner.1" word_count: 1520 status: draft reviewed: false schema_types: ["Article", "FAQPage"]

What Goes in a SKILL.md File?

Quick answer: A SKILL.md file has two required parts: YAML frontmatter between --- markers (at minimum, name and description fields) and a body containing numbered process steps and an output contract. Optional additions include a "when not to use" section, rules and constraints, and a self-improvement block. Domain knowledge that would bloat the file goes in references/ subdirectory files instead.

What are the required frontmatter fields in SKILL.md?

Every functional SKILL.md requires exactly two frontmatter fields: name (the skill identifier used for direct invocation) and description (the trigger sentence Claude reads to decide when to activate the skill). All other frontmatter fields are optional and do not affect whether the skill loads or runs.

The frontmatter block is the YAML section between the opening and closing --- markers. Claude Code reads this at startup to discover the skill. Two fields are required for any functional skill.

---
name: skill-name
description: "Use this skill when [trigger condition]. Do NOT use for [anti-trigger]. [Core action]."
---

The name field identifies the skill and enables direct invocation with /skill-name. It must match the folder name in .claude/skills/. Use lowercase with hyphens.

The description field controls when Claude activates the skill. It must stay on a single line, multi-line descriptions break YAML parsing and the skill fails silently on every subsequent session. The character limit is 1,024 (Claude Code specification, 2026).

The description is the most important field in the entire file. A weak description produces a skill that triggers unreliably. AEM testing across 650 activation trials found that imperative descriptions achieve 100% activation rates; passive descriptions sit at 77% (AEM internal testing, 2026). Write it as an imperative: "Use this skill when..." not "A skill for..."

"The most valuable content in any skill is the Gotchas section — common mistakes. It should be based on real problems Claude encounters when using your skill." — Tort Mario, Engineer, Anthropic (April 2026, https://medium.com/@tort_mario/skills-for-claude-code-the-ultimate-guide-from-an-anthropic-engineer-bcd66faaa2d6)

Additional optional frontmatter fields exist (disable-model-invocation, tags, version) but do not affect basic functionality. Start with name and description. Add optional fields when you have a specific reason to.

What belongs in the body of SKILL.md?

The body of SKILL.md contains four components in order: a one-to-two sentence description of what the skill does, an optional list of trigger and anti-trigger conditions, numbered process steps with tool names and failure handling, and an output contract that states exactly what the skill produces and explicitly what it does not produce.

The body is everything below the closing --- of the frontmatter. The recommended section order:

1. What this skill does (required) One to two sentences. Not a paragraph. State the task the skill performs and the output it produces.

## What this skill does
Generates a Conventional Commits-format commit message from staged changes.

2. When to use it / When NOT to use it (recommended) A short list of trigger conditions and anti-triggers. This reinforces the description and gives Claude additional context when the trigger match is ambiguous.

3. Process steps (required) Numbered steps in execution order. Each step names a tool (if one is required), specifies the input, and handles failure cases. This is the operational core of the skill.

## Process

Step 1: Use the Bash tool to run `git diff --staged`. Read the output.
Step 2: Identify the change type from the diff (feat, fix, refactor, docs, chore).
Step 3: Output a commit message: Line 1 is `type(scope): description under 72 chars`.
  If no staged changes exist, stop and tell the user there is nothing to commit.

4. Output contract (required) Two lines minimum: what the skill produces, and what it explicitly does NOT produce. Without a "does NOT produce" list, Claude decides what to include. The output varies across sessions.

## Output contract
Produces: a single git commit message, nothing else.
Does NOT produce: PR descriptions, changelogs, code suggestions, or review comments.

5. Rules and constraints (recommended) Hard constraints the skill must follow. Numbered list. Use "Always" and "Never" language, not "should" or "try to."

6. Self-improvement section (optional) A block that tells Claude how to capture feedback for future skill versions. Useful for skills that go through regular review cycles.

What should NOT go in SKILL.md?

Domain knowledge, long examples, and scripts do not belong in SKILL.md. Domain knowledge (API docs, style guides, lookup tables) goes in references/ files loaded on demand. Long output examples go in assets/approved-examples/. Deterministic scripts go in assets/. Keeping these separate means SKILL.md stays under 150 lines and loads without token overhead every session.

The 500-line limit is not a suggestion. It is the point at which a skill file stops being instructions and starts being documentation nobody reads, and at which startup token overhead affects Claude's ability to select the right skill in a library (Claude Code specification, 2026).

Three categories of content belong outside SKILL.md:

Domain knowledge. API documentation, style guides, taxonomy references, lookup tables, anything Claude needs to know but not to decide. Move this to a references/ file and add a step that loads it: "Use the Read tool to load references/style-guide.md before generating output."

Long examples. If you need approved output examples to calibrate Claude's style, create an assets/approved-examples/ folder. Reference it in the step: "Match the tone and format of the examples in assets/approved-examples/."

Scripts. Deterministic logic that Claude should not vary belongs in a Python or bash script in assets/. Reference and execute it from a step. Do not embed 50-line scripts in SKILL.md.

Each skill adds approximately 100 tokens of metadata overhead at startup (Claude Code specification, 2026). A 600-line SKILL.md costs more tokens than a 150-line SKILL.md with two reference files, and the reference files only load when explicitly read in a step.

How long should my SKILL.md actually be?

For most skills, 80 to 150 lines is the right length: long enough to cover one task completely, short enough for a reviewer to read in five minutes and for Claude to load without crowding its startup token budget. Simple single-task skills can run under 80 lines. Anything over 150 lines is a signal that the skill covers multiple tasks or contains content that belongs in reference files.

For most skills, 80 to 150 lines is the target range. Under 80 lines is achievable for simple, single-task skills. Over 150 lines is a signal the skill is doing too much.

The 500-line ceiling exists in the specification, but treating 500 as the target is a mistake (Claude Code specification, 2026). A 500-line skill file competes for startup token budget, reduces discovery accuracy across the library, and becomes hard for any human reviewer to audit quickly.

Three-part test for right-sizing:

  1. Can a new team member read it in 5 minutes? If not, it is too long.
  2. Does it cover exactly one named task? If it covers two tasks with an "OR" in the description, it is two skills.
  3. Could any section move to a reference file without loss of function? If yes, move it.

A 150-line skill with two reference files is almost always better than a 350-line skill. The reference files load on demand. The 350 lines of SKILL.md load every session.

What is the one-level-deep rule for reference files?

Reference files in references/ may only be one level deep: a SKILL.md step reads a reference file directly; that reference file cannot point to or load another reference file. Chaining references creates unpredictable loading order and context overflow risks, so the architecture enforces a flat structure where every reference file is self-contained and explicitly named in a process step.

Reference files in references/ can be read by the skill. They cannot point to other reference files. The one-level-deep rule exists because reference chains create unpredictable loading behavior: if style-guide.md points to brand-voice.md which points to tone-examples.md, it is unclear which files load, in what order, and whether all of them fit in context.

Flat reference structure produces predictable behavior. Each reference file is independent, self-contained, and loaded explicitly by a named step in the process (Claude Code architecture, 2026).

If you find yourself wanting reference files to link to other reference files, the domain knowledge is not yet structured. Reorganize it into self-contained documents before adding them to the skill.

For the complete overview of SKILL.md anatomy in context of the full skill engineering process, see The Complete Guide to Building Claude Code Skills in 2026.

For the detailed guide to writing the description field correctly, see What does the description field do in a Claude Code skill?.

For how to write process steps that Claude follows consistently, see How do I write step-by-step instructions for a Claude Code skill?.

Frequently Asked Questions

What's the minimum viable SKILL.md file that actually works?

The minimum viable SKILL.md is a frontmatter block with name and description fields plus one to three numbered process steps in the body — no output contract, no reference files, no rules section. The skill will trigger and execute a process, but it will not produce consistent output across users or handle edge cases, because those require an explicit output contract and constraint rules.

A frontmatter block with name and description fields, plus 1-3 numbered process steps. No output contract, no reference files, no rules section. The skill will trigger and follow a process. It will not produce consistent output across users, and it will break on edge cases. Minimum viable means it runs, not that it is production-ready.

Can I use markdown tables and code blocks inside SKILL.md?

Yes — markdown tables, code blocks (fenced with triple backticks), and headers (## and ###) all parse correctly and are read by Claude as structured content. Code blocks are the preferred way to show exact output formats in the output contract. Tables are useful for short lookup content, but move any table longer than 20 rows to a references/ file to avoid bloating the skill.

Markdown tables, code blocks, and headers all render and are read by Claude. Code blocks are useful for showing exact output formats in the output contract. Tables work for lookup content, though if the table is more than 20 rows, a reference file is a better home for it. Headers (##, ###) help Claude parse section boundaries in the body.

My SKILL.md is 800 lines. How do I refactor it?

Refactor an 800-line SKILL.md in three steps: move all domain knowledge blocks to reference files, split the skill if it covers more than one distinct task, and remove any process steps that duplicate Claude's built-in behavior. Applied sequentially, each step alone typically reduces line count by 30 to 40 percent (AEM internal refactoring analysis, 2026), bringing an 800-line file to under 200 lines in most cases.

Three steps. First, move every block of domain knowledge (examples, lookup tables, style rules, taxonomy) to reference files. Second, check if the skill covers more than one distinct task, if so, split it. Third, check if any process steps duplicate logic already built into Claude. Each fix alone typically reduces line count by 30 to 40 percent (AEM internal refactoring analysis, 2026).

Should I use first person or third person in SKILL.md instructions?

Second person imperative for process steps: "Read the file," "Ask the user," "Output the result." Third person for descriptions of what the skill does: "This skill generates..." First person ("I should...") is ambiguous inside Claude's context window and produces less reliable instruction adherence.

What happens if I put SKILL.md in the wrong folder?

If SKILL.md is not at .claude/skills/[skill-name]/SKILL.md or ~/.claude/skills/[skill-name]/SKILL.md, the skill will not load and Claude will not report an error — the skill simply does not appear in the discovery index. There is no warning, no fallback, and no partial activation; the file is silently ignored as if it does not exist.

The skill does not load. Claude Code scans .claude/skills/[skill-name]/SKILL.md and ~/.claude/skills/[skill-name]/SKILL.md. A file at .claude/SKILL.md, .claude/skills/SKILL.md (without a named subdirectory), or anywhere else in the project tree is not discovered. Claude will not error, the skill simply does not exist in the discovery index.

Last updated: 2026-04-13