Building Claude Skills: a complete guide

A Skill is the smallest unit of reusable expertise you can hand Claude. It is a single Markdown file: a few lines of metadata, then a system prompt that turns a general model into a specialist. Done well, it is the difference between "write me a cold email" and a sequence that references the prospect's actual website.

This guide covers the anatomy, the rules that make a Skill fire reliably, and the mistakes that quietly break them.

What a Skill actually is

A Skill is a .md file with YAML frontmatter and a body. The frontmatter tells Claude when to use it; the body is the instruction set.

---
name: cold-email
description: Use when the user wants outbound sales emails or
  cold outreach sequences. Loads proven frameworks (AIDA, PAS, BAB).
---
 
You are a senior outbound copywriter. When given an offer and a
prospect, produce three distinct angles, each under 120 words,
each with exactly one call to action.
 
## Rules
1. Reference something specific about the prospect.
2. Never use the words "synergy", "leverage", or "circle back".
3. End with a single, low-friction ask.

When Skills fire (and when they don't)

Claude matches the user's intent against every Skill's description. Vague descriptions ("helps with marketing") collide with each other and routing becomes a coin flip. Specific descriptions ("use when drafting outbound cold emails") win.

• Good: "Use when reviewing a contract or NDA for risk."
• Bad: "Legal helper."

The five mistakes that kill a Skill

1. Burying the trigger. If the description describes the output instead of the situation, routing degrades.
2. Writing an essay. A Skill is a system prompt, not documentation. Keep it tight.
3. No refusals. Tell the Skill what not to do. Constraints make output predictable.
4. Mixing two jobs. One Skill, one outcome. Split anything that does two things.
5. No examples. One worked example in the body anchors tone better than three paragraphs of adjectives.

A reusable template

---
name: <kebab-case-id>
description: Use when <specific situation>. <What it produces>.
---
 
You are <role>. <One-line mission>.
 
## Process
1. ...
2. ...
 
## Constraints
- Never ...
- Always ...
 
## Example
Input: ...
Output: ...

Ship that, drop it into Claude, and you have repeatable expertise on tap.