writing-good-skillslisted

# Writing Good Skills ## Overview The craft layer of skill authoring: what a well-written SKILL.md looks like. For the *process* (baseline test → write → close loopholes), **REQUIRED SUB-SKILL:** superpowers:writing-skills — not repeated here. Core principle: **prose cannot enforce prose.** A model that under-executes instructions also under-executes the instruction to try harder. Every check below moves weight off goodwill and onto structure. Baseline-tested 2026-08: two competent agents writing skills naturally both failed checks 1, 3, and 5. Those are the defaults you are correcting. ## The seven checks **1. Description = symptoms only. Zero workflow.** List the situations and phrasings that should trigger the skill; never what it does. Why: agents treat a workflow summary as the skill and skip the body (verified in superpowers testing). **2. Every hard rule carries its why, in one line.** "Write gates to a file — intentions don't survive a long context; files do." Why: a bare imperative gets rationalized away under pressure; a rule with visible logic can't be dodged as "spirit vs letter." **3. If an outcome is observable, name the artifact that proves it.** A file the agent must write, a command whose output decides, a template to fill — never "make sure X." Why: a check replaces tokens of self-assessment with a free subprocess, and evidence can't drift the way a promise can. **4. Absolute rules need an honest exit.** A visible way to surrender a requirement, wit