writing skills

• a skill is a reusable technique, not a war story. narratives of how a problem was solved once are the anti-pattern.
• discovery is the first design constraint. the frontmatter description states when to use — triggers, symptoms, situations — and never summarizes the workflow: tested behavior showed agents follow the description instead of reading the body when it contains a shortcut. names are verb-first and active.
• match the form to the failure. a discipline failure (knows the rule, skips it under pressure) needs prohibition + rationalization table + red flags. a wrong-shaped output needs a positive recipe stating what the output is. prohibition lists on shaping problems produced more of the unwanted content than no guidance at all.
• no nuance clauses. "Don't X unless it matters" reopens negotiation; real exceptions become their own conditional on an observable predicate.
• test before deploy, every edit. the iron law — no skill without a failing test first — covers edits and "simple additions" too.

untested skills always have issues: the author's clarity doesn't transfer, and agents find loopholes the author never imagined. the failure is measurable — an untriggered description means the skill is never loaded. baseline testing is the only way to capture the verbatim rationalizations an agent actually uses ("they obviously want it merged"), and those exact phrases are what the counter-table must name to work. without the failing test first, the skill's wording is speculation deployed to production behavior.

• wrote the skill before testing? delete it, start over.
• micro-test wording (fresh-context reps against a no-guidance control) before full pressure scenarios.
• one excellent example beats five mediocre ones; keep token weight low — frequently loaded skills earn brevity.

creating or editing any skill, and before deploying skill changes — deploying untested skills is deploying untested code.

bad

skill rule: always write clean code

no trigger, observable boundary, or way to expose a loophole. an agent either skips it (nothing says when it applies) or interprets "clean" by its own taste — the rule changes nothing while appearing covered. untested, the loophole surfaces in production, and each failure gets patched with another untested sentence rather than a scenario that proves the fix.

good

trigger: before editing a code file
action: read its JSDoc heading
failure: stop when the heading is missing or says do not edit

exercisable against a concrete agent response: trigger, action, observable failure give every edit a red-green cycle — the baseline run shows the violation, the counter run shows it gone. the skill accumulates only guidance that survived testing, so its token weight stays earned.

mdx authoring · document frontmatter