Writing your first skill

You know when to use a skill. Building one is almost anticlimactic — until you hit the one part that actually matters.

A skill is just a folder with a SKILL.md file inside. The make-or-break is one line: the description.

A SKILL.md opens with a little header — a name and a description — then plain-text instructions below it:

---
name: pr-description
description: Use when writing a pull request description. Summarizes the
  change from the commits and fills in the team's PR template.
---

When asked to write a PR description:
1. Look at the commits on the branch.
2. Group them into a short summary and a "what changed" list.
3. Fill in the template in .github/pull_request_template.md.

The instructions are the easy part — they’re just how you’d explain the job to a person.

The description is the matcher, not a label

Here’s the part that trips people up. It’s tempting to write the description like a title: “PR description helper.” That’s useless — Claude has nothing to match against.

The description is the only thing Claude reads when deciding whether to reach for the skill. It has to answer one question: when should this fire?

So you write the situations in: “Use when writing a pull request description…” Now, the moment you say “write up this PR,” it matches.

The description isn’t documentation for a human browsing a list of skills. It’s the trigger. Write it for when, not what.

If your skill never fires

Almost every “my skill doesn’t work” problem is the same problem: the description doesn’t describe the situation. Claude never matched it, so it never opened it.

The fix is always the same — rewrite the description to name the moments it should kick in, in the words you’d actually use when that task comes up.

(You don’t even have to write skills by hand — there’s a skill for making skills. But understanding what makes one fire is the part worth keeping in your head.)

What’s next

That’s the “package knowledge” half of this level. The rest is about time — doing independent work all at once instead of one piece after another. Start small: parallel tool calls.