7.4
Build Your First Skill
Why this exists
You've read one, vetted six, installed one and changed it. Now you write one — and it should be for something you genuinely do more than once, because a skill for a task you don't have is an exercise, and exercises don't get used.
The idea
Find something you've explained twice. That's the skill.
The hard part isn't writing it. It's choosing. Good candidates share three traits:
| Trait | Why |
|---|---|
| You do it repeatedly | Otherwise it never fires again |
| It has a right answer | You can tell whether the output is good |
| You currently re-explain it | The explaining is the skill, already written badly |
That third one is the tell. Anything where you find yourself typing "same as last time, but…" is a skill waiting to be written down.
The writing is four moves:
Name and description. From 7.1 — the description is the trigger, and it's the only part that determines whether this ever runs. Write it as when, not what. "Use when the user asks to..." rather than "Formats things."
The steps. How you'd explain it to a competent person who's never done it. Numbered. Specific enough that two runs produce the same shape.
What good looks like. Same idea as the brief in 5.1 — describe the finished thing. Length, format, tone, what must be included. Without this you get output that's reasonable and wrong-shaped.
What not to do. The mistakes you'd otherwise correct every time. This is the section that saves the most effort and gets written least.
Write it from a real example. Not from imagination. Take something you produced recently that came out well, and describe how to make that. Skills written from an abstract idea of the task produce abstract output.
And the same rule as anything else you've built in this course: test it, then fix the source. Run it on something real, notice what you corrected by hand, and put that correction into the skill. Two rounds of that and it's genuinely useful. Skipping it leaves you hand-fixing the same thing forever.
Do
- List three things you've explained to Claude more than once. Use the list from 7.1 if you made one.
- Pick the one you do most often and that has a clear right answer.
- Find a real example of the output done well. You're describing how to make that.
- Write the skill file with four parts: - Name - Description — written as when to use it - Steps — numbered, specific - What good looks like + what not to do
- Install it.
- Test it on something real and let it run without steering.
- Note everything you corrected by hand.
- Put those corrections into the skill. This is the step.
- Run it again on fresh input. It should need less correction.
- Save as
my-first-skill.mdalongside a note of what changed between round one and round two.
Step 8 is where the value is. Round one always needs correction. The skill gets good because you feed the correction back rather than absorbing it.
Done when
Never do
Don't write a skill for something you do once. It'll never fire again and you'll have spent an hour on an exercise.
Don't leave your corrections in your head. If you fix the same thing by hand twice, that fix belongs in the skill. Otherwise you've built something that needs you every time, which is the opposite of the point.