How to write a SKILL.md (with examples)

What does a SKILL.md file look like?

To create a skill for Claude Code, the Claude app or Codex, make a folder and add a SKILL.md file: a header with a name and a description, then the instructions in Markdown. Save it in your agent's skills folder and test it in a new session. A SKILL.md file is all you need, and you can write one in any text editor in a few minutes. The format comes from the open Agent Skills standard, so the same file works across agents.

A skill is a folder. Inside it, SKILL.md has two parts: a header between two --- lines (YAML frontmatter), then the instructions in Markdown.

code-review/
├── SKILL.md
└── references/
    └── checklist.md      (optional extra files)

---
name: code-review
description: Review a diff or pull request for bugs, edge cases and
  security issues. Use when the user asks for a code review or before merging.
---

# Code review
...instructions...

The two required fields

name

• Lowercase letters, digits and hyphens only, like code-review or release-notes-v2.
• Up to 64 characters.
• It must match the folder name exactly.
• It can't start or end with a hyphen, or contain two hyphens in a row.
• For Claude, it also can't contain the words "claude" or "anthropic", so claude-helper is out.

Pick a name that says what the skill does. Anthropic's authoring best practices suggest verb forms like writing-release-notes or plain noun phrases like release-notes, and warn against vague names like helper or utils.

description

• Required, up to 1,024 characters.
• Says what the skill does and when to use it. The agent reads only this line when deciding whether to load the skill.
• No XML tags (Claude rejects them).
• If you plan to upload the skill to the Claude app, keep it short: Anthropic's help article on creating custom skills lists a 200-character limit for descriptions there.

Optional fields

The standard also allows a few optional fields. Most skills don't need any of them.

Claude Code adds its own fields, such as disable-model-invocation: true to stop Claude from running a skill on its own. Other agents ignore fields they don't know, so they're safe to include.

How do you write a good skill description?

A good description names the task and the words people actually use, and ends with a "Use when" sentence. It works like a trigger: agents compare it to what you asked for.

Anthropic recommends writing it in the third person ("Reviews a diff...", not "I can review..."), because the description is added to the agent's system prompt and a shifting point of view can confuse skill selection. Put the most important words first: when many skills are installed, both Claude Code and Codex shorten long descriptions to fit their budget.

# Too vague: the agent can't tell when this applies
description: Helps with code.

# Specific: what it does, and when to use it
description: Review a diff or pull request for bugs, edge cases and
  security issues, with the smallest fix for each. Use when the user asks
  for a code review, a PR review, or "check this before I merge".

Write the instructions

1. Lead with the steps. A short numbered list the agent can follow beats paragraphs of background.
2. Say what good output looks like. Format, length, tone, and one short example if the format matters.
3. Cover the gaps. What to do when information is missing, for example "If the language isn't given, use TypeScript" or "Ask for the diff if it isn't given."
4. Keep the main file focused. Move long checklists, style guides or API notes into separate files in the folder and link to them. The agent opens them only when needed.
5. Put repeatable work in scripts. A script in the folder runs the same way every time, where instructions can drift.
6. Don't explain what the agent already knows. Skip "a commit message describes a change". Spend the words on your rules, which it can't guess.
7. Match strictness to risk. A code review can be loose guidance. A database migration should be exact steps, in order, with "do not skip" where it matters.

Keep the body under about 500 lines. When you link to other files, use relative paths like references/checklist.md, keep links one level deep from SKILL.md, and say whether the agent should run a script or read it.

A full example

---
name: commit-message
description: Write a clear commit message from the staged changes, in the
  Conventional Commits style. Use when the user asks to commit, or asks for
  a commit message.
---

# Commit message

1. Read the staged diff (git diff --staged).
2. Pick the type: feat, fix, docs, refactor, test or chore.
3. Write a subject line under 72 characters, in the imperative:
   "fix: handle empty cart totals", not "fixed some bugs".
4. If the change needs context, add a body explaining why, not what.

If nothing is staged, say so and stop.

Where do you save a SKILL.md?

Test it

1. Start a new session so the agent sees the skill.
2. Ask for the task in your own words, three or four different ways. Don't copy the description.
3. Check the agent loaded the skill and followed the steps, including the edge cases.
4. If it didn't trigger, add the words you used to the description. If it triggered when it shouldn't, narrow the description.
5. Run it directly to test the instructions alone: /commit-message in Claude Code, $commit-message in Codex.

Common mistakes

• A description that says what but not when. "Formats SQL" never triggers when someone asks to "clean up this query".
• One skill doing five jobs. Split it. Small skills trigger more reliably and are easier to fix.
• A name that doesn't match the folder. Uploads to the Claude app fail on this, and other agents may skip the skill.
• Background essays. Long explanations push your actual rules down the page. Lead with steps.

Checklist before you save

• The folder name and name match, in lowercase with hyphens.
• The description says what and when, and fits in 1,024 characters.
• The steps are numbered and the expected output is clear.
• Missing information has a default or a question.
• Long reference material lives in its own file.

Turn a prompt you already have into a skill

Most good skills start as a prompt you keep pasting. The free SKILL.md generator does it in your browser: paste the prompt, check the name and description, copy the file.

In Kipt, open the prompt and choose Promote to skill: it suggests the name and a description you can sharpen, and turns each blank like {{language:TypeScript}} into an instruction such as "If the language isn't given, use TypeScript." It checks the rules for you and saves the folder to your GitHub repo, ready to install.

New to skills? Start with what Claude Code skills are and how to install them.