What is a SKILL.md file? The Anthropic Skill format, explained.

A Skill is a Markdown file with YAML frontmatter that changes how Claude behaves on a specific task. The frontmatter declares metadata — name, description, allowed tools — and the body holds the instructions Claude reads as part of its system prompt. The same SKILL.md works across Claude Code, Claude.ai, and the broader Anthropic ecosystem, which is why the format matters: one file, many surfaces. You can write one in a text editor, or you can build one in your browser with Skillbench and skip the YAML entirely.

Anatomy of a SKILL.md file

Every SKILL.md has two parts: a YAML frontmatter block fenced by --- on the first and last lines, followed by Markdown instructions. Four frontmatter fields carry weight:

name — a kebab-case identifier, lowercase, no spaces. This is how Claude refers to the Skill internally and how it shows up in /skills listings. Example: code-reviewer, email-triager.
description — one sentence that tells Claude when to invoke this Skill. Not what it does — when. Claude reads the description across all installed Skills and picks the one whose description best matches the current user request. Write it as a trigger condition: "Use when the user asks for a code review on a diff."
allowed-tools — an array of tools the Skill is permitted to call. Typical values: list_files, read_file, grep, web_search, code_execution. An empty array means the Skill runs without tool access — pure prompt logic. Tool permissions in Claude Code follow the same Off / Ask / Yolo model Skillbench mirrors in its sandbox.
tags — optional categorization, useful for filtering when you have a lot of Skills. Free-form strings.

The body below the frontmatter is plain Markdown. No special escaping. Headings, lists, code fences — anything Claude can read in a normal message. Most Skills are 5–50 lines of body content; longer Skills tend to drift and become harder to A/B test against a baseline.

A minimal SKILL.md example

The shortest viable SKILL.md is about ten lines. This one writes haikus:

---
name: haiku-writer
description: Use when the user asks for a haiku. Returns exactly 5-7-5 syllables.
allowed-tools: []
tags: [poetry]
---

Write a haiku in exactly 5-7-5 syllables. Output the haiku and nothing else.
No preamble. No explanation.

The four frontmatter fields are present, the body is two sentences, and the constraints (5-7-5, no preamble) are stated as imperatives. That's the entire Skill. Claude will load this as part of its system prompt and, when the user says "give me a haiku about debugging," produce three lines with the right syllable counts and nothing else.

A realistic example: a code reviewer

Most production Skills sit between 20 and 40 body lines. Here's a trimmed version of the code-reviewer Skill in the Skillbench gallery:

---
name: code-reviewer
description: Use when reviewing a pull request diff. Returns line-cited findings and a ship/no-ship verdict.
allowed-tools: [read_file, grep]
tags: [engineering, security, review]
---

You are a senior engineer reviewing a diff. Be specific. Cite line numbers.

For each issue, output one line in this format:
  L. <line> — <one-sentence problem>, **<category>**.

Categories: bug, security, perf, style, test-gap.

After the line-by-line review, output:
  **Verdict:** ship | no-ship.

Rules:
- Do not restate the diff back to the user.
- Do not say "looks good overall." Either ship or no-ship.
- If you find a security issue, the verdict must be no-ship.
- If there are no tests for new behavior, flag a test-gap.
- Be terse. The reviewer is busy.

Each piece earns its place. The description tells Claude this Skill is for diff review specifically — not architecture critique, not refactor suggestions. allowed-tools: [read_file, grep] lets the Skill open referenced files and grep for usages without granting broader access. The body locks the output format ("L. line — problem, category") so two runs on the same diff produce structurally identical reviews, which is the property that makes Skills worth measuring.

How to build a SKILL.md without writing YAML

Two paths exist. The first is Anthropic's official skill-creator plugin, installable into Claude Code via claude plugin install skill-creator. It runs as a CLI, prompts you for the same fields, and writes a SKILL.md to disk. Good if you're already in a terminal and want zero browser dependency.

The second is Skillbench: a browser form for the same fields, plus a live preview of the generated Markdown and a sandbox that runs the Skill against the real Anthropic API the moment you save. You bring your own API key, nothing is stored on a server, and the resulting SKILL.md downloads as a file you can commit to your repo. Open the builder and the first Skill takes about two minutes to author.

Where do SKILL.md files live?

Placement depends on the runtime:

Claude Code: user-level Skills go in ~/.claude/skills/<skill-name>/SKILL.md. Project-level Skills live in .claude/skills/<skill-name>/SKILL.md at the repo root and version with the codebase.
Claude.ai: uploaded through the UI — go to Settings → Skills → Upload, point at your SKILL.md, done.
Custom agents: anywhere your agent loads files from. The format is portable — read the Markdown, parse the frontmatter, prepend the body to the system prompt.

The file extension is always .md (lowercase). The filename inside the Skill directory is always SKILL.md (uppercase). The folder name should match the name field. Skillbench writes files with all three conventions baked in so you don't have to remember.

Build one in your browser → Browse 6 starter Skills