Claude Code skills: the SKILL.md format, with examples

What is a Claude Code skill?

A skill is a set of instructions Claude Code can load on demand. You write a SKILL.md file, and Claude adds it to its toolkit. Claude uses a skill when it looks relevant, or you invoke one yourself by typing / followed by the skill name. The official skills documentation says to create one when you keep pasting the same instructions, checklist or multi-step procedure into chat.

The key difference from CLAUDE.md is cost. A skill's description sits in context so Claude knows it exists, but the body loads only when the skill is used. Long reference material costs almost nothing until you need it. CLAUDE.md, by contrast, loads at the start of every session.

Skills also replaced custom commands. A file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both create /deploy and work the same way. Existing command files keep working; skills add a folder for supporting files and finer control over who invokes them. Claude Code ships with bundled skills too, such as /doctor, /code-review, /batch, /debug, /loop and /claude-api.

If a section of your CLAUDE.md has grown from a fact into a procedure, move it into a skill. See the guide to writing CLAUDE.md for what belongs there, and the hooks guide for rules that must never be skipped.

What does a SKILL.md file look like?

Every skill needs a SKILL.md file with two parts: YAML frontmatter between --- markers that tells Claude when to use the skill, and Markdown content with the instructions Claude follows. The directory name becomes the command you type, unless you set a name in the frontmatter.

---
description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff.
---

## Current changes

!`git diff HEAD`

## Instructions

Summarize the changes above in two or three bullet points, then list any risks you notice such as missing error handling, hardcoded values, or tests that need updating. If the diff is empty, say there are no uncommitted changes.

Save that as ~/.claude/skills/summarize-changes/SKILL.md, open a git project with a small edit and ask "What did I change?" Claude should load the skill by itself. You can also run /summarize-changes directly.

The line starting with ! followed by a backticked command is dynamic context injection. Claude Code runs the command first and replaces the line with its output, so Claude sees the real diff rather than guessing from open files. The marker works at the start of a line or after whitespace.

• Frontmatter must start on line one. If the opening --- is not the file's first line, Claude Code treats the whole file as skill content.
• Bad YAML does not stop loading, but the skill loads with no fields set. /skill-name still works, though Claude cannot match your description. Run with --debug to see the parse error.
• Keep SKILL.md under 500 lines. Move detailed reference material into separate files in the same folder.

Where do Claude Code skills live?

Where you save a skill decides which sessions load it. Save under your home directory for every project, commit it to a repository so teammates get it, or ship it in a plugin.

If two skills share a name, enterprise beats personal and personal beats project. With a deploy skill in both ~/.claude/skills/ and the project, /deploy runs the personal one. Plugin skills are namespaced, so they do not clash. Do not name a folder synced or anthropic-skills; those names are reserved.

Claude Code watches the skill folders, so adding or editing a skill during a session takes effect within that session. If you create a top-level skills folder that did not exist when the session started, run /reload-skills. Run /skills to list what is available.

Sharing at scale means plugins. See the guide to Claude Code plugins for bundling skills with hooks and subagents.

Which frontmatter fields should you know?

All frontmatter fields are optional. Only description is recommended. Field names must match exactly, hyphens included, because Claude Code ignores an unrecognized field without an error.

The combined description and when_to_use text is cut off at 1,536 characters in the skill listing, so lead with what matters. Write the description the way a user would phrase the request, because that is how Claude decides.

Who decides when a skill runs: you or Claude?

By default both. You type /skill-name at the start of a message to run it directly, and Claude can load it when your request matches the description. Two fields change that:

Use disable-model-invocation: true for anything with side effects or timing you want to control: deploys, commits, messages sent to other people. You do not want Claude deciding to deploy because the code looks ready. Use user-invocable: false for background knowledge, such as an explanation of a legacy system, that Claude should know but that is not an action.

Pass arguments after the name. Whatever follows the skill name replaces the $ARGUMENTS placeholder in the body, so /fix-issue 123 makes Claude receive "Fix GitHub issue 123".

What does a good example skill look like?

Here are two templates you can copy. The first drafts release notes from recent git history and can be run by you or by Claude. The second is a manual-only release checklist with arguments, because a release should never start without a human asking.

---
name: release-notes
description: Drafts release notes from recent git commits. Use when the user asks for release notes, a changelog entry, or what shipped.
argument-hint: [since-tag-or-date]
allowed-tools: Bash(git log *)
---

## Recent commits

!`git log --oneline --no-merges -50`

## Instructions

Write release notes for a reader who uses the product but does not read code.

1. If $ARGUMENTS is given, only include changes since that tag or date. Use `git log` to find them.
2. Group changes under: New, Improved, Fixed. Drop commits that only touch tests, formatting or CI.
3. Write each item as one sentence that starts with what the user can now do.
4. Do not invent features. If a commit message is unclear, list it under a final heading called "Needs a human".
5. Output Markdown only.

---
name: ship
description: Run the release checklist for this repository
disable-model-invocation: true
argument-hint: [environment]
---

Prepare a release to $ARGUMENTS. Work through these steps in order and stop at the first failure:

1. Run the full test suite. Report failures and stop if any test fails.
2. Run the build. Report warnings.
3. Check that CHANGELOG.md has an entry for the current version.
4. Show me the list of commits since the last tag and ask me to confirm.
5. Only after I confirm, tell me the exact command to deploy. Do not run it yourself.

Notice what both do. They state a clear job, number the steps, say what to do on failure, and avoid narration. The docs advise keeping the body concise because once a skill loads its content stays in context for later turns, so every line is a recurring token cost.

For a skill that needs long reference material, split it into files and link them from SKILL.md so they load only when needed.

my-skill/
├── SKILL.md        (required: overview and navigation)
├── reference.md    (detailed docs, loaded when needed)
├── examples.md     (usage examples, loaded when needed)
└── scripts/
    └── helper.py   (a utility script, executed rather than loaded)

How do you create and test your own skill?

1. Pick a repeated task. If you pasted the same instructions into Claude Code twice this week, that is a skill.
2. Create the folder: mkdir -p ~/.claude/skills/my-skill for a personal skill, or .claude/skills/my-skill inside a project.
3. Write `SKILL.md` with a description that uses the words you would actually type, then short numbered instructions.
4. Test it two ways. Ask something that matches the description and see whether Claude loads the skill. Then run /my-skill directly.
5. Edit and retest in the same session. Claude Code picks up changes within the session.
6. Commit project skills so the team gets them, and review other people's skills like code.

Ideas worth turning into skills: a commit-message style, a pull-request review checklist, a test-writing recipe for your framework, a migration procedure, and a release-notes drafter like the one above. If you are looking for something to build and test a skill against, the board has plenty of developer-tool ideas that other people posted and will not build, including a changelog your users actually read. Browse developer tools ideas and let a release-notes skill write its first changelog.

Why is my skill not working?

For a first-time setup, start with the Claude Code tutorial and the commands guide. The skills documentation also covers running a skill in a subagent, restricting which skills Claude may call, and evaluating a skill with the skill-creator tool.