Writing SKILL.md: a practical guide

A skill lives or dies on two things: whether the agent loads it at the right moment, and whether the instructions work in a session that has no memory of you writing them. This guide covers both.

The anatomy

---
name: release-checklist
description: Runs our release procedure end to end. Use when the user
  says "release", "ship", "cut a version", or asks to deploy to
  production.
---

# Release checklist

<instructions>

Two frontmatter fields are load-bearing:

• name — lowercase, dashes, unique within your team. It becomes the folder name and the thing people say ("run the release checklist").
• description — the only text the agent sees before deciding to load the skill. Everything routes through this paragraph.

Supporting files (references/*.md, templates, scripts) sit next to SKILL.md and get read on demand — keep the main file lean and push long material out.

Write the description as a trigger, not a summary

The most common failure in the wild: descriptions that describe. "Guidelines for code review" tells the agent what the skill is; it doesn't tell it when to fire. Compare:

❌ "Guidelines and best practices for reviewing code."

✅ "Reviews diffs against our security checklist. Use when reviewing a pull request, when the user asks for a security pass, or before merging to main."

The second names the situations. Include the words a user would actually say — "review this PR", "security pass" — because matching happens against real conversation.

Write the body for a stranger

The agent reading your skill next month shares no context with you. Three rules keep instructions durable:

1. State decisions, not just steps. "Run the tests" is a step. "If tests fail, stop and report — never publish over a red build" is a decision rule, and decision rules are where skills earn their keep.
2. Make outputs concrete. "Summarize findings" invites improvisation. "Output a table: severity, file, line, suggested fix" produces the same artifact every time.
3. Name the boundaries. The strongest lines in any skill start with "never": never force-push, never skip the approval, never include credentials in examples. Agents respect explicit boundaries far more reliably than implied ones.

Structure that scales

For anything beyond a page, this shape holds up:

# <What this skill does>

## When to use / when NOT to use
## The procedure (numbered, with decision points)
## Examples (one good, one bad)
## Pitfalls (things that went wrong before)

The pitfalls section is criminally underused. Every time the agent misapplies the skill, write the failure into the file. A skill that accumulates its own incident history gets better every month — that is knowledge compounding, which is the entire point.

Mistakes that quietly break skills

• A BOM at the top of the file. Windows editors love adding an invisible byte-order mark before ---, which can make parsers miss the frontmatter entirely — the skill loses its name and description without any error. Save as UTF-8 without BOM.
• Giant single files. Agents handle a 100-line SKILL.md better than a 1,000-line one. Move reference material to references/ and link it.
• Secrets in examples. Real tokens pasted into example configs will eventually be distributed with the skill. Use obvious placeholders (YOUR_API_KEY) — and publish through a pipeline that scans for secrets anyway.
• Duplicating what the agent already knows. Explaining what git is wastes context. Skills should carry what's yours: your conventions, your thresholds, your exceptions.

Test it like you mean it

Before sharing a skill, open a fresh agent session and phrase a request the way a teammate would — not the way you would. If the skill doesn't trigger, fix the description. If it triggers but improvises, tighten the body. Two or three rounds of this is usually enough.

Then treat the file as a released artifact: version it, review changes to it, and distribute it from one source of truth rather than by copy-paste. That last part is what MasterSkills handles — publish once, and every teammate's agents install and update from the registry.