| 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
- 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.
- 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.
- 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.
- 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.
