/skill-review

name: skill-review
description: >
  Review Claude Code skills against substantive quality standards — an 8-category
  rubric with JSON output, single-pass full-rubric review, and a determinism contract.
  Complements Anthropic's `plugin-dev:skill-reviewer` (structural checks).
  Use for: "review a skill", "check skill quality", "does this skill need evals",
  "review skill quality".
version: 0.1.0

Skill Review

Purpose

Review skills for substantive quality signals that Anthropic's `plugin-dev:skill-reviewer` does not cover. That agent handles structural concerns (frontmatter format, word count, writing style, progressive disclosure). This skill focuses on **substance** — whether the skill gives Claude the right kind of content, has appropriate test coverage, uses hooks effectively, and lives in the right location.

The rubric is **authoritative and closed.** Every finding type the reviewer can surface is enumerated in the per-category reference files. Reviewers match against the rubric; they do not invent new buckets. If a concern doesn't fit any enumerated finding type, it belongs in the out-of-rubric channel — never inline as Critical/Major/Minor.

**Closed does not mean conservative.** "Closed" constrains the *set* of finding types you may emit — it does **not** mean you should hesitate to apply the ones that exist. The two are independent: never invent a new finding type, AND never withhold a defined one when its predicate plausibly matches. The judgment-bound finding types — `operational-guardrail-untested` and `guardrail-eval-unpressured` (Test Coverage), `contradictory-instructions` and the three Behaviour sub-checks (Integrity), `procedure-smell-with-consequence`, `form-mismatch`, and `negotiable-guardrail` (Content Quality), `description-encodes-process` (Convention), the orchestration pair (Cost/Convention), the four frontier-model instruction anti-patterns — `verification-ritual`, `emphasis-inflation`, `reasoning-scaffold`, `stale-few-shot-example` (Cost) — `dated-model-configuration` (Integrity), and the Hooks judgment findings — `skill-advertisement-hook`, `heavy-work-in-hook`, `hot-event-hook`, `duplicate-hook` (Hooks) — are the ones a reviewer most often *under*-fires, because the defect is buried in an otherwise-sound skill and nothing jumps out on a first read. The `form-mismatch` / `negotiable-guardrail` pair is especially easy to miss because the *content* of a discipline rule can be correct while its *form* quietly fails to make it stick — a "prefer…" where a prohibition is needed, or a guardrail with an "unless it matters" escape hatch. For these types, **`pass` is a claim that must be earned, not a default**: a category may be marked `pass` only after you have positively checked the predicate (enumerated every guardrail and cross-checked it against the evals, read every referenced script, compared every same-condition instruction pair) and found it does not hold — not merely because no red flag was salient. When a defined predicate plausibly matches, fire it; absence of an obvious problem is not evidence of absence.

How a Review Runs

A review is a **single pass**: load every category reference, evaluate all eight categories against the skill, and emit the full JSON. There is no triage gate — no category is skipped for looking clean, so a finding can never be missed because its category's deep-dive reference was never opened. This trades token spend for recall by construction.

1. **Read the skill folder and the scripts it invokes.** SKILL.md body and frontmatter, `references/` listing, `evals/` listing, and any scripts the skill ships **or invokes** — both scripts under the skill's own `scripts/` and shared scripts at the plugin root (e.g. `${CLAUDE_PLUGIN_ROOT}/scripts/...`) that the SKILL.md references and tells Claude to run. A skill whose scripts live at the plugin level is the common case, not the exception — Glob for the referenced script paths and read them; do not treat "no `scripts/` dir inside the skill folder" as "no scripts to review". Also read any agent files the skill references or is paired with (a plugin-root `agents/*.md` the skill hands off to) — Integrity's `dated-model-configuration` check explicitly covers "the skill, its agents, or its scripts", so a stale model ID in an agent's frontmatter is in scope even though it lives outside the skill's own folder. Every check in this skill is performed by reading — Read, Grep, and Glob are the only tools needed. Note the skill's **reach** (a widely-shared skill published in a plugin/marketplace vs a personal or project-local skill) and its diff status (`M` if it's being modified in this PR) — Test Coverage and the stale-eval checks depend on both. 2. **Load all eight category references.** Read every deep-dive listed in [Reference Files](#reference-files) before evaluating. Load `suggested-rewrites.md` too if any finding will need a rewrite. Each reference owns the finding types, severity tiers, false-positive guardrails, and rewrite policy for its category — applying a category without its reference loaded is not permitted. 3. **Evaluate every category.** Apply each reference's rubric to the skill by reading it directly. A category with no matching finding emits `{"status": "pass", "findings": []}`; otherwise it emits its findings with `finding_type`, `severity`, `deterministic`, `location`, `explanation`, `fix`, and optionally `suggested_rewrite`. A skill that is mostly deterministic glue (pinned queries, fixed tool/MCP call sequences, output templates) — counting body **and** `references/` — is the `script-extractable-orchestration` (Cost) / `orchestration-shaped-skill` (Convention) pair; single-pass already loads both references every run, so no triage hint is needed to reach it. 4. **Emit structured JSON.** Output the full JSON — all eight categories, including the ones that passed clean — per the [Output Contract](#output-contract) below. This skill's contract ends at the JSON.