Agent Skill Format

Contract

Enforces the Anthropic Claude Agent Skill SKILL.md spec: the frontmatter holds exactly two keys (name, then description), the description carries a literal Use when trigger, and the body opens with an H1. Apply whenever you author or edit a SKILL.md file.

Rules

1. File name and location. The file is named SKILL.md — uppercase SKILL,

uppercase .md extension lowercase — inside a directory named for the skill. The skill directory sits directly under the skills root (~/.claude/skills/<skill>/ or <project>/.claude/skills/<skill>/). No nested subdirectories or namespaces in the skill path.

1. Frontmatter delimiters. The file begins with a YAML frontmatter block: a line

containing only --- at the very top of the file (byte 0 — nothing before it, not a title, not a blank line, not a comment), the keys, then a closing line containing only ---.

1. Exactly two keys, in order. The frontmatter contains name first, then

description. Nothing else.

1. No other keys. Claude reads only name and description; every other key is

ignored, so omit it. Forbidden: version, author, tags, license, category, date, created, updated, maintainer, difficulty, model, allowed-tools. If you feel the urge to add one of these, the information belongs in the body, not the frontmatter.

1. name field. A short human-readable string, 64 characters or fewer. Use a real

descriptive name (Title Case reads well), never a placeholder like skill-1, untitled, my-skill, or TODO.

1. description field. 1024 characters or fewer, and it MUST state two things in

order: (a) WHAT the skill does, then (b) WHEN to use it. Express the "when" as an explicit clause beginning with the literal words Use when, naming concrete trigger situations. Front-load the keywords a matcher would search for.

1. YAML quoting. If a value contains a YAML-significant character — a colon :,

a leading [, {, *, &, #, @, or a quote — wrap the whole value in double quotes. A description with a Use when ...: or any word: word pattern must be quoted or YAML mis-parses it.

1. Body opening. Immediately after the closing ---, the body's first line is a

single level-1 Markdown heading (# ) naming the skill. No prose, blank lines aside, before that heading; no ## or ### as the first heading.

Worked examples

Rule 3+4 — exactly two keys, no extras. A request to author a changelog skill.

BEFORE (base default — adds metadata keys):
---
name: changelog-generator
description: Generates a changelog from git history.
version: 1.0.0
author: jane
tags: [git, docs]
license: MIT
---

AFTER (conforming — two keys only):
---
name: changelog-generator
description: "Generate a Keep a Changelog file from git commit history. Use when preparing a release or summarizing changes since the last tag."
---

Rule 6 — description must embed Use when. A request to author a CSV-to-Markdown skill.

BEFORE (base default — what only, no trigger):
description: A tool that converts CSV files into Markdown tables.

AFTER (conforming — what, then literal `Use when`):
description: "Convert CSV files into GitHub-flavored Markdown tables. Use when pasting tabular data into docs, rendering query output, or building a README comparison table."

Rule 2 — frontmatter at byte 0. A request that the base prefaces with a title.

BEFORE (base default — H1 before frontmatter):
# Dockerfile Linter

---
name: dockerfile-linter
description: "..."
---

AFTER (conforming — frontmatter first, H1 in the body):
---
name: dockerfile-linter
description: "Lint and optimize Dockerfiles. Use when reviewing image builds or shrinking layers."
---

# Dockerfile Linter

Rule 5 — real name, not a placeholder.

BEFORE: name: skill-1
AFTER:  name: regex-builder

Rule 7 — quote values with a colon.

BEFORE (unquoted colon — YAML parse error):
description: Build cron expressions: minute hour day month weekday.

AFTER (quoted):
description: "Build and explain cron expressions (minute, hour, day, month, weekday). Use when scheduling a job or decoding an existing crontab line."

Rule 8 — body opens with a single H1.

BEFORE (base default — prose paragraph first):
---
name: pr-describer
description: "..."
---

This skill drafts pull request descriptions from a diff.
## Usage

AFTER (conforming — H1 first):
---
name: pr-describer
description: "..."
---

# PR Describer

This skill drafts pull request descriptions from a diff.

Edge cases and exceptions

• You genuinely want to record a version or author. Put it in the body (a ## Metadata

section or prose), never in the frontmatter. The two-key rule has no exceptions.

• The description has a colon you can't avoid (e.g. JSON:API). Quote the whole

value: description: "Build JSON:API endpoints. Use when ...".

• Use when must be the literal phrase. When you ..., Use this when ..., or

Useful when ... do not satisfy the trigger contract — the matcher keys on the exact string Use when. Lower-cased use when mid-sentence is acceptable, but lead the trigger clause with Use when.

• Name longer than 64 chars. Trim to the essential noun phrase; the full explanation

lives in description, which has 1024 chars.

• Single-line vs. multi-line description. Either is fine as long as it is valid YAML;

a single quoted line is simplest and avoids block-scalar pitfalls.

• A category/tags key the surrounding catalog requires. That is the registry's

packaging metadata, separate from the SKILL.md you author for Claude — inside the authored SKILL.md frontmatter, still only name and description.

Do / Don't

• Do keep frontmatter to exactly name and description. Don't add

version, author, tags, license, category, or date.

• Do lead the trigger with the literal Use when. Don't ship a description

that only says what the skill does.

• Do start the file with --- at byte 0. Don't put a title, comment, or blank

line before the frontmatter.

• Do open the body with one # heading. Don't start with prose or a ##.
• Do quote any value containing a colon. Don't leave word: word unquoted.
• Do give name a real descriptive value. Don't ship skill-1 / my-skill.

Common mistakes (the base's wrong defaults)

• Decorating the frontmatter with version/author/tags/license because that looks

like a "complete" manifest — all ignored, all forbidden.

• Writing a description that states only WHAT, with no Use when trigger.
• Prefacing the file with an H1 title or a sentence, pushing the frontmatter off byte 0.
• Using a placeholder name (skill-1, untitled).
• Leaving a colon in the description unquoted, breaking YAML parsing.
• Reordering to description before name.

Quick checklist

• ] File is SKILL.md, in a directory named for the skill.
• ] Line 1 is exactly ---; nothing precedes it.
• ] Frontmatter keys are exactly name then description — nothing else.
• ] name ≤ 64 chars, descriptive, not a placeholder.
• ] description ≤ 1024 chars, states WHAT then a literal Use when trigger.
• ] Values with a colon are quoted.
• ] First body line is a single # heading naming the skill.