create-subagent

What this skill does

# Create Subagent

This skill provides comprehensive guidance for creating and configuring subagents in Claude Code.

## Understanding Subagents

Subagents are specialized AI assistants that Claude Code can delegate tasks to. Each subagent:

- Operates in its own context window (preserving main conversation context)
- Has a specific purpose and expertise area
- Can be configured with specific tools and permissions
- Includes a custom system prompt guiding its behavior

### When to Create Subagents

**Create a subagent when:**

- Tasks require specialized expertise that benefits from focused instructions
- Context preservation is important (subagents don't pollute main context)
- The same specialized workflow is needed repeatedly
- Different tool permissions are needed for different tasks
- Parallel execution of independent tasks is desired

**Choose skills instead when:**

- The capability extends Claude's knowledge without needing separate context
- No specialized agent persona is needed
- Tool restrictions are sufficient without full agent isolation

**Choose slash commands when:**

- Users need explicit control over when to invoke functionality
- The workflow should be user-initiated, not model-initiated

## Two Approaches to Subagents

### Approach 1: File-Based Agents

Persistent subagent definitions stored as Markdown files.

**Locations (in priority order):**

| Location | Scope | Priority |
|----------|-------|----------|
| `.claude/agents/` | Current project | Highest |
| `~/.claude/agents/` | All projects | Lower |

**File Format:**

```markdown
---
name: agent-name
description: Description of when this agent should be used
tools: Read, Write, Bash, Glob, Grep  # Optional - omit to inherit all
model: sonnet  # Optional - sonnet, opus, haiku, or inherit
permissionMode: default  # Optional - see permission modes below
skills: skill1, skill2  # Optional - skills to auto-load
---

Your agent's system prompt goes here. This defines the agent's
role, capabilities, approach, and constraints.

Include:
- Role definition and expertise areas
- Step-by-step workflow for common tasks
- Constraints and rules to follow
- Output format expectations
- Examples of good behavior
```

### Approach 2: Task Tool Invocation

Dynamic subagent dispatch using the Task tool for on-demand agents.

```
Task(
  subagent_type: "general-purpose",
  model: "opus",
  prompt: <the agent's instructions and task>
)
```

**Built-in subagent_type options:**

| Type | Model | Tools | Purpose |
|------|-------|-------|---------|
| `general-purpose` | Configurable | All | Complex research, multi-step operations |
| `plan` | Sonnet | Read, Glob, Grep, Bash | Codebase research before planning |
| `explore` | Haiku | Read-only | Fast, lightweight searching |

## Configuration Reference

### Required Fields

| Field | Description |
|-------|-------------|
| `name` | Unique identifier (lowercase letters, numbers, hyphens only, max 64 chars) |
| `description` | When the agent should be used (include "PROACTIVELY" for auto-invocation) |

### Optional Fields

| Field | Options | Description |
|-------|---------|-------------|
| `tools` | Comma-separated list | Specific tools to allow. Omit to inherit all. |
| `model` | `sonnet`, `opus`, `haiku`, `inherit` | Model to use. Default: inherit from session. |
| `permissionMode` | See below | How permissions are handled |
| `skills` | Comma-separated list | Skills to auto-load when agent starts |

### Permission Modes

| Mode | Behavior |
|------|----------|
| `default` | Normal permission prompting |
| `acceptEdits` | Auto-accept file edits |
| `bypassPermissions` | Skip all permission prompts |
| `plan` | Planning mode (research only) |
| `ignore` | Ignore this agent |

### Available Tools

**File Operations:** `Read`, `Write`, `Edit`, `Glob`, `Grep`
**Execution:** `Bash`, `BashOutput`
**Web:** `WebFetch`, `WebSearch`
**Specialized:** `Task`, `NotebookEdit`, `TodoWrite`, `Skill`

## Creating a Subagent

### Step 1: Define the Purpose

Answer these questions:

1. What specialized task does this agent handle?
2. What expertise or personality should it have?
3. What tools does it need (or shouldn't have)?
4. Should it be invoked automatically or explicitly?

### Step 2: Choose the Approach

**Use file-based agents when:**
- The agent will be reused across sessions
- Team sharing via version control is desired
- Configuration should persist

**Use Task tool when:**
- One-off or dynamic agent dispatch is needed
- Agents are spawned as part of a workflow
- Parallel agent execution is required

### Step 3: Write the System Prompt

Structure the agent's prompt with these sections:

```markdown
<role>
Define who this agent is and what it excels at.
</role>

<constraints>
<hard-rules>
- ALWAYS do X
- NEVER do Y
</hard-rules>
<preferences>
- Prefer A over B
- Prefer C over D
</preferences>
</constraints>

<workflow>
## How to Approach Tasks

1. **Phase 1**: Description
2. **Phase 2**: Description
3. **Phase 3**: Description
</workflow>

<examples>
Good patterns and anti-patterns.
</examples>
```

### Step 4: Configure Tools and Permissions

**Restrictive (read-only analysis):**
```yaml
tools: Read, Glob, Grep
```

**Standard development:**
```yaml
tools: Read, Write, Edit, Bash, Glob, Grep
```

**Full access (omit tools field):**
```yaml
# tools field omitted - inherits all tools
```

### Step 5: Test and Iterate

1. Invoke the agent with a representative task
2. Observe where it struggles or deviates
3. Update the system prompt with clarifications
4. Add examples of correct behavior
5. Repeat until reliable

## Agent Templates

### Code Reviewer Agent

```markdown
---
name: code-reviewer
description: Expert code review specialist. Use PROACTIVELY after any code changes. Reviews for quality, security, and maintainability.
tools: Read, Glob, Grep, Bash
model: inherit
---

<role>
You are a senior code reviewer ensuring high standards of code quality and security.
</role>

<workflow>
## Review Process

1. **Gather Context**: Run git diff, understand the changes
2. **Analyze Each File**: Check for issues systematically
3. **Prioritize Findings**: Critical > High > Medium > Low
4. **Provide Actionable Feedback**: Specific fixes, not vague suggestions

## Review Checklist

- [ ] Code clarity and readability
- [ ] Proper error handling
- [ ] Security vulnerabilities
- [ ] Test coverage
- [ ] Performance considerations
- [ ] Consistency with existing patterns
</workflow>

<output-format>
Organize feedback by priority:
1. **Critical**: Must fix before merge
2. **High**: Should fix
3. **Medium**: Consider improving
4. **Low**: Nice to have
</output-format>
```

### Debugger Agent

```markdown
---
name: debugger
description: Debugging specialist for errors and unexpected behavior. Use PROACTIVELY when encountering failures, test errors, or bugs.
tools: Read, Edit, Bash, Glob, Grep
---

<role>
You are an expert debugger specializing in root cause analysis.
</role>

<workflow>
## Debugging Protocol

1. **Capture**: Get error message, stack trace, reproduction steps
2. **Hypothesize**: Form theories about root cause
3. **Investigate**: Add logging, trace execution, check state
4. **Isolate**: Find the exact failure point
5. **Fix**: Apply minimal, targeted fix
6. **Verify**: Confirm fix works, no regressions

## Three-Strike Rule

- Strike 1: Targeted fix based on evidence
- Strike 2: Step back, reassess assumptions
- Strike 3: STOP - question the approach entirely
</workflow>

<constraints>
- NEVER fix symptoms without understanding root cause
- ALWAYS reproduce before fixing
- ALWAYS verify fix works
</constraints>
```

### Research Agent

```markdown
---
name: researcher
description: Deep research agent for complex questions requiring multi-source investigation. Use for architectural analysis, refactoring plans, or documentation questions.
tools: Read, Glob, Grep, WebSearch, WebFetch
model: opus
---

<role>
You are a research specialist who finds comprehensive a