Sub-Agent Implementation Review

Review Claude Code sub-agent configurations for best practices.

Target: $ARGUMENTS (path to sub-agent file or agents directory)

When to Use This Skill

Creating new sub-agents
Auditing existing sub-agent configurations
Optimizing sub-agent performance and cost
Reviewing tool access and permissions
Implementing sub-agent hooks

Review Process

Discover - Find agent files at $ARGUMENTS (.claude/agents/ or ~/.claude/agents/)
Validate - Check frontmatter and configuration
Evaluate - Score against best practices
Report - Generate findings with recommendations

Sub-Agent File Structure

File Format

Sub-agents are Markdown files with YAML frontmatter:

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.

Storage Locations

Location	Scope	Priority	Use Case
`--agents` CLI flag	Session only	1 (highest)	Testing, automation
`.claude/agents/`	Project	2	Team-shared agents
`~/.claude/agents/`	User	3	Personal agents
Plugin `agents/`	Plugin scope	4 (lowest)	Distributed agents

Frontmatter Configuration

Required Fields

Field	Description	Example
`name`	Unique identifier (kebab-case)	`code-reviewer`
`description`	When Claude should delegate	`Reviews code for quality. Use proactively after code changes.`

Optional Fields

Field	Description	Default
`tools`	Allowed tools (allowlist)	Inherits all
`disallowedTools`	Denied tools (denylist)	None
`model`	`sonnet`, `opus`, `haiku`, `inherit`	`inherit`
`permissionMode`	Permission handling	`default`
`skills`	Skills to preload	None
`hooks`	Lifecycle hooks	None

Configuration Checklist

1. Naming & Description

Name is kebab-case and descriptive
Description explains WHEN to use the agent
Description includes "use proactively" if auto-delegation desired
Description is specific enough for accurate delegation

BAD:

name: helper
description: Helps with stuff

GOOD:

name: code-reviewer
description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.

2. Tool Access

Only necessary tools are granted
Read-only agents exclude Write/Edit
Dangerous tools require justification
MCP tools considered if needed

Tool Categories:

Category	Tools	Use Case
Read-only	Read, Glob, Grep	Research, review
Modification	Write, Edit	Implementation
Execution	Bash	Commands, builds
All	(inherited)	Full capability

GOOD (read-only reviewer):

tools: Read, Grep, Glob, Bash
disallowedTools: Write, Edit

3. Model Selection

Model matches task complexity
Cost-sensitive tasks use Haiku
Complex reasoning uses Sonnet/Opus
inherit used when parent model is appropriate

Model	Best For	Cost
`haiku`	Fast searches, simple tasks	Low
`sonnet`	Balanced capability/speed	Medium
`opus`	Complex reasoning	High
`inherit`	Match parent context	Varies

4. Permission Modes

Permission mode matches use case
bypassPermissions used only when necessary
dontAsk used for non-interactive agents

Mode	Behavior	Use Case
`default`	Standard prompts	Interactive agents
`acceptEdits`	Auto-accept edits	Trusted modifiers
`dontAsk`	Auto-deny prompts	Background agents
`bypassPermissions`	Skip all checks	Automation (dangerous)
`plan`	Read-only exploration	Research agents

5. System Prompt Quality

Prompt Structure:

---
[frontmatter]
---

[Role statement - who the agent is]

When invoked:
1. [First step]
2. [Second step]
3. [Third step]

[Detailed guidelines]

[Output format specification]

6. Skills Preloading

Only necessary skills preloaded
Skills match agent's domain
No duplicate/conflicting skills

skills:
  - api-conventions
  - error-handling-patterns

7. Hooks Configuration

Hooks validate dangerous operations
Hook scripts are executable
Exit codes used correctly
Hooks don't block legitimate operations

Hook Exit Codes:

Code	Behavior
0	Allow operation
1	Error (operation continues)
2	Block operation

Example: Validate SQL queries

hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-readonly-query.sh"

Best Practices

Design Principles

Principle	Description
Single Purpose	Each agent excels at one specific task
Minimal Tools	Grant only necessary permissions
Clear Delegation	Description enables accurate auto-delegation
Version Control	Project agents checked into repo

When to Use Sub-Agents vs Main Conversation

Use Sub-Agents:

Task produces verbose output (tests, logs, docs)
Need specific tool restrictions
Work is self-contained
Can return a summary

Use Main Conversation:

Frequent back-and-forth needed
Multiple phases share context
Quick, targeted changes
Latency matters

Common Patterns

1. Isolate High-Volume Operations

Use a subagent to run the test suite and report only failing tests

2. Parallel Research

Research auth, database, and API modules in parallel using separate subagents

3. Chain Sub-Agents

Use code-reviewer to find issues, then use fixer to resolve them

Foreground vs Background

Mode	Permissions	Questions	Use Case
Foreground	Interactive prompts	Passed through	Complex tasks
Background	Pre-approved only	Auto-denied	Parallel work

Anti-Patterns

Anti-Pattern	Problem	Fix
God Agent	Does everything	Split by responsibility
Vague Description	Wrong delegation	Be specific about when to use
Over-Permissioned	Security risk	Limit tools to necessary
Missing Hooks	Unsafe operations	Add validation hooks
Hardcoded Model	Inflexible	Use `inherit` unless specific need
No Constraints	Unpredictable	Define clear boundaries in prompt
Verbose Prompt	Context waste	Keep focused and specific

Review Output Format

## Sub-Agent Review: [agent-name]

### Summary
[1-2 sentence overview]

### Configuration Score

| Category | Score | Notes |
|----------|-------|-------|
| Naming & Description | X/5 | |
| Tool Access | X/5 | |
| Model Selection | X/5 | |
| Permission Mode | X/5 | |
| System Prompt | X/5 | |
| Hooks | X/5 | |
| **Overall** | **X/5** | |

### Critical Issues
- [ ] [Issue] - Location: [field]

### Recommendations
- [ ] [Recommendation] - Priority: [High/Medium/Low]

### Strengths
- [What the configuration does well]

Built-in Sub-Agents Reference

Agent	Model	Tools	Purpose
Explore	Haiku	Read-only	Fast codebase search
Plan	Inherit	Read-only	Research for planning
general-purpose	Inherit	All	Complex multi-step tasks
Bash	Inherit	Bash	Terminal commands
Claude Code Guide	Haiku	Read-only	Help with features

Plugin-Packaged Sub-Agents

When distributing sub-agents as part of a Claude Code plugin, additional configuration applies.

Plugin Directory Structure

my-plugin/
├── .claude-plugin/
│   └── plugin.json          # Plugin manifest (only manifest here)
├── agents/                   # Sub-agents at plugin root
│   ├── security-reviewer.md
│   ├── performance-tester.md
│   └── compliance-checker.md
├── skills/                   # Supporting skills
├── hooks/                    # Hook configurations
└── scripts/                  # Hook scripts

Critical: Agents directory must be at plugin root, not inside .claude-plugin/.

Plugin Agent Frontmatter

Plugin agents support additional frontmatter fields:

---
description: What this agent specializes in
capabilities: ["task1", "task2", "task3"]
---

# Agent Name

Detailed description of the agent's role and when Claude should invoke it.

## Capabilities
- Specific task the agent excels at
- Another specialized capability

## Context and examples
When this agent should be used and what problems it solves.

Field	Description	Example
`description`	Agent specialization	`Security code review specialist`
`capabilities`	Task list for delegation	`["security-review", "vulnerability-scan"]`

Plugin Manifest Configuration

In plugin.json, specify custom agent paths:

{
  "name": "security-agents",
  "version": "1.0.0",
  "agents": "./custom/agents/"
}

Path options:

Default: agents/ directory auto-discovered
Custom: "agents": "./custom-agents/" or "agents": ["./agents/reviewer.md", "./agents/tester.md"]

Plugin Agent Hooks

Plugin hooks can respond to sub-agent lifecycle events:

Event	Trigger	Use Case
`SubagentStart`	Sub-agent begins	Logging, initialization
`SubagentStop`	Sub-agent attempts to stop	Cleanup, validation

{
  "hooks": {
    "SubagentStart": [
      {
        "hooks": [{
          "type": "command",
          "command": "${CLAUDE_PLUGIN_ROOT}/scripts/log-agent-start.sh"
        }]
      }
    ]
  }
}

Plugin Agent Checklist

Agents at plugin root (not in .claude-plugin/)
Uses ${CLAUDE_PLUGIN_ROOT} for script paths
Hook scripts are executable (chmod +x)
capabilities array aids delegation accuracy
Plugin manifest validates with /plugin validate

Plugin Integration Points

Integration	Behavior
`/agents` interface	Plugin agents appear alongside built-in agents
Auto-invocation	Claude delegates based on `description` and `capabilities`
Manual invocation	Users can invoke plugin agents directly
Coexistence	Plugin agents work alongside built-in and user agents

Plugin Anti-Patterns

Anti-Pattern	Problem	Fix
Agents in `.claude-plugin/`	Not discovered	Move to plugin root
Absolute paths in hooks	Breaks on install	Use `${CLAUDE_PLUGIN_ROOT}`
Missing `capabilities`	Poor auto-delegation	Add capability list
Non-executable scripts	Hooks fail silently	Run `chmod +x`

Example: Well-Configured Sub-Agent

---
name: code-reviewer
description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.
tools: Read, Grep, Glob, Bash
model: inherit
---

You are a senior code reviewer ensuring high standards of code quality and security.

When invoked:
1. Run git diff to see recent changes
2. Focus on modified files
3. Begin review immediately

Review checklist:
- Code is clear and readable
- Functions and variables are well-named
- No duplicated code
- Proper error handling
- No exposed secrets or API keys
- Input validation implemented
- Good test coverage
- Performance considerations addressed

Provide feedback organized by priority:
- Critical issues (must fix)
- Warnings (should fix)
- Suggestions (consider improving)

Include specific examples of how to fix issues.

sub-agent-review