How to Write Good Skill Instructions
The quality of your SKILL.md determines how reliably Claude performs the task. A vague description produces inconsistent results; a precise one produces the same output every time.
Six rules for reliable skills
| # | Rule | Why it matters |
|---|---|---|
| 01 | Name the behaviour | Say exactly what the skill does, not just what it is about. |
| 02 | Add trigger phrases | Tell Claude which phrases should activate the skill. |
| 03 | Define the output | Specify format, length, and structure of the expected response. |
| 04 | Give a clear role | One sentence — who Claude is playing while running this skill. |
| 05 | List the steps | Numbered steps prevent Claude from skipping or reordering tasks. |
| 06 | Set constraints | What Claude must NOT do is often more important than what it should. |
Before and after: the same skill, written two ways
The two skills below have the same name and intent — reviewing code. The difference is how precisely the instructions are written.
Vague
--- name: review description: Review code --- Review the code the user gives you.
Problems: No trigger phrases. No output format. No steps. Claude will interpret “review” differently every time.
Precise
--- name: code-review description: > Review code for bugs, security issues, and style violations. Triggered by: "review this", "check my code", "/code-review". Outputs a structured report grouped by severity. allowed-tools: - Read --- ## Role You are a senior code reviewer. Your job is to catch bugs, security flaws, and style issues before code ships. ## Steps 1. Read the full file or diff the user provides. 2. Group findings under three headings: - Critical — must fix before merge - Warning — should fix - Style — optional improvement 3. For each finding include: - File + line number - What is wrong and why it matters - A concrete fix suggestion (code snippet when helpful) ## Output format Use Markdown. Keep each finding to 3–5 lines. End with a one-line summary: "X critical, Y warnings, Z style notes." ## Constraints - Do NOT rewrite the entire file — annotate only. - Flag potential SQL injection, XSS, and hardcoded secrets as Critical. - If the diff is clean, say so explicitly.
Why it works: Role, steps, output format, and constraints are all explicit. Claude produces the same structured report every time.
Anatomy of a well-written SKILL.md
Every section of your skill file has a specific job. Here is what each part controls and the most common mistake for each.
| Section | What it controls | Common mistake |
|---|---|---|
name | The slash command: /name | Spaces or uppercase — use kebab-case only |
description | Auto-detection trigger + context for Claude | One vague line — should be 3–5 lines |
allowed-tools | Which Claude tools the skill can use | Omitting Read when the skill needs file access |
## Role | Claude's persona while running the skill | Skipping it — Claude defaults to generic assistant |
## Steps | The ordered workflow Claude must follow | Prose instead of numbered steps |
## Output format | Shape and length of the final response | Not specifying — output varies every run |
## Constraints | What Claude must NOT do | Skipping it — leads to runaway or unexpected behaviour |
1. Write a description that does three things
The description field is read by Claude every time it decides whether to auto-activate your skill. It should answer three questions: What does it do? When is it triggered? What does it output?
--- name: standup description: > Generate a daily standup update. Triggered by: "standup", "daily update", "/standup". Outputs: Yesterday / Today / Blockers in plain text. ---
2. Always specify an output format
Without an output format section, Claude picks a format on its own — and it changes every run. Specify format, length, and any structural requirements explicitly.
| Instead of… | Try… |
|---|---|
| “Write a commit message for the staged changes.” Claude might write a sentence, a paragraph, or a multi-line block. | “Outputs a single-line commit message: type(scope): description. Optionally follow with a blank line and a one-paragraph body if the change is complex.” Format, length, and optional body are all defined. |
--- name: commit description: > Write a Conventional Commit message from staged changes. Outputs a single-line commit message in the format: type(scope): short description followed by an optional body. ---
3. Use constraints to stop unwanted behaviour
Claude tries to be helpful beyond the task. A ## Constraints section explicitly draws the boundary — what the skill should not do.
--- name: docs-review description: Review documentation for clarity and completeness. allowed-tools: - Read --- ## Constraints - Never edit the file directly — only report issues. - Ignore spelling outside of headings and code samples. - Do not suggest restructuring the entire document. - Maximum report length: 300 words.
Quick checklist before saving a skill
| Done | Check |
|---|---|
| Yes | name is kebab-case, no spaces or uppercase |
| Yes | description answers What / When / Outputs in 3+ lines |
| Yes | trigger phrases are listed in the description |
| Yes | allowed-tools is set (add Read if the skill reads files) |
| Yes | ## Role is one clear sentence |
| Yes | ## Steps is a numbered list, not prose |
| Yes | ## Output format specifies shape, length, and structure |
| Yes | ## Constraints lists what Claude must NOT do |
| — | (Optional) ## Examples shows one input → one output pair |
Before you continue
- A precise
descriptionanswers what, when, and what output — in 3+ lines. - Numbered
## Stepsand a defined## Output formatdrive consistency. ## Constraintsin negative phrasing stops runaway behaviour.- The
## Output formatsection is the single biggest driver of consistency — fix it first when output varies. - Next: systematic skill testing — invocation checks, output consistency, and regression logs.
What's Next
Writing good instructions is an art. Next: systematic skill testing — invocation checks, output consistency, and regression logs.