Skills that argue back

Most skills read like a recipe card. Preheat, mix, bake, done. They give the agent the steps in order and stop there, as if the hard part of any real job were remembering the sequence. It never is. The hard part is the fork in the road the recipe doesn't mention — the moment two reasonable moves diverge and only one of them is the move you'd actually make. A skill that stays silent there hands the decision back to a model guessing at your taste. A skill that has already decided, and says so, is worth ten of them.

That is the whole difference between a checklist and a skill worth signing. A checklist is neutral by design; it works for anyone, which is another way of saying it works for no one in particular. The skills people keep are the opposite. They have a spine. They say never do this, always do that, and here is why — and when the agent drifts, or the user leans on it, the file pushes back.

Opinions are compressed experience

An opinion in a SKILL.md is not a mood. It is a scar. "Never mock what you own" is four words standing in for a hundred afternoons lost to tests that passed against a fake and failed against production. "Extract a variant after the third repeat, not the first" is someone's whole aesthetic about premature abstraction, folded flat. Every strong instruction is a decision you already paid for, written down so the agent doesn't pay for it again.

This is why the neutral version is worthless even when it is technically correct. "Consider your mocking strategy" is true and useless. It offloads the exact judgment the reader came for. The instruction that names a default — do this, not that — is the compression of experience the model cannot reconstruct on its own, because the model never lost the afternoon.

So when you catch yourself writing a line any competent engineer would nod along to, stop. Agreement that costs nothing teaches nothing. The lines that earn their place are the ones a reasonable person could argue with — and that you would argue back.

"It depends" is a cop-out inside a SKILL.md

Everything depends on something. That is true, and it is also the laziest sentence in technical writing. "It depends" is what you say when you know the answer and don't want to be caught being wrong. Inside a skill it is worse than useless, because the reason the skill exists is to make the call the reader can't yet make. Handing it back to them defeats the file.

The fix is not false certainty. It is picking the default out loud and naming the case where it breaks. "Use the boring database until you have a measured reason not to" depends on plenty — scale, team, workload — and still commits. It tells the agent where to start and trusts it to spot the exit. That is honest. "Choose the right database for your needs" is not honesty, it is abdication wearing a tie.

A skill that refuses to decide has outsourced the only thing it was hired to do.

Confidence is not the same as dogma. You can name a tradeoff and still take a side. What you cannot do, if you want the file to be worth installing, is survey the options neutrally and leave. Nobody installs a survey.

Constraints that survive being questioned

A strong constraint is not one nobody challenges. It is one that has already been challenged and held. When you write "never do X," assume the sharpest reader you know is standing over your shoulder asking why — and if your only answer is "it's cleaner" or "best practice," the constraint isn't ready. It hasn't survived a question yet, which means it will fold the first time an agent or a user leans on it.

The constraints worth encoding come with their reason attached, because the reason is what makes them portable. "Never touch markup you can't see rendered" travels because the why is obvious the moment you read it — you cannot judge a change you cannot observe. The rule and its justification arrive together, so the agent can apply it to cases you never listed. A bare rule with the reasoning stripped out is a superstition, and models, like people, discard superstitions the moment they turn inconvenient.

This is also the test for your own drafts. Read each line and ask: if the agent pushed back on this, could the file answer? If the answer lives only in your head, the skill is incomplete. Put the argument in the file. That is the part that argues on your behalf when you are not in the room.

Encode the default, then the escape hatch

The failure mode on the other side is the rule with no exit — the skill so opinionated it breaks the moment reality doesn't match the author's Tuesday. A good opinion is not a cage. It is a strong default plus the named condition under which you abandon it. The default carries the ninety percent case. The escape hatch keeps the file honest about the other ten, without dissolving back into "it depends."

Here is the shape. One of these instructs; the other decorates.

# Limp
Handle errors appropriately and log where useful.

# Opinionated, with an escape hatch
Let it crash. Do not catch an exception you cannot act on —
an unhandled error with a stack trace beats a swallowed one
with a shrug. Catch only at a boundary where you can retry,
translate, or report to a human. If you are wrapping a call
in try/except and the except body only logs, delete it.

The second one has a point of view and still tells you when to break it. It does not pretend there is never a reason to catch — it names the reason precisely, so the agent can tell your boundary from its own laziness. That is the craft in one line: strong enough to steer, specific enough to know its own edges.

The file that pushes back

The reason all of this matters is drift. An agent left with a neutral checklist drifts toward the mean — the most generic plausible output, the code that could have been written by anyone, which is exactly the code the labs already generate for free. A skill with opinions is a rail against that drift. When the agent starts sanding your sharp choice down into a safe one, the file is there in writing, holding your side. When the user asks for the thing you know is a mistake, the skill has already said why, before the mistake gets made.

That is what people are installing when they install yours. Not the steps — the steps are cheap, the model half-knows them already. They are installing the argument: the set of calls you have made and are willing to defend. The skills that get kept for years are the ones with a person clearly behind them, refusing to be generic on the reader's behalf.

So write the opinion down. Name the default, name its exit, and set the reason next to the rule so the file can hold the line when you are not there to. The people who bounce off your sharp edges were never going to stay. The ones who keep it are keeping you.