writing-skillslisted

# Writing Skills ## Overview **Core principle:** A skill earns its place by changing what a future agent *does*, not by describing what you already know. If an agent would behave correctly without the skill, the skill is noise. So the test comes first: watch the wrong behavior happen, then write the smallest skill that fixes it. A skill is a **reusable technique, persona, or reference** — not a story about the one time you solved something. If it reads like a diary entry, it's not a skill yet. ## Write the Failing Case First ``` NO SKILL WITHOUT FIRST SEEING THE BEHAVIOR IT FIXES ``` 1. **Run the scenario without the skill.** Give a fresh agent the task that should trigger it. Watch what it actually does. Write down the exact wrong move and the exact rationalization it used. 2. **Write the minimal skill** that addresses *that* failure — not every hypothetical cousin of it. 3. **Run the scenario again with the skill.** Confirm the behavior changed. If it didn't, the wording is too soft or too abstract — tighten it against the real rationalization, not an imagined one. 4. **Record the scenario** in the skill's `evals/` — the triggering prompt plus the expected-behavior bullets (format and runner: `EVALS.md`). That baseline is what proves the *next* edit still works. A skill with no recorded failing case is a claim no one can re-check; evals are the source of truth, not the prose. Skipping this is the cardinal sin. "It's obviously clear" is how unused skill