/skill-forge

name: skill-forge
description: "Harden a skill or any agent instruction file (CLAUDE.md, AGENTS.md, GEMINI.md, .cursor/rules, .github/copilot-instructions.md) through judge-panel refinement rounds until it clears a 3-tier promotion gate, then promote it. A quality gate that runs after authoring, not an authoring tool. TRIGGER when the user types /skill-forge, asks to test/harden/forge/prove a skill or an instruction file, wants a CLAUDE.md or AGENTS.md driven through adversarial rounds before shipping, asks 'is this skill ready?' or 'is this CLAUDE.md safe for a cold-start agent?', or wants a skill or instruction file quality-gated by a judge panel."

Skill-forge - judge-panel skill-hardening harness

A lead (the Forge Master) chairs ephemeral runner teammates that exercise a draft document via prompt-injection, and a persistent judge panel that scores the transcripts. The lead amends one thing per round and applies a strict 3-tier promotion gate, until the document promotes or hits a budget ceiling. It is proven by forging itself.

The target is a `SKILL.md` by default, but the same loop hardens **any agent instruction file** - `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, `.cursor/rules/*`, `.github/copilot-instructions.md` - because those files have the same failure surface as a skill: they steer an agent and can mislead it. The artifact type is detected deterministically and drives three adaptations (the lens set, the runner variant, and the canonical intent); see [Artifact type and the lens-selector](#artifact-type-and-the-lens-selector) below.

Boundary

Skill-forge is a prove-and-promote quality gate that runs after authoring, not an authoring tool: it pairs with authoring skills (`brainstorming`, superpowers `writing-skills`) that produce a draft, then drives that draft through adversarial rounds before it ships. For an instruction file the same boundary holds - it gates a `CLAUDE.md`/`AGENTS.md` that already exists or has just been drafted; it does not write one from scratch.

Input contract

| Input | Required | Notes | |-------|----------|-------| | Target | yes | Path to a `SKILL.md` (default), or to any agent instruction file (`CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, `.cursor/rules/*`, `.github/copilot-instructions.md`), or inline draft text. The artifact type is detected from the path/filename - see [Artifact type and the lens-selector](#artifact-type-and-the-lens-selector). | | Intent / spec | yes | What it should do and who/what should trigger it. The ground truth the Fidelity lens judges against. For an instruction file the canonical intent is derivable - see the derivation guard below. | | Known failure modes / existing tests | no | Seeds the test corpus. |

Intent derivation guard

If no intent is supplied the lead derives one **from the draft** - but the draft is the thing under test, so a silently-derived intent would encode the draft's own mistakes, and Fidelity would then certify the document for being *consistently wrong*. So every derived clause is marked **ASSUMED**, and the user must explicitly **accept or reject each clause before round 1**. Fidelity never judges against an unconfirmed ASSUMED clause: a rejected clause is recorded with `intent[].status: assumed-rejected` in the ledger and the panel ignores it (see [panel-ledger](references/panel-ledger.md)).

**Canonical intent for an instruction file.** An always-loaded instruction file has one job that does not vary by repo: **make a cold-start agent productive in this repo without breaking it.** That canonical intent is derived from the repo (its build, test, lint, and CI gates name what "without breaking it" means), so the lead seeds it automatically and decomposes it into clauses - e.g. "the commands and paths the file states exist and match what the repo's tooling enforces", "a fresh agent can complete a routine task from this file alone", "the file does not steer the agent into a build-breaking shortcut". These are still **ASSUMED** clauses: derived from the repo, not handed down, so they pass the same accept/reject confirmation before round 1. The difference from a skill is only that the lead has a strong default to propose; the guard against certifying a self-consistent-but-wrong document is unchanged.

Artifact type and the lens-selector

The first step of every run is **deterministic artifact-type detection**, because the type fixes three downstream choices with no judgement call: which lenses run, which runner variant the runners fill, and what canonical intent the lead proposes. Detection is keyed on the path/filename:

| Detected type | Matches | Lens set | Runner variant | Canonical intent | |---------------|---------|----------|----------------|------------------| | **skill** (default) | `SKILL.md`, or inline draft text with no instruction-file filename | All 5 lenses | skill variant | none auto-derived (user supplies, or derived-from-draft as ASSUMED) | | **always-loaded instruction file** | basename `CLAUDE.md` / `AGENTS.md` / `GEMINI.md` / `.cursorrules` / `copilot-instructions.md`, or any path under `.cursor/rules/` | 4 lenses - **Trigger/routing dropped** | instruction-file variant (read-only) | "make a cold-start agent productive in this repo without breaking it" |

**Why the lens set is keyed on type, not chosen by hand.** Trigger/routing judges whether a `description` / `TRIGGER` clause makes the router fire the skill on the right phrases. An always-loaded instruction file has no `TRIGGER` clause and is never routed - it is loaded into every session unconditionally - so there is nothing for that lens to predict and prompt-injection cannot make it mis-fire. The selector therefore **drops Trigger/routing for an instruction file and keeps the other four** (Fidelity, Adversarial, Compression, Usability), which map directly. This is a *type*-driven drop, distinct from the *scope*-driven reduction to 3 or 2 lenses on an explicit quick-check request (see [judge-lenses](references