The two sections of a SKILL.md
A SKILL.md has exactly two parts: YAML frontmatter (metadata between two --- lines) and the markdown body (the instructions). Here's a complete example:
--- name: code-reviewer description: Reviews code for security, performance, and correctness issues. Use when reviewing a pull request, diff, or file. --- # Code Reviewer You are a senior engineer doing a focused code review. ## Process 1. Security first (injection, auth, secrets). 2. Then correctness, performance, and maintainability. ## Output Group findings by severity with a concrete fix for each.
The frontmatter fields
| Field | Required | Purpose |
|---|---|---|
| name | Yes | Kebab-case identifier, max 64 chars. Should match the skill's folder name. |
| description | Yes | What the skill does and when to use it. Claude reads this to decide when to load the skill. |
The description is the most important line
Claude loads a skill based on its name and description, not its body. A precise description that says what the skill does and when to apply it is the single biggest factor in whether your skill triggers reliably.
The instructions body
The markdown body is where you teach Claude the task. Effective bodies share a few traits: a clear process, an explicit output format, and rules that explain why - because Claude generalizes better from reasons than from rigid commands. Examples of good output steer behavior more than abstract instructions.
- Process: the steps to follow, in order.
- Output format: exactly how the result should be structured.
- Rules and constraints: what to always or never do, with the reason.
- Examples: before/after or sample output to anchor the style.
Reference files and scripts
Beyond SKILL.md, a skill can bundle reference files (e.g. references/style-guide.md) and scripts. Keep the SKILL.md focused and point to these for detail, so Claude loads the heavy material only when needed. You can see this pattern in the Skill Library templates.
Ready to build one? Follow the step-by-step guide to creating a skill, or generate a complete SKILL.md with MakeMySkill.