sub-agent-review

What this skill does

# 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:

```markdown
---
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:**
```yaml
name: helper
description: Helps with stuff
```

**GOOD:**
```yaml
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):**
```yaml
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:**
```markdown
---
[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

```yaml
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**
```yaml
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

```markdown
## 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 |