The definitive guide to writing Claude skills that are razor-sharp, deeply effective, and built to trigger reliably. Use this skill whenever you need to create, draft, or improve a SKILL.md file for Claude — whether from scratch, from a conversation workflow, or from a vague idea. Also use when someone says 'make this into a skill', 'write a skill for X', 'help me build a Claude skill', or wants to capture any repeatable Claude workflow into a reusable skill. This skill teaches the craft of skill-writing itself — the meta-skill.
You are about to write a Claude skill. Not a mediocre one. Not a "pretty good" one. You are going to write a skill so precise, so well-structured, and so deeply considered that the agent reading it will execute with the focused intensity of someone four hours into a flow state.
Every sentence earns its place. Every instruction lands clean. This document is your complete playbook.
A skill is a markdown file (SKILL.md) that acts as a runtime instruction manual injected into Claude's context when triggered. It transforms Claude from a generalist into a specialist — temporarily giving it deep expertise, opinionated workflows, and battle-tested patterns for a specific domain.
Think of it like this: Claude without a skill is a brilliant generalist. Claude with a skill is that same generalist who just read the best playbook ever written on exactly this topic, moments before starting work.
my-skill/
├── SKILL.md ← The brain (required)
│ ├── YAML frontmatter ← Name + description (triggers the skill)
│ └── Markdown body ← The actual instructions
├── scripts/ ← Executable code for deterministic tasks (optional)
├── references/ ← Deep-dive docs loaded on demand (optional)
└── assets/ ← Templates, fonts, icons, etc. (optional)
Skills load progressively to stay efficient:
name + description from YAML frontmatter. Always in Claude's context. This is what triggers the skill.The implication: your SKILL.md needs to be dense, precise, and under 500 lines. If you're going longer, push detail into references/ files and point to them.
Before writing a single line of markdown, answer these questions.
The description field is the sole mechanism that determines whether Claude uses your skill. If the description is weak, your brilliant instructions never get read.
Claude errs on the side of not using skills. Include:
references/.Help Claude understand the user's mental model, not just the task.
Name and shame generic, low-effort patterns. Surprisingly effective.
Give Claude permission to deviate when appropriate. Rigid skills produce brittle outputs.
Write 2-3 realistic test prompts. Check:
| Mistake | Fix |
|---|---|
| Vague description | Be pushy and specific with trigger words |
| Over-reliance on MUST/ALWAYS/NEVER | Explain the why instead |
| No examples | Show good vs. bad output |
| Monolithic 800-line SKILL.md | Split into SKILL.md + references/ |
| No anti-patterns section | Name the slop, shame the slop |
| Missing escape hatch | Give permission to deviate with justification |
| No completion criteria | Define the finish line explicitly |