Claude Code skills: 6 examples and how to write one
How to write a Claude Code skill: SKILL.md, frontmatter fields, arguments, and dynamic context. Six copy-paste examples, plus how to share skills with a team.
Every week someone on the team asks Claude Code to write a pull request description, and every week they explain the format again: what changed, why, how it was tested, the ticket link. The explanation is always the same. That repetition is what skills are for.
A skill packages instructions Claude loads only when they are needed. This post explains how to write one and gives six examples, based on Anthropic's skills documentation, checked on 16 November 2026.
How a skill works
A skill is a folder containing a SKILL.md file. The file has two parts: YAML frontmatter between --- markers that tells Claude when to use it, and markdown instructions Claude follows when it runs.
- Where it lives:
.claude/skills/<name>/SKILL.mdfor a project, shared with the team through git, or~/.claude/skills/<name>/SKILL.mdfor you across all projects. - How it runs: Claude loads it automatically when your prompt matches its description, or you run it directly with
/name. - What it costs: the body loads only when used, unlike CLAUDE.md, which loads every session. Once loaded, it stays in context across turns, so keep it concise.
Frontmatter fields
| Field | What it does |
|---|---|
description | What the skill does and when to use it. Claude matches prompts against it. Recommended |
name | The command name. Defaults to the folder name |
when_to_use | Extra trigger phrases, appended to the description |
argument-hint | Shown in autocomplete, for example [issue-number] |
arguments | Named arguments, available as $name in the body |
disable-model-invocation | true means it only runs when you type /name |
allowed-tools | Tools pre-approved while the skill runs, so they don't prompt, for example Read Grep |
context: fork | Runs the skill in its own subagent context |
All fields are optional, and a misspelled field is ignored without an error. The frontmatter is only read if the opening --- is the first line of the file.
Example 1: write a pull request description
Pulls the diff into the skill when it runs, so Claude starts with the actual changes. A line starting with ! and a command in backticks is run, and its output is inserted.
.claude/skills/pr-description/SKILL.md:
---
description: Write a pull request description for the current branch. Use when the user asks for a PR description or is about to open a PR.
---
## Changes on this branch
!`git diff main...HEAD --stat`
## Instructions
Write a PR description with these sections:
- What changed: 2 to 4 bullets
- Why: one sentence, link the ticket if the branch name has an ID
- How it was tested: commands run and their result
Keep it under 200 words. Don't list every file.
Example 2: fix a GitHub issue by number
Takes an argument. Run it as /fix-issue 482.
.claude/skills/fix-issue/SKILL.md:
---
description: Investigate and fix a GitHub issue by number.
argument-hint: [issue-number]
---
## Issue
!`gh issue view $0`
## Steps
1. Reproduce the problem with a failing test.
2. Fix it with the smallest change that makes the test pass.
3. Run the full test suite.
4. Summarize the cause and the fix, and reference issue #$0.
$0 is the first argument. $ARGUMENTS holds all of them.
Example 3: a deploy you only run on purpose
Some procedures should never start because Claude thought they were relevant. disable-model-invocation: true means only /deploy runs it, and context: fork runs it in its own subagent so the deploy output doesn't fill your main conversation.
---
name: deploy
description: Deploy the application to production.
context: fork
disable-model-invocation: true
---
1. Run the test suite. Stop if anything fails.
2. Build the application.
3. Deploy with `./scripts/deploy.sh production`.
4. Report the deployed version and the health check result.
Example 4: a code reviewer that doesn't edit
allowed-tools pre-approves the listed tools, so the review runs without permission prompts. It doesn't block other tools, so the instructions say not to edit, and edits still go through your normal permission settings.
---
description: Review the current changes for bugs, missing tests, and security issues. Use when the user asks for a review.
allowed-tools: Read Grep Glob
---
!`git diff HEAD`
Review the diff above. Do not edit any files. For each problem, give the file and line, what is wrong,
and a one-line fix. Check: error handling, missing tests, secrets in code,
and SQL built from strings. If nothing is wrong, say so in one line.
Example 5: a migration with a template file
A skill folder can hold supporting files. Here the skill points Claude at a template in the same folder.
.claude/skills/new-migration/
SKILL.md
template.sql
---
description: Create a new database migration. Use whenever a schema change is needed.
argument-hint: [short-description]
---
1. Create db/migrations/<timestamp>_$0.sql using template.sql in this skill's folder.
2. Never edit a migration that has already been applied.
3. Include a down migration.
4. Run `make migrate-test` and report the result.
Example 6: draft an architecture decision record
Writes ADRs in the same shape every time, and never marks one accepted on its own. The full version, with the template it uses, is in ADR for AI agents.
---
name: adr
description: Draft a new architecture decision record in docs/adr/ when the user makes or changes an architecture decision.
---
1. Find the next free number in docs/adr/README.md.
2. Write docs/adr/NNNN-short-title.md from docs/adr/TEMPLATE.md.
3. Set Status: Proposed. A person approves it.
4. If it replaces an ADR, say so and link both.
When a skill misbehaves
| Problem | Likely cause | Fix |
|---|---|---|
| Never triggers | Description doesn't match how people ask | Put the main use case first; add trigger phrases in when_to_use |
| Triggers too often | Description is too broad | Narrow it, or set disable-model-invocation: true |
| Ignored partway through | Body is long or rambling | State what to do, not why; cut it down |
| Description cut short | Over the 1,536-character listing limit | Shorten description and when_to_use together |
| No fields apply | Frontmatter didn't parse | Make --- the first line; check the YAML |
Sharing skills with a team
Commit project skills in .claude/skills/ and everyone who works in the repository gets them. They can also run in CI, covered in Claude Code GitHub Actions. Cursor also loads skills from .claude/skills/; see Cursor rules vs skills vs AGENTS.md vs CLAUDE.md. For skills that many repositories need, package them as plugins in a team marketplace, covered in Claude Code team memory. The full setup is in Claude Code plugins and marketplaces.
Skills hold procedures: how the team does a task. They are less suited to decisions that change, such as which payment provider to use or which feature is cut from a release. A skill file can go stale like any other file.
Where Lockstep fits
Lockstep's Standards & Skills feature distributes skills to a whole engineering organization. An engineering lead publishes a skill once, written in Lockstep or imported from a public GitHub repository at an exact commit, and rolls it out by team, repository, or path. Enrolled checkouts receive it in .claude/skills/lockstep-org-*/, kept out of git and never overwriting a developer's local edits, and an adoption view shows which version reached which checkout. Whether Claude actually invoked a skill is reported as unobservable, not guessed.
Managed skills work with Claude Code today. See how it works.
Sources checked 16 November 2026
Related reading
For the definition, see agent skills. For hooks, which run whatever Claude decides, see Claude Code hooks: 6 examples. For subagents, see Claude Code subagents: 5 examples. For the built-in commands, see the Claude Code slash commands cheat sheet. To choose between all the extensions, see CLAUDE.md vs skills vs hooks vs subagents. For what still belongs in CLAUDE.md, see CLAUDE.md examples. For the format shared across Claude Code, Codex, and Cursor, see the Agent Skills open standard.
Frequently asked questions
- How do I create a Claude Code skill?
- Make a folder at .claude/skills/<skill-name>/ for a project skill, or ~/.claude/skills/<skill-name>/ for a personal one, and add a SKILL.md with frontmatter and instructions. The folder name, or the name field, becomes the command you type, such as /summarize-changes.
- What frontmatter does SKILL.md need?
- All fields are optional. description is recommended, because Claude uses it to decide when to load the skill. Other fields include name, when_to_use, argument-hint, arguments, disable-model-invocation, allowed-tools, and context: fork to run the skill in a subagent.
- How do I pass arguments to a skill?
- Type them after the command, like /fix-issue 482. In the skill, $ARGUMENTS holds all arguments, $0 or $ARGUMENTS[0] holds the first, and named arguments declared in the arguments field are available as $name.
- What is the difference between a skill and CLAUDE.md?
- CLAUDE.md loads in full at the start of every session. A skill's body loads only when it is used, so it suits longer procedures that only matter for some tasks. Once loaded, a skill stays in context across turns, so keep it concise.
- Why is my skill not triggering?
- Usually the description doesn't match how you ask. Put the key use case first, because the description and when_to_use text are truncated at 1,536 characters in the skill listing. Also check that the frontmatter's opening --- is the file's first line and that the YAML parses.
Keep reading