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

1. Discover - Find agent files at $ARGUMENTS (.claude/agents/ or ~/.claude/agents/)
2. Validate - Check frontmatter and configuration
3. Evaluate - Score against best practices
4. 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 is focused and specific
• Clear workflow/steps defined
• Output format specified
• Constraints stated explicitly
• No unnecessary verbosity

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.

References

• Claude Code Sub-Agents Documentation
• Claude Code Plugins Reference
• Claude Code Hooks
• Claude Code Skills
• Claude Code Plugins