resonance-ops-skill-author

/resonance-ops-skill-author: forge a skill to the gold standard

Role: the meta-skill. It builds the other skills. Input: a capability gap, a task the agent does poorly or re-explains every time. Output: a skill template in .forge/skills/<name>/, compiled to SKILL.md, with >= 3 evals, passing the validator. Definition of Done: python .forge/validate_skill.py <out> is clean, >= 3 eval cases exist, and the skill closes a gap proven by a baseline run.

You do not write prose and hope. You build the way you would build software: prove the gap, write the minimum, validate, eval, commit atomically. A skill that ships unmeasured is a liability, not an asset.

Prerequisites (fail fast)

• You can name the gap in one sentence and give a concrete example task. If you cannot, stop and ask the user for one.
• You know the archetype (see step 2). If the request is "make X better," first decide whether X is knowledge, procedure, or orchestration.

Algorithm

Copy this checklist and tick items as you go.

1. Prove the gap (eval-first). Run the target task without a skill. Record where the model fails or what you keep re-explaining. This is the baseline. No gap, no skill. → verify: you have a written baseline failure.
2. Choose the archetype. → verify: one of:
   • knowledge: a domain expert applied inline (copywriter, architect). Auto-loaded.
   • procedure: a gated, multi-step job with a Definition of Done (build, ship). Invoked as /name; mark manual-only if it has side effects.
   • orchestration: a procedure that drives other skills/subagents (audit swarm, review pipeline). See skill_spec.md for the contract each one must satisfy.
3. Write the golden evals first. Create >= 3 cases in evals/ (query + expected_behavior rubric). Cover the happy path, an edge case, and a failure the skill must prevent. See eval_protocol.md. → verify: 3 files in evals/.
4. Write the minimum skill. Start from the matching template in .forge/templates/. Add only what the model does not already know (see degrees_of_freedom.md). Nail the description first, it is what makes the skill trigger (see description_patterns.md). Push fragile, deterministic steps into scripts/, not prose (see script_authoring.md). → verify: body is lean, references one level deep.
5. Compile. python .forge/forge.py build <name> (add --host all to emit every tool, --model <m> to target a model). The Forge injects shared sections (voice, decisions, completion) so you never hand-copy them. → verify: output written.
6. Validate (the gate). python .forge/validate_skill.py <output-path>. Fix every ERROR and every warning you can before continuing. This is your Definition of Done check. → verify: validator clean.
7. Eval. Run the skill against the golden cases (with vs. without). It must beat the baseline from step 1. → verify: measured improvement.
8. Commit atomically (the Iron Contract). Only after validate + eval pass, write the skill into place and tell the user what landed. If anything failed, discard and report; there is no "almost shipped" state.
9. Iterate (Claude A / Claude B). Author with this instance; test with a fresh one on real tasks. Bring its failures back as edits to the template, never to the generated output. Regenerate.