Skip to main content

Toolkit contribution & review

How prompts and skills get into the shared toolkit, and how they earn the word "proven". Everything is a PR — the artefact, its registry row and its evidence travel together — so contributing to the toolkit feels exactly like contributing code, because it is.

The workflow​

  1. Open a PR containing the artefact — a prompt (one file, with front-matter, in /toolkit/prompts) or a skill (spec + golden scenarios, per the skill-development playbook).
  2. Update the registry in the same PR — new row, or lifecycle/version change. A toolkit PR without a registry change is incomplete.
  3. Review within 48 hours — the SLA. One reviewer from the owning discipline (Test reviews test prompts, Security reviews security prompts) plus any Toolkit Guild member. Two approvals, not a meeting.
  4. Merge — the artefact is live at lifecycle draft and any squad may use it, knowing exactly how much to trust it.

What reviewers check​

A paragraph of criteria, not a committee: the artefact does one job and says what it is; it names its own failure modes honestly; it contains no secrets, client data or personal data (UK GDPR — synthetic or scrubbed examples only); its guardrails follow the agent-guardrail standard and nothing in it authorises an irreversible action; placeholders are obvious; the version bump matches the change; the registry row matches the front-matter. If it passes those, it merges — taste disagreements become follow-up PRs, not blockers.

Lifecycle & promotion​

draft → trial → proven → deprecated, recorded in front-matter and the registry:

  • draft — merged, usable, unmeasured. Where everything starts.
  • trial — at least one squad is using it on real work and has agreed to report back. Promotion to trial is a reviewer's judgement call.
  • proven — harness evidence only. The artefact has been run through the golden-task harness and the results are linked from its front-matter (eval: field) in the promoting PR. No harness link, no promotion — this is the line that keeps "proven" meaning something.
  • deprecated — superseded or retired. The file and registry row remain, pointing at the replacement; history is part of the toolkit.

Demotion is the same PR in reverse: if a proven prompt starts failing on a new model version, anyone may propose proven → trial with the evidence.

Why this shape​

The 48-hour SLA keeps contribution cheaper than hoarding — the failure mode this playbook exists to prevent is squads keeping good prompts in private notes because sharing is slow. Review by the owning discipline keeps quality without creating a bottleneck body; the Guild governs the loop, it doesn't approve every entry.

Pending decision

Named reviewers per discipline (and cover across UK/India time zones so the 48-hour SLA holds) need assigning — Toolkit Guild to confirm the rota.

Standards referenced: Semantic Versioning.