writing-skillslisted

# Writing Skills Writing a skill IS TDD on process documentation: watch an agent fail the task WITHOUT the skill (RED), write the skill against those exact failures (GREEN), close the loopholes it then invents (REFACTOR). If you never watched it fail without the skill, you don't know the skill teaches the right thing. Vendored from [obra/Superpowers](https://github.com/obra/Superpowers) (MIT, Jesse Vincent), compressed to house style per `[[vendored-skill-compression]]`. **REQUIRED BACKGROUND:** superpowers:test-driven-development defines the RED-GREEN-REFACTOR cycle this adapts. ## Authoring contract lives in one canonical place Ordered-by-weight bullets, the behavior-anchored `description` template, description-SDO (WHEN not WHAT), and "match the form to the failure" are the house authoring contract — see `[[skill-authoring-contract]]`, don't restate them. Token-efficient prose style: `[[instruction-compression-playbook]]`. This file covers only what's specific to *creating + testing* a skill. ## What a skill is A reference guide for a proven technique, pattern, or tool — reusable, not a narrative of how you solved something once. Three shapes: - **Technique** — a concrete method with steps (`condition-based-waiting`, `root-cause-tracing`). - **Pattern** — a way of thinking about a class of problem (`flatten-with-flags`). - **Reference** — API/syntax/tool docs. ## When to create one - Create when: the technique wasn't obvious to you, you'd reuse it across projects