How to write a SKILL.md

A SKILL.md file is a set of instructions your coding agent loads when a task matches. Writing one is closer to briefing a capable new colleague than to programming. The format is simple. The hard part is getting the agent to pick the skill at the right time and then actually follow it.

This guide walks through each part of the file, then shows a complete skill you can copy. It follows the open specification at agentskills.io, which Claude Code, Cursor, Codex, GitHub Copilot and Gemini CLI all read. If you are new to the concept, start with what agent skills are.

The anatomy of a skill

A skill is a folder. The folder name is the skill's name, and inside it SKILL.md is required. Everything else is optional:

pr-description/
  SKILL.md
  references/
    examples.md
  scripts/
    collect_diff.sh

SKILL.md has two parts: YAML frontmatter between --- lines, and a Markdown body.

Part 1: Frontmatter

The spec requires two fields.

name. 1 to 64 characters, lowercase letters, numbers and hyphens only. It cannot start or end with a hyphen or contain two hyphens in a row, and it must match the folder name. pr-description is valid; PR_Description and pr--description are not.

description. 1 to 1024 characters. What the skill does and when to use it. This is the most important line in the file, so it gets its own section below.

Optional spec fields are license, compatibility (environment requirements, up to 500 characters), metadata (a map of string keys to string values, for example author and version) and allowed-tools (experimental, support varies).

Agents add their own fields on top. Claude Code and Cursor both support disable-model-invocation: true, which stops the agent from loading the skill on its own so it only runs when you call it by name. Use it for skills that take actions, like deploying. Claude Code supports many more (paths, model, context and others). Agents ignore fields they do not know, but if you plan to upload a skill to claude.ai, stick to the spec fields: Claude's upload rejects anything else.

Two mechanical rules that cause most "invisible skill" bugs: the opening --- must be the very first line of the file, and the YAML must parse. In Claude Code, a broken frontmatter still loads the skill but with no fields, so your description silently disappears.

Part 2: A description that triggers

At the start of each session, the agent sees only each skill's name and description. It decides whether to load your skill from those few words. So the description has two jobs:

1. Say what the skill produces, concretely.
2. Say when to use it, in the words a user would actually type.

Compare:

• Weak: "Helps with pull requests."
• Strong: "Writes a pull request description from the current branch's diff: summary, why, how to test, risks. Use when the user asks for a PR description, PR body, merge request text, or says they are about to open a PR."

The strong version names the output, lists trigger phrases, and covers synonyms ("merge request"). A few more tips:

• Put the main use case first. Claude Code truncates long descriptions in its skill list (at 1,536 characters), and every agent weighs the opening words most.
• Write in the third person about what the skill does, not "I can help you".
• Say when not to use it if there is an obvious neighbour: "Not for commit messages."
• Do not stuff keywords. A list of fifty terms makes the skill fire on unrelated tasks.

Part 3: The body

The body loads in full once the skill is triggered. The spec recommends keeping it under about 5,000 tokens and 500 lines; move anything longer to separate files. There is no required structure, but this order works well:

1. Goal. One or two sentences: what done looks like.
2. Inputs. What the agent must gather or ask for before starting.
3. Steps. Numbered, each one a concrete action.
4. Output format. A template of the exact result.
5. Rules. The few hard constraints, phrased as checkable statements.
6. Example. One short input and output pair, or a pointer to a reference file.

Write instructions the agent can check itself against. "Be concise" is not checkable. "The summary is at most three sentences" is. Explain the reason behind a non-obvious rule in a few words: agents follow rules better when they know why, and they handle edge cases more sensibly.

Part 4: references and scripts

Supporting files are loaded only when the body tells the agent to read them, so they cost nothing until needed.

• references/ holds longer documentation: style guides, API notes, extended examples. Point to them with a relative path and say when to read them: "If the diff touches database migrations, read references/migrations.md first."
• scripts/ holds code the agent can run. Use a script when the step is deterministic and the agent would otherwise improvise it: collecting a diff, validating a file, converting formats. Make scripts self-contained and print clear errors.
• assets/ holds templates and data files.

Keep references one level deep. A reference that points to another reference that points to a third tends to get skipped.

The full worked example

Here is a complete, working skill. Save it as .claude/skills/pr-description/SKILL.md for Claude Code, or .agents/skills/pr-description/SKILL.md for Cursor or Codex.

---
name: pr-description
description: Writes a pull request description from the current branch's changes, with summary, motivation, testing steps and risks. Use when the user asks for a PR description, PR body, merge request text, or says they are about to open a pull request. Not for commit messages.
metadata:
  author: your-team
  version: "1.0"
---

# PR description

Goal: a description a reviewer can read in under two minutes and know what changed, why, how to verify it, and what could break.

## Inputs

1. Find the base branch. Use `main` unless the user names another one.
2. Run `git log --oneline <base>..HEAD` and `git diff --stat <base>...HEAD`.
3. Read the full diff for any file with more than 20 changed lines.
4. If there is a linked issue in the branch name or commits (for example `fix/123-login`), note the number.
5. If you cannot tell why the change was made, ask the user one question before writing. Do not guess the motivation.

## Steps

1. Group the changes by user-visible effect, not by file.
2. Write the summary first, then the other sections.
3. For testing steps, prefer commands that exist in this repo (check package.json, Makefile or README).
4. List risks only if they are real: schema changes, changed public APIs, new env vars, removed behaviour, performance-sensitive paths.
5. Check the result against the rules below before showing it.

## Output format

## Summary
<1-3 sentences, what changes for the user or the system>

## Why
<the problem or request this solves; link the issue if found>

## Changes
- <one line per user-visible change>

## How to test
1. <command or click path>
2. <expected result>

## Risks
- <risk and how it is mitigated, or "None identified">

## Rules

- The summary is at most three sentences and contains no file names.
- Every item under Changes maps to something in the diff. Do not describe changes that are not in the diff.
- Mention every new environment variable and every migration by name under Risks.
- No marketing words ("robust", "seamless", "powerful").
- If the diff is over 800 changed lines, say so in the summary and suggest splitting the PR.

## Example

For a longer example of a finished description, read `references/example.md`.

Notice the pattern: trigger phrases and a boundary in the description, fact-gathering before writing, a literal output template, and rules the agent can verify. references/example.md is optional.

Part 5: Testing your skill

Treat a skill like code: try it before you trust it.

1. Check it loads. In Claude Code run /skills; in Codex run /skills; in Cursor type / in Agent chat and look for the name. Install steps are in our guides for Claude Code, Cursor and Codex.
2. Test triggering. In a fresh session, ask three or four realistic requests without naming the skill ("write up this PR for me", "I'm opening a merge request"). Then ask two that should not trigger it ("write a commit message"). Adjust the description until both sets behave.
3. Test the output. Run the skill on a real task and check each rule. Every rule that was broken is a sign the instruction is unclear or buried.
4. Validate the format. The agentskills.io reference tool checks frontmatter and naming: skills-ref validate ./pr-description.
5. Watch long sessions. In long conversations the agent may compact older context, and skill instructions can fade. Put the important rules early in the body.

Common mistakes

• A vague description. The skill never triggers, or triggers on everything.
• **Folder name and name do not match.** Some agents refuse the skill; others list it under a different name.
• Frontmatter not on line one. A blank line or a comment above --- breaks it.
• A wall of advice instead of steps. "Consider good practices for X" gives the agent nothing to do.
• Everything in one file. A 1,500-line SKILL.md costs context every time it loads. Move reference material out.
• Explaining what the agent already knows. Spend words on your conventions, not on how git works.
• No output format. Without a template, every run looks different.

If you would rather start from skills that already went through this testing, the coding skills on Risemi are written and tested in-house, and the free ones are a good set to read for structure.