review-skill

name	review-skill
description	Review an agent skill against the official skills spec and best practices guidelines. Use when the user asks to "review this skill", "audit a skill", "check a skill against best practices", "validate SKILL.md", or after creating or substantially editing a skill. Do NOT use for subagent definition files (agents/*.md) — use review-agent for those.
compatibility	Requires Node.js 18+

review-skill — checklist audit of a skill directory

The deliverable is the filled-in checklist from references/checklist.md: every item gets exactly one verdict backed by a fact. No summarizing essay, no prose findings.

Target

The target is a directory containing a SKILL.md. Given a bare name, resolve it against the nearest skills/ directory; if that is ambiguous or the path has no SKILL.md, stop and report — do not guess.

Procedure

1. Run the mechanical checks: node scripts/check.mjs <target-dir> (invoked from this skill's root). It emits JSON verdicts for the spec items keyed by the same IDs as the checklist. Use its measurements verbatim — never re-derive by eye what the script already measured. Its warn results become PASS or FAIL by your judgment, with the script's detail as evidence.
2. Read the whole target: the target's SKILL.md in full, the list of every bundled file, and each references/, scripts/, and assets/ file that the judgment items require. Never grade a file you did not open.
3. Walk the checklist: read your own references/checklist.md and assign every item exactly one verdict — PASS, FAIL, or N/A. Applicability rules are stated per section; N/A is allowed only where an item's stated condition holds, never as an escape from a hard call.
4. Report using the output format below. Before delivering, verify every checklist ID appears exactly once in the report — a missing section is a broken review. FAIL items reappear in a fix list ordered by severity (spec violations first, then description, then content quality).

Verdict rules

• Evidence is mandatory on every line: a measured value ("description 812/1024 chars"), a location (SKILL.md:47), or a quote of at most one line.
• Binary calls: when a judgment item is partially met, it is FAIL with evidence of the gap — no "partial" or "mostly" verdicts.
• Do not invent findings to look thorough; a well-built skill legitimately passes everything.

Output format

# Skill review: <name> (<relative path>)

**<n> PASS · <n> FAIL · <n> N/A**

## A. Spec compliance
- ✅ A1 — frontmatter parses
- ❌ A3 — name `foo` != directory `bar`
- ...every item, every section, one line each...

## F. Scripts & commands
- ➖ F1 — N/A: no scripts bundled, no shell commands in SKILL.md
- ...

## Fixes (FAIL items, by severity)
1. A3 — rename directory to `foo` or set `name: bar`
2. ...one minimal fix per FAIL...

Worked example

A target skills/pdf-tools/ whose frontmatter says name: pdf-processing and whose description is "Helps with PDFs." yields, among others:

• ❌ A3 — name pdf-processing != directory pdf-tools
• ❌ B1 — "Helps with PDFs." names no concrete capability
• ✅ A4 — description 16/1024 chars

Troubleshooting

• node: command not found — Node.js is not installed; suggest the user installs Node 18+ and rerun.
• Checker exits 2 — bad invocation; pass exactly one existing directory.
• Checker exits 3 — the target has no SKILL.md; wrong path or not a skill — report it, don't guess a sibling.