Reviewing Agents

Overview

Performs a structured, scored audit of Claude Code subagent definition files against official best practices. Produces a scored report across 5 quality dimensions and optionally generates a corrected version.

Follow these steps exactly.

When not to use

Does not scaffold new agents — use agent-creator. Does not review SKILL.md files — use skill-reviewer.

Table of Contents

• Step 1: Resolve Target Agent File
• Step 2: Read and Measure
• Step 2b: Determine Guidelines Source
• Step 2c: Regression Risk Check
• Steps 3-7: Audit, Score, Report, Fix, and Write
• Quick Reference Checklist

Step 1: Resolve Target Agent File

Determine which agent definition file to audit:

1. Explicit path in message -- If the user provided a file path, use it directly.
2. Conversation context -- If an agent has been recently discussed or created, use that file.
3. Glob for agents -- Search for agents/*.md files in the project and present a picker via AskUserQuestion.
4. Ask if still unclear -- "Which agent definition file would you like me to review? Please provide the path."

Validate the resolved file is an agent definition (has YAML frontmatter with at least a name: field). If the file is a SKILL.md, redirect: "This looks like a skill file. Use /reviewing-skills instead."

Step 2: Read and Measure

Read the target file and record:

Plugin agent detection:

Walk up from the agent file's directory to find .claude-plugin/plugin.json. If found AND the agent is inside a known marketplace structure (kit/plugins/), set marketplace_repo = true -- suppress plugin-ignored-fields warnings. If found but NOT in kit/plugins/, set plugin_agent = true -- warn about ignored fields (permissionMode, hooks, mcpServers).

Edge case detection:

• Empty body -- Frontmatter present but zero body lines. Will score 0 on System Prompt Quality.
• Non-YAML frontmatter -- File does not start with ---. Report as hard failure.
• Duplicate YAML keys -- Same key appears twice in frontmatter. Flag as ERROR (YAML parsers silently use last value).

Note the presence or absence of:

• YAML frontmatter delimiters (---)
• name: field
• description: field with "Use when..." trigger phrase
• ## Role section in body
• ## Workflow or ## Behavior section in body
• ## Output Format section in body
• ## Scope Boundaries section in body
• STOP instruction (for background agents)
• Memory consult/update instructions (if memory: is set)

Step 2b: Determine Guidelines Source

Default: Use references/best-practices.md (static, always available).

Fetch live from official docs when user says:

• "use latest", "check official docs", "fetch from platform", "use current guidelines"

Live fetch URL:

https://code.claude.com/docs/en/sub-agents

If live fetch fails: fall back to references/best-practices.md silently and note the failure in the audit output under a "Guidelines Source" line.

Step 2c: Regression Risk Check

For files with git history: Compare the current agent file against its last committed version to detect breaking changes and regressions. See references/audit-steps.md for the comparison matrix.

Skip if any of the following are true:

• Not inside a git repository (git rev-parse --git-dir returns non-zero)
• File has never been committed (git log --oneline -- <path> returns no output)
• User says "skip regression check", "no comparison", or "first review"

For new files (no git history): Run the golden template comparison instead. Check whether the agent file includes the expected structural sections: ## Role, ## Workflow or ## Behavior, and (for agents that produce output) ## Output Format. Report missing sections as "template gaps" alongside the dimension scores. See references/best-practices.md -- Golden Template section.

Steps 3-7: Audit, Score, Report, Fix, and Write

Continue with references/audit-steps.md for:

• Step 3: Score 5 dimensions (2 pts each, max 10)
• Step 4: Output scored report with grade
• Step 5: Present fixes as a unified diff in chat output
• Step 6: Ask whether to apply diff directly or add inline <!-- SUGGESTION --> comments to a copy
• Step 7: Write-to-disk confirmation (requires explicit second confirmation)

Quick Reference Checklist

Frontmatter Compliance

• YAML delimiters (---) present and matching
• name: present, lowercase + hyphens only, <=64 chars
• name: does not contain anthropic or claude as substring
• description: present, <=1024 chars, third person
• model: valid if present (sonnet, opus, haiku, full model ID, inherit)
• permissionMode: valid if present (default, acceptEdits, auto, dontAsk, bypassPermissions, plan)
• maxTurns: in range 5-50 if present
• effort: valid if present (low, medium, high, xhigh, max)
• color: valid if present (red, blue, green, yellow, purple, orange, pink, cyan)
• background: boolean if present
• isolation: is worktree if present
• memory: valid if present (user, project, local)
• No unrecognized frontmatter field names
• No duplicate YAML keys

Tool Configuration

• All tool names in tools: are valid Claude Code tools
• Agent not listed in tools: (no effect in subagents)
• Both tools and disallowedTools set noted as INFO
• Read-only agents have disallowedTools: Write, Edit, NotebookEdit
• Background agents do not have unrestricted Write/Edit/Bash
• If tools omitted: inherits all -- appropriate for purpose?

Description Quality

• "Use when..." trigger phrase present
• Delegation context explains WHEN to delegate (not just what it does)
• Scope exclusion present ("Does NOT...", "Not intended for...")

• =3 searchable domain keywords

• Third person (no I, you, we, your)

System Prompt Quality

• ## Role section present
• ## Workflow or ## Behavior section present with numbered steps
• Output format defined (if agent produces reports)
• Scope boundaries defined (in scope / out of scope)
• STOP instruction present (if background: true)
• Memory consult/update instructions present (if memory: is set)
• Body length 20-300 lines
• No hardcoded absolute paths

Security & Isolation

• bypassPermissions not used (or has explicit justification)
• background: true + mutation tools restricted
• Plugin agent: ignored fields not set (unless marketplace repo)
• Memory enabled with corresponding body instructions
• maxTurns not outside 5-50 range

Source: shawn-sandy/agentics — distributed by TomeVault.