BBotnexio

Buy now!

← All guides

SKILL.md Format & Template: Write a Claude Code Skill (with Examples)

You keep pasting the same checklist into Claude Code. A skill fixes that: one SKILL.md file, and Claude picks it up when it's relevant or when you type /skill-name.

This guide gives you a copy-paste template, the exact frontmatter rules, three short examples, and the errors that stop a skill from loading.

What a skill is (and isn't): SKILL.md vs. CLAUDE.md vs. AGENTS.md

A skill is a folder with a SKILL.md file: YAML frontmatter plus Markdown instructions. Claude Code skills follow the open Agent Skills standard.

The key difference is when content loads:

FileLoadedUse for
CLAUDE.mdEvery sessionFacts: build commands, conventions, layout
AGENTS.mdEvery session (tool-dependent)Same, shared across coding agents
SKILL.mdDescription always; body only when usedProcedures, checklists, long reference

Anthropic's docs put it plainly: if a CLAUDE.md entry "is a multi-step procedure or only matters for one part of the codebase", move it to a skill or a path-scoped rule.

skill.md vs agent.md: AGENTS.md is always-on project context. A skill is an on-demand procedure. Claude Code reads AGENTS.md as project instructions (v2.1.277+) when no CLAUDE.md is present. For the AGENTS.md side, see Cursor Rules vs. AGENTS.md.

Where skills live

Personal: ~/.claude/skills/<name>/SKILL.md

Available in all your projects on this machine. Not loaded in Cowork or cloud sessions.

Project: .claude/skills/<name>/SKILL.md

Loaded in sessions for this repository. Commit it and your team gets it too.

Other locations exist (enterprise, plugin, nested folders in monorepos). Two reserved folder names to avoid: synced and anthropic-skills.

mkdir -p .claude/skills/commit-message

SKILL.md format

YAML frontmatter

The frontmatter sits between --- markers and must start on the first line. Otherwise Claude Code treats the whole file, markers included, as plain content.

The Agent Skills spec requires two fields:

  • name: 1–64 characters, lowercase letters, numbers and hyphens only. No leading or trailing hyphen, no --. Must match the parent folder name.
  • description: 1–1,024 characters. Say what the skill does and when to use it.

Optional spec fields: license, compatibility (max 500 characters), metadata (string key–value map) and allowed-tools (experimental).

Claude Code is more lenient: all fields are optional there, description is recommended, and name defaults to the folder name. It also adds its own fields, such as disable-model-invocation, argument-hint and context: fork.

One catch: if you upload a skill to claude.ai or the Skills API, only the six spec fields are allowed. Anything else fails with an "Unexpected key(s) in SKILL.md frontmatter" error. Stick to the spec fields if you want a portable skill.

Body: instructions, steps, examples

The body has no format restrictions. The spec recommends step-by-step instructions, input/output examples and edge cases.

Keep it lean. Once a skill loads, its content stays in context across turns, so every line costs tokens.

Supporting files and progressive disclosure

Skills load in stages. Name and description (~100 tokens) load at startup. The body loads when the skill activates (the spec recommends under 5,000 tokens). Extra files load only when needed.

my-skill/
├── SKILL.md
├── references/   # docs Claude reads on demand
├── scripts/      # code Claude runs
└── assets/       # templates, data files

Keep SKILL.md under 500 lines. Reference files with relative paths, one level deep.

Copyable SKILL.md template

Spec-only fields, so it stays portable:

---
name: my-skill
description: Does X for Y. Use when the user asks to X, mentions Y, or wants Z.
license: Proprietary
metadata:
  author: your-name
  version: "1.0"
---

# My Skill

## When to use
- The user asks to ...
- Files matching ... are involved

## Steps
1. Read ...
2. Do ...
3. Check ...

## Output format
- ...

## Edge cases
- If ..., then ...

## More detail
- See [references/REFERENCE.md](references/REFERENCE.md) for ...

Save it as .claude/skills/my-skill/SKILL.md. Remember: the folder is my-skill, so name is my-skill.

Three short examples

1. Commit message

---
name: commit-message
description: Writes a Conventional Commits message for the staged changes. Use when the user asks for a commit message or wants to commit.
---

1. Run `git diff --staged` and read the changes.
2. Pick one type: feat, fix, docs, refactor, test, chore.
3. Write a subject line under 72 characters, imperative mood.
4. Add a short body only if the change needs context.
5. Output the message in one code block. Don't commit.

2. Code review checklist

---
name: review-checklist
description: Reviews a diff against the team checklist. Use when the user asks for a code review, PR review, or "check my changes".
---

Check the diff for:
- Missing error handling and unchecked inputs
- Hardcoded secrets, URLs or magic numbers
- New code without tests
- Names that don't match nearby code

Report findings as a list: file, line, issue, suggested fix.
If nothing is wrong, say so in one line.

3. Release notes

---
name: release-notes
description: Drafts user-facing release notes from git history. Use when the user asks for release notes, a changelog, or "what's new".
---

1. Run `git log --oneline` since the last tag.
2. Group entries under: New, Improved, Fixed.
3. Rewrite each entry for users, not developers.
4. Skip internal chores and refactors.

Want Claude to never trigger a skill on its own (say, a deploy)? In Claude Code, add disable-model-invocation: true. That's a Claude Code extension, not a spec field.

Writing descriptions that trigger reliably

The description decides whether Claude loads your skill. Treat it like a search query.

  • Lead with the use case. Claude Code truncates description + when_to_use at 1,536 characters in the skill listing.
  • Name the trigger words users actually type: "commit message", "changelog", "PR review".
  • Bad: "Helps with PDFs." Good: "Extracts text and tables from PDF files… Use when working with PDF documents." (Both are the spec's own examples.)
  • Bilingual teams: add the phrases in both languages, e.g. "Use when the user asks for release notes or Versionshinweise." This fits in the same description field.

If a skill triggers too often, make the description more specific.

Common errors

  • "SKILL.md must start with YAML frontmatter (---)": the opening --- isn't the first line. Remove blank lines, BOMs or comments above it.
  • Broken YAML: in Claude Code the skill still loads, but with no fields set, so Claude can't match the description. Run claude --debug to see the parse error.
  • Invalid name: My-Skill, -skill and my--skill all break the spec. Use lowercase with single hyphens.
  • Name ≠ folder name: the spec requires them to match.
  • Description too long: over 1,024 characters breaks the spec.
  • Non-spec fields on upload: argument-hint and other Claude Code fields fail on claude.ai or the Skills API.

Validate before you share

The spec points to its reference library:

skills-ref validate ./my-skill

In Claude Code 2.1.233 and later, claude plugin validate can also check a bare .claude/skills directory (no plugin manifest needed) and reports SKILL.md files whose frontmatter fails to parse:

claude plugin validate .claude/skills

Then check triggering: ask "What skills are available?" and try a prompt that should match.

Prefer to start from ready-made skills?

The Claude Code Skills Pack by Aramac has 14 skills, validated against the Agent Skills specification (claude plugin validate, Claude Code 2.1.301). Personal, non-commercial use only (license). €29 incl. VAT.

Need an AGENTS.md or CLAUDE.md to go with it? See the Cursor + Claude Code Rules Pack (€19 incl. VAT).

FAQ

What is the difference between SKILL.md and AGENTS.md?
AGENTS.md holds project instructions that load every session. A SKILL.md holds one procedure; only its description is always in context, and the body loads when the skill is used.

Which frontmatter fields does SKILL.md need?
The Agent Skills specification requires name and description. Claude Code itself treats every field as optional but recommends description, and uses the folder name if name is missing.

Where do I put SKILL.md?
In a folder named after the skill: ~/.claude/skills/<name>/SKILL.md for personal skills, or .claude/skills/<name>/SKILL.md inside a project.

Why isn't my skill triggering?
Check that the opening --- is the first line, that the YAML parses, and that the description contains the words you actually use. You can always invoke it directly with /skill-name.

Do skills work on claude.ai?
You can upload them to claude.ai. Uploads accept only the six spec fields (name, description, license, compatibility, metadata, allowed-tools), and Claude Code-only features such as dynamic context injection don't work there.

Sources

All checked October 16, 2026.

---

An independent product by Aramac GmbH. Not affiliated with or endorsed by Anysphere (Cursor) or Anthropic (Claude Code). Cursor and Claude are trademarks of their respective owners.