Authoring Skills

A skill is not instructions. It is an index card of crystallized wisdom — the principle distilled, with just enough specifics woven in that it lands.

The measure: does reading it change how the situation is seen, before anything is done? A skill that only tells an agent what steps to take has failed, because an agent that needed the steps will follow them badly and one that did not needed nothing.

Aim at intuition, not compliance. The good skill produces the way the user is talking about this makes me want to think like this.

Say the thing that is not already known

Most of what could be written in a skill, a capable agent already knows. Restating it costs context and teaches nothing, and — worse — dilutes the parts that are not obvious until nothing stands out.

So the test for every line: would this have been done anyway? If yes, cut it. What remains is the actual content: the reframe, the non-obvious ordering, the failure mode that is invisible from inside, the distinction that dissolves a confusion.

This is why skills get shorter as they get better. The first draft contains the subject; the final draft contains only what is surprising about it.

One subject

A skill answers one question and fires in one kind of moment. When it needs "and also", it is two skills, and both are weaker for the merge — the trigger becomes vague, and the reader gets one relevant half and one irrelevant one.