New Skill Scaffolder

Creates a public skill under skills/<name>/ and stress-tests it through the full RED → GREEN → REFACTOR → adversarial-review → validate cycle before declaring it done.

Phase 1 — TDD Baseline (RED)

Before writing a single line of skill content, run /skill-tester to establish the baseline. Use its checklist to have a subagent run without the new skill loaded and record every rationalization the agent uses to skip the rule you are encoding. Document those rationalizations — every one must be countered in the skill body.

Phase 2 — Scaffold

1. Choose a kebab-case name (e.g. dep-auditor).

1. Create the directory and file:

   skills/<name>/SKILL.md

1. Write the frontmatter:

   ---
   name: <name>
   description: Use when <specific triggering conditions — no workflow summary, ≤500 chars>
   ---

1. Required sections (in order):

• ## Overview — one paragraph: what it does, hostile framing, single-shot behaviour
• ## When to Use — bullet list of triggering conditions and situations
• ## Process — numbered steps (find → ask → fix → re-validate)
• ## Findings Format — findings grouped by severity: Critical / High / Medium / Low / Advisory; Fixed and Invalid sections group entries under ### Pass N — YYYY-MM-DD h3 headers; output path docs/audit/<name>-findings.md. (Non-audit skills that write only to stdout may use ## Output Format instead.)
• ## Fix Strategy — what may be auto-applied, what requires user approval
• ## Common Mistakes — what the skill must NOT do

1. Counter every RED-phase rationalization explicitly in the skill body — add a rule or

a Common Mistakes entry for each one. "Rationalisation" and "rationalization" refer to the same thing; use "rationalization" (US spelling) consistently throughout.

Phase 3 — Verify Behaviour (GREEN)

Run /skill-tester again, this time with the skill loaded. Confirm the agent complies with every rule. If the agent finds a new loophole, add an explicit counter and re-run until no loopholes remain.

Phase 4 — Refactor

With the GREEN phase clean, refactor the skill body for clarity and hostile precision:

• Remove hedging language ("might", "could", "potential") — every statement must be

unconditional

• Tighten rule wording so each rule can be tested by a single scenario
• Consolidate duplicate or overlapping rules
• Ensure the Common Mistakes section names the exact rationalizations captured in the

RED phase

• Re-run /skill-tester after refactoring to confirm no regression — all GREEN

scenarios must still pass

Phase 5 — Adversarial Review

Run /adversarial-reviewer against the new skills/<name>/SKILL.md file. Treat the skill body as code under review — hunt for ambiguous rules, missing edge-case coverage, hedged language, and instructions that permit rationalization. Fix every HIGH or CRITICAL finding. Re-run until adversarial-reviewer reports no findings at HIGH or above.

Phase 6 — Structural Validation

1. Add a row to the Existing Skills table in CLAUDE.md.

1. Add a row to the Available Skills table in .claude/skills/skills/SKILL.md — this is the launcher skill users invoke to discover and route to public skills. Keep it in sync.

1. Add a row to the "Existing Public Skills" table in .github/copilot-instructions.md.

Also update README.md — it always contains a mirrored skills table.

1. Add a row to the Skill Catalogue table and all relevant Mermaid diagrams in

.claude/skills/README.md (the wiring guide). Update the Quick Reference Input/Output table as needed.

1. Run the validator:

    uv run scripts/validate-skill.py skills/<name>/SKILL.md

1. Run /validate-skills to confirm all skills remain consistent.

Phase 7 — PR Review

1. Run /pr-reviewer on the staged diff. Fix all findings at HIGH or above.

Re-run until pr-reviewer reports no findings at HIGH or above.

1. Commit with feat: add <name> skill — this triggers a minor version bump.

Skill Quality Gate

A skill is not done until all of these pass:

• [ ] skill-tester GREEN phase: agent complies with every rule
• [ ] skill-tester REFACTOR verify: re-run with skill loaded after refactoring; no new loopholes
• [ ] adversarial-reviewer: no HIGH or CRITICAL findings remain
• [ ] uv run scripts/validate-skill.py skills/<name>/SKILL.md exits 0 with no errors
• [ ] /validate-skills exits clean
• [ ] pr-reviewer: no HIGH or CRITICAL findings in the diff