What Makes a Good Skill

Before we build a skill, we ask three plain questions. Not a form — the ones that decide whether the thing should exist:

• What happens without it? Show the actual result, don't describe it. If it already comes out fine, stop — the best skill is the one you didn't need. This one question cancels most ideas, and it is meant to.
• What happens with it? Show that too, side by side. If the two look the same, the skill changes nothing — a costume (we come back to this below).
• Does someone already do this? If a skill next door already covers the moment, don't build a twin — sharpen the neighbour instead.

A skill earns its place only when the "without" is visibly worse than the "with", and nothing already closes that gap. Everything after this assumes you cleared that bar.

Think of a skill as a good habit you hand to the assistant. "When someone asks you to write a commit message, do it this way." "When you touch a chart, use the house colours." The assistant already knows a great deal; a skill is a nudge that makes it do a specific thing the way you want it done — consistently, without being reminded each time.

Which means a skill only earns its keep if two separate things are true. Miss either and it is dead weight, however good it looks.

• It shows up. The right request arrives and the skill is reached for automatically — and, just as important, an unrelated request that only looks similar leaves it asleep.
• It changes the outcome. Once it shows up, the result is actually better than it would have been without it.

Here is the part that surprises everyone. The thing that decides whether a skill shows up is not its cleverness. It is one short paragraph — the description — written in plain language, that tells the assistant when to reach for it.

A good description does one job: it routes. It says, in the words a real person would use, "reach for me when the task is X." It names the moments — "when writing a commit", "when converting sizes to scale with the font", "when someone asks what tools exist for this." It does not ramble about how the skill works inside. Nobody reaching for a tool needs its schematics; they need to know it is the right tool.

The most common way a skill fails is quiet and expensive: a description written too broadly, so the skill wakes for a thousand requests that were never its own — forever, in the background, slowing everything and helping nothing. A description that is too shy merely goes unused. A description that is too greedy is a leak that never stops. Aim narrow. Name the real moments; name a near-miss it should ignore.

This is the trap, and it is worth stopping on. A skill can appear flawlessly, every single time, and change nothing — a costume the assistant wears over what it would have done anyway. It looks busy. It looks adopted. It is hollow.

So we never trust "it fired" as proof it worked. We check the second thing separately: we run the same real task twice — once with the skill, once without — and compare the two results honestly, without telling the judge which was which. If the output is no better with it than without it, the skill is a costume, and no amount of "it fired reliably" redeems that. A skill has to earn its place by changing the answer.

One more thing separates a skill you would publish from one you would only keep to yourself. When someone installs your skill, its instructions run in their assistant, on their work. So before anything ships, every skill is walked through an eight-point safety check — could it be tricked, could it leak something, could it run something it shouldn't. A skill that cannot pass that walk does not go out, no exceptions. Publishing is a promise: this is safe to let into your work.