| name | review-agent |
| description | Review a subagent definition file (agents/*.md) against the documented subagent format and best practices, including the seam with any skill it binds to — duty segregation, pointer-not-copy, actor-neutral skill content. Use when the user asks to "review this agent", "audit an agent definition", "check an agent against best practices", "validate agent frontmatter", "check the agent/skill separation", or after creating or substantially editing an agent. Do NOT use for skill directories (SKILL.md) — use review-skill for those (a seam violation inside a bound skill is still reported here). |
| compatibility | Requires Node.js 18+ |
review-agent — checklist audit of a subagent definition
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 single markdown agent definition file. Given a bare name, resolve it against the nearest agents/ directory (a project's .claude/agents/, a plugin's agents/, or ~/.claude/agents/); if that is ambiguous or the path is not a markdown file, stop and report — do not guess.
Procedure
- Run the mechanical checks:
node scripts/check.mjs <target-file> (invoked from this skill's root). It emits JSON verdicts for the format 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, plus the
name and description of every sibling agent in the same agents tree (needed for the B4 overlap call). Where the body binds the agent to other artifacts — a skill it must invoke, a script it must run, a profile doc it must read — confirm each exists where the body says it does. When a skill binding exists in either direction (the agent invokes/preloads a skill, or a skill spawns this agent), read that skill's whole SKILL.md too — the F section grades both sides of the seam and cannot be judged from the agent file alone. 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 item; 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 (format violations first, then description/delegation, then seam violations, then prompt and capability quality). For an F finding whose fix lands in the bound skill rather than the agent file, the fix line names the skill file explicitly.
Verdict rules
- Evidence is mandatory on every line: a measured value ("description 812 chars"), a location (
helm.md:23), 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 agent legitimately passes everything.
Output format
# Agent review: <name> (<relative path>)
**<n> PASS · <n> FAIL · <n> N/A**
## A. Format compliance
- ✅ A1 — frontmatter parses; body 2100 chars
- ❌ A6 — color `magenta` not in {red, blue, green, yellow, purple, orange, pink, cyan}
- ...every item, every section, one line each...
## D. Capability discipline
- ➖ D5 — N/A: no memory/skills/maxTurns/background/isolation fields
- ...
## Fixes (FAIL items, by severity)
1. A6 — set `color: purple` (magenta is not an accepted value)
2. ...one minimal fix per FAIL...
Worked example
A target agents/reviewer.md whose frontmatter grants tools: Read, Write, Edit, Bash while its body says "you are strictly read-only — never modify files", whose description is "Helps with reviews.", and whose body restates the review procedure's worker roster while also citing the skill that owns it, yields, among others:
- ❌ D2 — body forbids writes (
reviewer.md:9) but frontmatter grants Write, Edit
- ❌ B1 — "Helps with reviews." names no concrete capability
- ❌ F3 — roster restated (
reviewer.md:17) beside its own pointer to the owning skill
- ✅ A2 — name
reviewer (8 chars) valid
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 file.
- Checker exits 3 — the target is not a markdown file; agents are discovered as
.md only — report it, don't guess a sibling.
