Skip to main content

Skill development & testing

How a repeated task becomes a tested, versioned agent skill. Skills are the compounding asset of RAPID — capabilities we invoke, not reinvent — and this playbook is the path from "I keep pasting this prompt" to a registry entry another squad can trust.

The signal​

The same prompt pasted three times is the signal. Once is a task, twice is a coincidence, three times is a skill waiting to be written. The threshold is deliberately low and deliberately concrete — "would this be useful?" invites speculation; "have we actually done this three times?" invites evidence. Speculative skills (built for imagined demand) are the failure mode: they rot unused while carrying maintenance cost.

Write the spec first​

Copy the skill spec template to skills/<name>/spec.md and fill every section before building:

  • Trigger — the repeated task it replaces, stated so the next person recognises it.
  • Inputs → outputs — precise shapes; downstream steps depend on them.
  • Procedure — deterministic where it can be; honest about where it uses judgement.
  • Guardrails & permissions — least privilege per the guardrail standard; anything irreversible is out of scope — the skill prepares, a human authorises.
  • Failure modes — known ways it goes wrong and how each is caught.

If the spec is hard to write, the skill isn't ready — usually the task isn't actually repeatable yet, which is worth discovering before the build, not after.

Build against golden scenarios​

Write the golden scenarios before the skill, exactly as test-first works for code: fixed inputs, expected outputs, a pass criterion per scenario, fixtures stored in skills/<name>/golden/. Cover the failure modes the spec names — a skill that has never been tested against its own known weaknesses isn't tested. Scenarios use synthetic or scrubbed insurance data only (a fixture policy schedule, an anonymised claims extract) — never client data. The scenarios run in the golden-task harness; no spec + scenarios, no publication.

Review, register, release​

  1. Peer review — via the contribution workflow: PR, owning-discipline reviewer, 48-hour SLA.
  2. Registry entry in the same PR — the registry row carries path, phase, owner, lifecycle, version.
  3. Semver releases — patch for wording and fixes, minor for new capability that doesn't change the contract, major for anything that changes inputs, outputs or permissions — with a migration note in the PR, because other squads' workflows now depend on the old contract.
  4. Promotion — draft → trial on real use; trial → proven on harness evidence only, same rule as prompts.
Pending platform work

Running golden scenarios automatically in CI (so a skill PR fails when its scenarios do) needs harness wiring — until then scenario runs are manual and their results are linked in the PR.

Standards referenced: Semantic Versioning.