What Makes A Skill Good

Time: 35 minutes
You'll end up with: A second, better version of your own skill

Why this exists

Your skill from 7.4 works. This lesson is about the gap between works and good, because that gap is where all the value is — and it's a gap you can close deliberately rather than by accident.

The idea

A good skill produces the same quality output on a bad day as a good one. That's the entire test.

Anyone can write instructions that work when they're paying attention. The point of a skill is that it works when you're not — pasted into a rushed session, run on odd input, used by someone who wasn't there when you wrote it.

Four things separate the two:

Specificity. The most common weakness by a distance. "Write a professional summary" produces something different every time because "professional" isn't a specification. "Five bullets, under fifteen words each, no adjectives, lead with the number" produces the same thing every time.

A worked example. One example of good output in the file is worth three paragraphs describing good output. It removes ambiguity you didn't know was there — the reader stops guessing at your standards and copies them.

Explicit failure modes. "Don't do X" only appears in skills that have been used. A skill with no such section is one that hasn't met reality yet, and every correction you make by hand is a missing line.

The description matches reality. From 7.1, still the thing that decides whether it runs at all — but there's a second failure: a description that's too broad fires when you didn't want it. Both directions cost you.

Weak	Strong
"Formats reports"	"Use when asked to turn raw metrics into a weekly summary"
"Write it professionally"	"Five bullets, max 15 words, lead with the number"
No example	One example of good output
No don'ts	The four things you always end up correcting

The test that settles it: give the same skill and the same input to a fresh session and see whether the output matches what you got before. If it drifts, the skill is under-specified and the drift shows you exactly where.

One thing worth naming: length is not quality. A long skill full of vague instruction is worse than a short one with a worked example. The measure is whether the output is predictable, not whether the file is thorough.

Do

Take your skill from 7.4.
Run it on identical input in two fresh sessions. Save both outputs.
Compare them. Every difference is a place the skill doesn't specify enough. List them.
Fix the biggest one by replacing a vague instruction with a specific one — counts, formats, limits.
Add one worked example of good output to the skill file.
Add a "what not to do" section from every correction you've made by hand across both lessons.
Check the description in both directions: would it fire when you want it, and would it fire when you don't?
Run the two-session test again. The outputs should now match.
Save as my-skill-v2.md and write three lines on what changed and why.

Step 2 is the whole method. You can't fix drift you haven't seen, and one run never shows it.

Done when

Two fresh sessions produce matching output from the same input.
Every vague instruction has been replaced with something countable or specific.
The file contains one worked example of good output.
There's a "what not to do" section drawn from real corrections.
The description fires when you want it and not when you don't.

Never do

Don't judge a skill on one run. One run tells you it works. Two fresh runs tell you whether it's specified. They're different questions and only the second one matters.

Don't confuse long with good. A short skill with a worked example beats a long one full of adjectives. Predictable output is the measure, not thoroughness.