Lesson 10Claude Skills

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.

description fieldtrigger phrasesoutput formatconstraintsbefore & after
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 & 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
SKILL.md (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 — sometimes prose, sometimes bullet points, sometimes nothing useful.
✅ Precise
SKILL.md (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.

SectionWhat it controlsCommon mistake
nameThe slash command: /nameSpaces or uppercase — use kebab-case only
descriptionAuto-detection trigger + context for ClaudeOne vague line — should be 3–5 lines
allowed-toolsWhich Claude tools the skill can useOmitting Read when the skill needs file access
## RoleClaude's persona while running the skillSkipping it — Claude defaults to generic assistant
## StepsThe ordered workflow Claude must followProse instead of numbered steps
## Output formatShape and length of the final responseNot specifying — output varies every run
## ConstraintsWhat Claude must NOT doSkipping it — leads to runaway or unexpected behaviour
01

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?

claude.ai/customize/skills — Edit Skill
Your skills
/code-review
/commit
/standup
/standupediting
Description
Generate a daily standup update.
Triggered by: "standup", "daily update", "/standup".
Outputs: Yesterday / Today / Blockers in plain text.
✅ What it does — clear
✅ Trigger phrases — listed
✅ Output shape — named
SKILL.md — description field
---
name: standup
description: >
  Generate a daily standup update.
  Triggered by: "standup", "daily update", "/standup".
  Outputs: Yesterday / Today / Blockers in plain text.
---
02

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.

❌ Don't: "Write a commit message for the staged changes." — Claude might write a sentence, a paragraph, or a multi-line block.
✅ Do: "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."
SKILL.md — output format in description
---
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.
---
03

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.

SKILL.md — constraints section
---
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.
💡 Tip: Write constraints in the negative: "Never edit files directly" is clearer than "Only report issues." Negative phrasing is less ambiguous for language models.

Quick checklist before saving a skill

☑name is kebab-case, no spaces or uppercase
☑description answers What / When / Outputs in 3+ lines
☑trigger phrases are listed in the description
☑allowed-tools is set (add Read if the skill reads files)
☑## Role is one clear sentence
☑## Steps is a numbered list, not prose
☑## Output format specifies shape, length, and structure
☑## Constraints lists what Claude must NOT do
☐(Optional) ## Examples shows one input → one output pair
ℹ️ Info: The most reliable skills have a clear role, numbered steps, and at least one example. If your skill produces inconsistent output, the first thing to fix is the ## Output format section — it is the single biggest driver of consistency.

What's Next

Writing good instructions is an art. The next lesson shows you how to test your skills systematically so they work reliably every time.