| name | resonance-ops-skill-author |
| description | Authors, audits, and hardens Resonance skills with the Forge compiler. Use when building a new skill, converting a workflow into a procedure skill, writing or fixing a skill description or frontmatter, shrinking a bloated SKILL.md, adding evals, or running the skill validator. Covers all three archetypes (knowledge, procedure, orchestration) and emits per-tool, per-model output. |
| archetype | procedure |
/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)
Algorithm
Copy this checklist and tick items as you go.
- 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.
- 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.
- 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/.
- 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.
- 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.
- 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.
- Eval. Run the skill against the golden cases (with vs. without). It must beat the baseline from step 1. → verify: measured improvement.
- 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.
- 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.
Recovery
- Validator reports ERRORs you cannot resolve → the skill is not done. Report the specific check and stop; do not ship a failing skill.
- Eval does not beat baseline → the skill adds tokens without value. Cut it back or kill it.
- Asked to edit a generated
SKILL.md directly → refuse. Edit the template in .forge/skills/<name>/ and recompile. Generated files carry a "do not edit" banner.
- Tried to fix a failing skill 3 times without success → stop, show the eval output, escalate.
What good looks like
- The
description says what it does AND when to fire, in third person, under 1024 chars.
- The body is an overview that points to references; it is not a wall of text.
- A procedure skill states Input, Output, Definition of Done, Recovery.
- Fragile steps are scripts with real error handling, not hopeful prose.
- Three evals exist and pass. The validator is clean.
Out of scope
- Writing application code (delegate to resonance-backend / resonance-frontend).
- Writing marketing copy (delegate to resonance-copywriter).
- Inventing a new file format. The output is a SKILL.md; the Forge owns how it is generated.
Operating Standard
Apply the Resonance operating standard from AGENTS.md (always loaded): the builder Voice and its banned-word list (no AI slop, no em dashes), Recommendation-First decisions (models recommend, the user decides), the Completion protocol (end with DONE / DONE_WITH_CONCERNS / BLOCKED / NEEDS_CONTEXT, backed by evidence, escalate after 3 failed tries), and the Ratchet (log durable learnings to .resonance/learnings.jsonl).
Model note (Claude): Strong native reasoning. Do not narrate "let me think step by step" or pad with chain-of-thought; think, then act. Prefer the dedicated file and search tools over shell. State assumptions briefly, then proceed.
