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

Frontmatter Configuration

Required Fields

Optional Fields

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:

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

4. Permission Modes

• Permission mode matches use case
• bypassPermissions used only when necessary
• dontAsk used for non-interactive 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:

Example: Validate SQL queries

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

Best Practices

Design Principles

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

Anti-Patterns

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

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.

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:

{
  "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

Plugin Anti-Patterns

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