/writing-skills

name: writing-skills
description: Use when creating a new skill, editing an existing skill, or verifying skills work before deployment

Writing Skills

Overview

**Writing skills IS Test-Driven Development applied to process documentation.**

A skill is behavior-shaping code, not prose. You write a failing test (a pressure scenario an agent gets wrong without the skill), watch it fail, write the minimal skill that fixes it, watch it pass, then close loopholes.

**Core principle:** if you didn't watch an agent fail without the skill, you don't know whether the skill teaches the right thing — or anything at all.

**The Iron Law:**

NO SKILL WITHOUT A FAILING BASELINE FIRST

This applies to new skills AND to edits of existing skills. "Simple addition", "just a section", "docs update" — all the same violation. Write the skill before testing it? Delete it and start over.

When to Use

• Creating a new skill for this repo (also read CONTRIBUTING.md — new

skills must be agreed in an issue first and ship with eval coverage)

• Editing any `skills/**/SKILL.md` content
• Reviewing a PR that changes skill content

**When NOT to use:** for project-specific conventions (those go in the team-ai-directives repo as CDRs), or for mechanical constraints a script or test can enforce — automate those, save documentation for judgment calls.

Core Process

RED — Baseline the failure

Run the scenario WITHOUT the skill loaded. Document verbatim:

• What the agent actually did
• The exact rationalizations it used to skip the correct behavior
• Which pressures triggered the failure (time, sunk cost, authority, "it

works either way")

If the agent already behaves correctly without the skill, **stop — there is nothing to fix.** A skill that enforces behavior that comes for free is context noise (this repo exists to fight context noise, not add to it).

GREEN — Write the minimal skill

Start from the template (`templates/SKILL-template.md` in this directory). Address only the failures you observed in RED — not hypothetical ones.

Run the same scenario WITH the skill. The agent should now comply.

REFACTOR — Close the loopholes

New rationalization found? Add an explicit counter, re-test. Loop until bulletproof under pressure.

Micro-test wording before full scenarios

Full pressure runs are slow. Verify wording cheaply first: one fresh API/subagent call per sample, 5+ reps per variant, always including a no-guidance control. If the control doesn't exhibit the failure, there is nothing to fix. Read every flagged match manually — automated counts overstate both failure and success.

Structure Rules (this repo)

| Rule | Why | |------|-----| | Exactly 2 levels deep: `skills/<domain>/<skill>/SKILL.md` | Enforced by `test_skill_directory_depth`; resolves the `skills` CLI depth limit | | Frontmatter: `name` + `description` required (≤1024 chars total) | Enforced by `test_skill_description_presence_and_length` | | Optional `scripts:` (`sh:`/`ps:`) and `disable-model-invocation: true` | Mark skills that must not be model-invoked | | Description = trigger only | See below — the single most common way skills silently break | | Headings: `Overview` → `When to Use` → `Core Process` → `Red Flags` → `Verification` | Canonical shape; `Configuration` only if the skill has knobs | | Token budget: aim <500 lines for the SKILL.md body (enforced: warn >500, fail >800 — see test_skill_token_budget) | Heavy reference → `references/`; scripts → `scripts/{bash,powershell}/` | | New skills ship with eval coverage | Goldset criterion + binary grader (`{"pass": bool, "score": 1.0\|0.0}`) — see `evals/promptfoo/` |

Skill Discovery Optimization (SDO)

The `description` is the trigger surface: `factory-mission` hands every skill's name+description to its subagents, and the model decides what to load from that list.

**Description = when to use. NEVER what the skill does.**

Measured failure mode (see superpowers' writing-skills, which this skill adapts): when a description summarizes the workflow, agents follow the *description* instead of reading the skill body — a description saying "code review between tasks" produced one review where the skill's flowchart clearly required two.

# BAD: workflow summary — agents will follow this shortcut
description: Bootstraps the session by injecting the team context index and pulls rules on demand

# GOOD: trigger only
description: Use when a session starts and the team AI directives context is not yet loaded

• Start with "Use when…" and name concrete symptoms and situations
• Third person (it is injected into prompts)
• Keywords an agent would search for: error messages, symptoms, tool names
• Skills with `disable-model-invocation: true` are exempt (not routed by

the model) but must still not mislead

Match the Form to the Failure

Before writing guidance, classify the baseline failure. The form that bulletproofs one failure type backfires on another.

| Baseline failure | Right form | Wrong form | |---|---|---| | Skips a rule under pressure (knows better, does it anyway) | Prohibition + rationalization table + red flags | Soft guidance ("prefer…", "consider…") | | Output has the wrong shape (bloated, buried verdict) | Positive recipe: state what the output IS, its parts in order | Prohibition list ("don't restate", "never narrate") | | Omits a required element | Structural: a REQUIRED slot in the template | Prose reminders near the template | | Behavior depends on a condition | Conditional on an observable predicate | Unconditional rule + exemption clauses |

No nuance clauses either way: "don't X unless it matters" reopens negotiation; a single nuance clause on a winning recipe degrades it.

Bulletproofing Discipline Skills

For rule-enforcing skills, close every loophole explicitly: forbid the specific workarounds ("don't keep it as reference — delete means delete"), add the foundational principle early ("violating the letter of