Writing an agent skill in this house style

A skill is not a tutorial and not an API reference. It is the note you would leave for the next person about to lose two days to the same thing. Everything in the format follows from that.

The shape. Frontmatter, a short orientation, a Traps section taking most of the file, then Verifying it. Roughly 60–140 lines. Orientation exists only to make the traps legible.

The description does two jobs — when to load the skill, and what symptom the reader is staring at, so the match happens on the error rather than the topic. The exemplar in the mined repository ends its description "…or hitting ImageVector/Painter type errors": that last clause is the one that fires when somebody is confused rather than curious.

Teach how to verify a value, never list values that go stale. The same exemplar sends readers to the upstream code-point list rather than listing names. A list goes stale; a procedure does not.

The Traps section is the product. Each trap opens with the wrong move in bold, then what happens, then what to do instead — so a reader scanning bold lines finds their own situation.