Writing Skills

A skill is executable operational guidance. Treat changes to it like behaviour changes: specify the outcome, observe failure, make the smallest effective instruction change, and prove the new behaviour under pressure.

Define the contract

1. State the concrete problem, intended outcome, triggers, non-triggers, prerequisites, outputs, and failure or escalation paths.
2. Inspect the existing skills and the repository conventions before adding a new boundary. Extend an existing skill when it already owns the behaviour.
3. Use a lowercase kebab-case directory and a canonical SKILL.md. Add YAML frontmatter whose name matches the directory exactly and whose description states observable trigger conditions, not a vague summary.
4. Keep the canonical workflow agent- and model-agnostic. Describe capabilities and outcomes instead of hard-coding a harness, model, tool name, or operating system. Put harness integration in adapters/.
5. Write direct steps an agent can execute and results it can verify. State each rule once, in one place, in plain words. Current models follow instructions closely: capitals, repeated rules, and long warnings make them over-cautious and slow, not safer.
6. Keep the main workflow concise. Move detailed schemas, briefs, and contracts into directly linked, one-level-deep references/ files.

Bound every loop

An instruction set that only adds rigour does not converge. Any skill containing a repeat-until step needs all four:

• A blocking threshold - which findings actually stop progress, and which are recorded without stopping it.
• A narrowing scope - later rounds verify the previous round and the new delta rather than re-reading everything with fresh eyes.
• Memory across rounds - a durable record of what is already settled, so a later round cannot silently reverse an earlier one.
• A round budget and an escalation path - a hard count, then stop and ask the user.

A gate that never closes costs as much as a gate that never opens. Every extra round, dispatch, and repeated check run must earn its cost in caught defects.

Harness wiring

Canonical files stay portable; adapters do the wiring. When adapting for a harness, use what it actually offers instead of restating a procedure in prose:

• Agent definitions with a restricted tool list, so "dispatch a fresh reviewer" is a name rather than an improvised prompt. Do not pin a model; workers inherit the session's model.
• Invocation control - restrict a side-effecting skill to explicit user invocation; mark pure background knowledge model-only.
• Tool restriction in the skill's own frontmatter, so a read-only skill is enforced read-only rather than merely asked to be.
• Dynamic context injection for the facts a skill would otherwise spend its first tool calls discovering - the current branch, the working-tree status, the in-flight state file.
• Isolated execution when a skill's whole job is to run in a fresh context and hand back a conclusion.
• Prompt-time hooks to put a routing gate in front of the model every turn, and pre-action hooks to hard-block what a prose rule can only forbid.

An adapter wires; it does not restate. It points at the canonical file and adds only what the harness needs. Duplicated procedure drifts.

Preserve provenance

Before adapting external material, record its repository, author or organisation, exact revision, license, retained behaviour, removed assumptions, and material rewrites alongside the project's other attribution records. Do not copy or adapt material whose license does not permit redistribution. Preserve required notices.

Validate behaviour

For each new or materially changed behaviour, create realistic scenarios that exercise the trigger and the strongest likely rationalisations:

1. Red: Run or evaluate the scenario without the proposed instruction. Record the observable failure or bypass. If the agent already behaves correctly, strengthen the scenario or prove the instruction unnecessary.
2. Green: Add the minimum instruction that prevents the observed failure. Run the same scenario and record exact evidence of compliance.
3. Refactor: Remove repetition and ambiguity without weakening enforcement. Rerun the green scenario.
4. Pressure: Test plausible excuses - task size, urgency, a prior agent's claim, unavailable context, partial success, conflicting convenience. The skill must hold its gates and use its escalation path.
5. Convergence: For any loop, test that it ends. Feed it a stream of low-severity findings and confirm the round budget, the threshold, and the memory stop it rather than letting it grind.
6. Boundaries: Test a non-trigger scenario and the interaction with adjacent skills. The skill must neither activate too broadly nor contradict its owning workflow.

Do not accept prose review as behavioural validation when the behaviour can be simulated. Record the scenarios, the observed results, and any unresolved portability limits. Never claim compatibility with a harness that was not tested.

Structural checks

Before completion:

• verify the frontmatter name, the directory name, headings, and code fences;
• resolve every relative link;
• search the canonical files for accidental harness-specific instructions;
• check that every state has a success, retry, blocked, or escalation path;
• confirm the examples match the documented repository and runtime layouts;
• read the skill as an agent with no conversation history;
• update the guide in ../../docs/development-workflow/ in the same change when a workflow skill's phases, loops, gates, or artifacts changed.

Apply the evidence gate in development-workflow before claiming the skill is ready.