Claude Code Skill Spec

Contract

Enforces the exact on-disk shape of a Claude Code Agent Skill. Apply whenever you are asked to create, scaffold, generate, or author a Claude Code / Agent Skill — the output must match this fixed format, not an invented manifest shape.

Rules

The format is arbitrary and fixed. Reproduce every part of it.

1. Location. Put the skill at .claude/skills/<kebab-name>/SKILL.md. The <kebab-name>

directory sits DIRECTLY under .claude/skills/.

• <kebab-name> is lower-case kebab-case: changelog-generator, not ChangelogGenerator or

changelog_generator.

• There is exactly one directory level between .claude/skills/ and SKILL.md. No nested

namespaces, no category/skill/ grouping, no skill/v1/ versioning under the name.

• Personal (user-wide) skills live at ~/.claude/skills/<name>/; project skills at

<repo-root>/.claude/skills/<name>/. Same <name>/SKILL.md shape in both.

1. Filename. The main file is named EXACTLY SKILL.md — upper-case SKILL, lower-case .md.

Not skill.md, Skill.md, skill.yaml, manifest.json, manifest.yaml, index.md, or README.md. (A README.md may exist alongside as human docs, but it is never the skill file.)

1. Frontmatter block. SKILL.md MUST begin with a YAML frontmatter block: the very first line

is --- alone, then the fields, then a closing line of --- alone. Nothing precedes the opening --- (no blank line, no comment, no H1).

1. Frontmatter keys — exactly two. The frontmatter contains EXACTLY the keys name and

description, and no others.

• Forbidden keys (Claude ignores them; including any is wrong): version, author, tags,

tools, license, category, model, created, updated, maintainer, difficulty, allowed-directories, or anything else. Only name and description.

1. name. A short, human-friendly title string, at most 64 characters. Title Case is

conventional (Changelog Generator). This is the display name and differs from the kebab-case directory: dir changelog-generator, name: Changelog Generator.

1. description. At most 1024 characters, and it MUST state BOTH what the skill does AND when to

use it. Include an explicit trigger clause, conventionally phrased starting with Use when …. Front-load concrete trigger keywords so Claude matches it. A description with no "when" clause is invalid even if grammatical.

1. Body opening. Immediately after the closing ---, the body's first heading is a single H1:

# <Name>. Not ##, not prose before the heading.

1. Lean body / progressive disclosure. Keep SKILL.md lean. Long reference material, templates,

and scripts go in separate files the body links to (scripts/, resources/, references/ under the skill dir) — not inlined as walls of text. The frontmatter + body are what Claude reads first; linked files load on demand.

Worked examples

One BEFORE (a plausible-looking wrong default) → AFTER (conforming) per rule.

Rule 1 — location & nesting

BEFORE — nested namespace folders and a grouping directory:

.claude/skills/git/changelog/generator/SKILL.md

AFTER — one kebab-case directory directly under .claude/skills/:

.claude/skills/changelog-generator/SKILL.md

Rule 2 — filename

BEFORE — lower-case / wrong extension:

.claude/skills/changelog-generator/skill.md
.claude/skills/changelog-generator/manifest.yaml

AFTER — exact casing:

.claude/skills/changelog-generator/SKILL.md

Rule 3 — frontmatter is YAML fenced by ---, not JSON

BEFORE — a package.json-style manifest:

json
{ "name": "Changelog Generator", "description": "Generates changelogs." }

AFTER — YAML frontmatter at the top of SKILL.md:

markdown
---
name: Changelog Generator
description: "Generate a changelog from git history. Use when cutting a release."
---

Rule 4 — exactly two keys

BEFORE — extra keys borrowed from npm/semver habits:

yaml
---
name: Changelog Generator
version: 1.0.0
author: platform-team
tags: [git, docs]
description: Generates changelogs.
---

AFTER — only name and description:

yaml
---
name: Changelog Generator
description: "Generate a changelog from git history grouped by type. Use when cutting a release or updating CHANGELOG.md."
---

Rule 5 — name length & form

BEFORE — a kebab id reused as the display name, or an overlong sentence:

yaml
name: changelog-generator-that-reads-git-history-and-groups-by-commit-type

AFTER — short, human-friendly title ≤ 64 chars:

yaml
name: Changelog Generator

Rule 6 — description must say WHAT and WHEN

BEFORE — what only, no trigger:

yaml
description: "A tool that generates changelogs from git history."

AFTER — what + explicit Use when trigger:

yaml
description: "Generate a changelog from git history grouped by commit type. Use when cutting a release, summarizing merged PRs, or updating CHANGELOG.md."

Rule 7 — body opens with H1 # <Name>

BEFORE — body starts with prose or a sub-heading:

markdown
---
name: Changelog Generator
description: "... Use when cutting a release."
---
This skill generates changelogs.

AFTER:

markdown
---
name: Changelog Generator
description: "... Use when cutting a release."
---

# Changelog Generator

This skill generates changelogs from git history.

Rule 8 — lean body, link the rest

BEFORE — a 600-line SKILL.md with every template pasted inline. AFTER — a short SKILL.md that links out:

markdown
See `resources/templates/changelog.hbs` for the template.
Run `scripts/build.sh` to generate.

Edge cases & exceptions

• name with special characters (:, #, leading @): quote the YAML string —

name: "JSON:API Builder". Unquoted name: JSON:API Builder is a YAML parse error.

• Description near the 1024-char limit: trim prose, keep the Use when trigger — the trigger is

load-bearing, not the prose.

• Multiple related skills: each gets its OWN .claude/skills/<name>/ directory. Do not put two

skills in one folder or namespace them under a parent.

• The skill needs scripts or templates: allowed — put them in scripts/, resources/, or

references/ UNDER the skill dir. These are content subdirs, not the forbidden "nested namespace under the skill name"; SKILL.md still sits at the top of the skill dir.

• A README.md for humans: fine to include alongside SKILL.md, but Claude reads SKILL.md. The

README.md is never a substitute for it.

• Kebab dir vs Title-Case name: they intentionally differ — directory pr-summarizer,

name: PR Summarizer. Don't force them to match.

Do / Don't

• DON'T name the file skill.md, Skill.md, skill.yaml, or manifest.json. ALWAYS name it

SKILL.md.

• DON'T emit the skill as a JSON / TOML / package.json object. ALWAYS use a Markdown file with a

YAML frontmatter block.

• DON'T add version, author, tags, tools, license, or category to the frontmatter. ALWAYS

stop at name and description.

• DON'T write a description that only says what it does. ALWAYS include an explicit Use when …

trigger.

• DON'T nest the skill under grouping/namespace folders. ALWAYS place <name>/ directly under

.claude/skills/.

• DON'T start the body with prose or ##. ALWAYS open with the H1 # <Name>.

Common mistakes (the base's wrong defaults)

• Emitting a package.json-shaped JSON manifest instead of a Markdown + YAML-frontmatter file.
• Reflexively adding version: 1.0.0, author, and tags from package-manifest habit.
• Lower-casing the filename to skill.md, or using manifest.yaml / README.md as the skill file.
• Writing a description that states only the function and omits the Use when trigger.
• Nesting the skill under a category/namespace path like .claude/skills/git/changelog/.
• Forgetting the opening # <Name> H1, or putting text before the frontmatter's first ---.

Quick checklist

• ] Path .claude/skills/<kebab-name>/SKILL.md, one dir level, no nesting.
• ] File named exactly SKILL.md.
• ] Frontmatter fenced by --- lines, at the very top.
• ] Exactly two keys: name and description — nothing else.
• ] name ≤ 64 chars; description ≤ 1024 chars with an explicit Use when trigger.
• ] Body opens with # <Name>.
• ] Long material linked from scripts/ / resources/, not inlined.