---
name: agent-skill-format
source: https://app.decimal.ai/s/agent-skill-format@1/SKILL.md
source_sha256: 3499f2159cdf
---

# 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.
2. **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 `---`.
3. **Exactly two keys, in order.** The frontmatter contains `name` first, then
   `description`. Nothing else.
4. **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.
5. **`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`.
6. **`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.
7. **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.
8. **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.