bfollington 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.
Skills exist at many altitudes and all are legitimate: specific knowledge, specific practice, mental models, techniques, principles, abstract processes. What they share is not scope but density.
They are index cards in a network, not chapters in a manual. Written to compose — because two loading together should sharpen each other rather than repeat. Where one skill's subject genuinely adjoins another's, name the neighbour and let it own its half rather than restating it badly.
The description is the skill
The frontmatter description is what decides whether the skill is ever loaded. Prose about the topic wastes it.
It needs the situation, in the words that situation actually arrives in — and the negative case, explicitly. Without a stated boundary a skill fires everywhere, becomes noise, and gets turned off. A skill that never fires and a skill that always fires are both dead; the second also damages everything around it.
Structure that fits in the head
Headings should be readable as an argument on their own, in order. Someone skimming only the headings should come away with the shape.
Prose over bullets for reasoning — bullets fragment argument into assertions and lose the because. Bullets for genuine lists: failure modes, categories, things to look for.
One worked example, concrete and specific, beats three abstract ones. Show the artifact — the actual report, the actual shape — rather than describing what it should contain.
End with failure modes. They are the highest-density part of any skill: each one names a trap that is invisible from inside, and they are what makes a skill act as a check rather than a nudge.
Calibrate against reality
A skill claiming to fire on every task, or one written for a situation that has come up once, are the two ends of the same error — it was written from imagination rather than from what actually happens.
Write from real friction. The skill worth having is the one that would have prevented a specific thing that went wrong, more than once.
When revising: prefer cutting to adding. The instinct after a failure is to append a clause covering it, and a few rounds of that produces something long, hedged, and no longer sharp. Ask instead whether the original principle, stated better, would have covered it.
Failure modes
- Procedures. Numbered steps for something an agent can already sequence.
- Restating the obvious. Content that would have been produced anyway, crowding out content that would not.
- Vague triggers. A description with no negative case, so it fires constantly and gets disabled.
- Two skills in one. "And also" in the summary. The trigger is now blurred for both.
- Bullet soup. Assertions stacked with the reasoning removed, so nothing is persuasive.
- Accretion. Grown by appending caveats, never re-cut. Long, hedged, unmemorable.
- Imagined use. Written for a situation that has not actually occurred.
- No boundary. Nothing stating what this is not for, or which neighbouring skill owns the adjacent ground.