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 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 below. This skill's contract ends at the JSON.