Staged prompts for deep, opinionated reviews of skills — the behavior patches that steer agents. Centered on behavioral validation, not just careful reading.

skill-review

A series of prompts for producing deep, opinionated reviews of skills — the conditional behavior patches that steer other agents.

It is descended from repo-review and keeps that project's discipline: staged passes, each performed without knowing what later passes ask for; prose as the canonical product with a thin YAML appendix beneath it; honesty about blindness as the load-bearing virtue. But it is not "repo-review for skills." A skill is not a body of work to be interpreted — it is an instrument that changes how another agent behaves. So skill-review's center of gravity is behavioral validation: a skill earns its existence only if it fires when it should and changes behavior for the better once it does. Everything else serves that.

The passes

Order	Name	Catches
01	The First Read	First impression: behavioral contract, trigger surface, disclosure economy, a predicted behavioral delta, and an honest inventory of cross-skill references
02	The Discounted Resource	The bundled script or reference the first read trusted without opening — honest disclosure vs. façade
03	The Doorway	Whether the `description` fires when it should and stays silent when it shouldn't
04	The Ablation	What the skill actually changes in an agent, measured by removing it
04.5	The Synthesis	The core diagnosis folded into one current judgment — does the skill earn its keep?
05	The Decomposition	Whether to tighten one skill or split it into a collection — the trigger-partition crux
06	The Twin	What the skill's design philosophy looks like beside one adjacent skill
07	The Harvest	Reusable authoring primitives worth carrying to other skills
08	The Delta Review	Which prior judgments move after the skill changes

This table is an informal teaser. See docs/PASSES.md for the full map: each pass's status, prerequisites, early-stop condition, and the prerequisite DAG.

The arc reads end to end: read → verify → synthesize → act / compare / mine → re-review on change. Passes 01–04 are the core read-and-verify block; 04.5 is an optional compositional checkpoint; 05 acts on the verdict; 06 and 07 are optional analytical passes; 08 is out-of-band, run later when the skill is edited.

One optional pass operates one rung above this series: repo-link-inventory, a library-level pre-pass that walks a whole skills/ folder at once and produces an edge list of cross-skill references plus a findings list (notably phantom_link for unresolved routing references). It is recommended when reviewing a multi-skill library and skipped for single-skill review; the per-skill series remains complete without it. See docs/PASSES.md for details.

The two-prediction spine

The series is staged so later passes test earlier ones. The First Read, working from the text alone, makes two predictions: when the description will fire (trigger_surface) and where the skill is load-bearing versus inert (behavioral_delta). The Doorway then maps the real firing boundary, and the Ablation measures the real behavioral delta — each recording whether it confirmed or overturned the prediction. The Synthesis resolves the loop into one verdict.

This is the point of the whole design: read on its own, a skill's good writing is exactly what fools you. The executable passes exist to catch what reading cannot.

How to run a review

Critical: present the passes to the analyzer one at a time. Each pass shapes what the analyzer attends to. If later passes are visible while it works on an earlier one, its direction gets polluted by anticipation of what's coming.

Pick a skill worth reviewing.
Give the analyzer The First Read only. Let it produce its full analysis, predictions included.
Give it The Discounted Resource — it opens the bundles the first read trusted, or terminates early if there are none.
Give it The Doorway — does the skill fire on the right queries?
Give it The Ablation — what does the skill change versus the agent with no skill at all?
Optionally give it The Synthesis to fold passes 01–04 into one current judgment before deciding what to do next.
Give it The Decomposition — should this stay one skill, be tightened, or split into a collection?
Optionally give it The Twin with a chosen adjacent skill (same problem, different design philosophy).
Optionally give it The Harvest to mine the skill for reusable authoring patterns.

You earn each step. After the core block you pick and choose; a pass that halts with a real finding — "this skill is already atomic," "this skill resists measurement" — tells you more than one that fabricates output to look thorough.

Running the executable passes

The Doorway, the Ablation, and the Decomposition probe the skill with a battery of realistic queries or tasks. Each has a strong form (run the battery against a real model) and a fallback form (reason about what a run would show). Both are legitimate; conflating them is not. The shared craft of building and running a battery — realistic items, the should-fire/should-not-fire/near-miss split, the complexity confound, repeats for variance, the right model, and the measured-versus-predicted honesty line — lives once in references/battery.md. Each pass says only how it points one.

How to update a review

Use The Delta Review when the skill has changed since the baseline review and you want to know which judgments need to move. Give the analyzer the prior review, both versions of the skill (baseline and updated), and the diff between them. It locates what changed, maps each change to the judgments it threatens, re-checks only those, and reports the result as movement — held, moved, newly open — rather than re-reviewing from scratch.

Output format

Every pass produces two outputs:

Prose body. Opinionated, direct, written for a careful human reader.
YAML appendix. A pass_output: block at the end, keyed by pass_id, suitable for downstream tools that route findings, compare skills, or feed structured data elsewhere.

Each appendix identifies the skill source state it analyzed (source_state, or two states for the comparative and incremental passes) and carries a confidence block with a concrete smallest_open target — the single smallest file that, if opened next, would most reduce the pass's largest uncertainty.

The executable passes also carry an honesty boolean — ran_battery, ran_baseline — recording whether a result was measured or predicted. Downstream readers weight everything else by it; a predicted result must never wear the clothes of a measured one.

Early termination

A pass that has nothing real to do says so and stops. This is a feature, not a failure — the statement of why is itself diagnostic:

Discounted Resource stops when the skill has no substantial bundles.
Doorway stops when the skill is only ever invoked by explicit name.
Ablation stops when the skill makes no falsifiable behavioral claim (pure taste); it records the qualitative difference and the fact that the value is a judgment, not a delta.
Decomposition stops when the skill is already atomic.
Twin stops when no genuine adjacent skill exists.
Harvest stops when nothing survives outside this skill.
Delta Review stops when nothing material has changed since the baseline.

Audience

Two readers, served by the same discipline:

A human curator who reads the prose carefully and asks sharper questions afterward.
Downstream tools that consume the structured YAML for purposes the analyzer cannot anticipate.

The writing serves both: tell the truth as you see it, mark where your sight is weak, leave the next reader something to push against.

Status

Young. The nine passes and their map exist; the series has not yet been run end-to-end against a real skill. The natural next step is to point it at one and see where the prompts are sharp and where they are vague — a First Read is cheap, and the series is built to be honest about its own blind spots, including this one.

Repo layout

skill-review/
├── README.md
├── 01-first-read.md
├── 02-discounted-resource.md
├── 03-doorway.md
├── 04-ablation.md
├── 04.5-synthesis.md
├── 05-decomposition.md
├── 06-twin.md
├── 07-harvest.md
├── 08-delta-review.md
├── docs/
│   └── PASSES.md       # the map of the series + prerequisite DAG
└── references/
    └── battery.md      # shared craft for the query/task probing passes