---
name: task-agent-patterns
description: |
  Patterns for spawning and using agents via the Task tool in Claude Code.
  Use this skill when spawning Explore, Plan, general-purpose, or custom agents,
  when needing to understand agent types and capabilities, when writing effective
  agent prompts, or when using background/parallel agents. Triggers: "spawn agent",
  "Task tool", "subagent", "general-purpose agent", "Explore agent", "parallel agents",
  "background agent", "resume agent", "agent patterns".
---

# Task Agent Patterns

Comprehensive guide to spawning and using agents via the Task tool.

## Overview

The Task tool launches specialized agents (subprocesses) to handle complex tasks autonomously. Each agent operates in an isolated context window, enabling parallel execution and specialized workflows.

## Available Agent Types

| Agent Type | Model | Tools | Best For |
|------------|-------|-------|----------|
| `Explore` | Haiku | Read-only | Fast codebase search, file discovery |
| `Plan` | Inherited | Read-only | Planning mode research |
| `general-purpose` | Inherited | All tools | Complex multi-step tasks |
| `Bash` | Inherited | Bash | Terminal commands in isolation |
| Custom agents | Configurable | Configurable | Specialized workflows |

## When to Use Each Agent

### Use `Explore` When:
- Searching codebase without making changes
- Quick file lookups and pattern matching
- Answering "where is X?" questions
- Parallel research across multiple areas

**Thoroughness levels:**
- `quick` - Targeted lookups, fast responses
- `medium` - Balanced exploration
- `very thorough` - Comprehensive multi-location analysis

### Use `general-purpose` When:
- Task requires both reading AND writing
- Complex reasoning with multiple steps
- Need full tool access (WebSearch, Edit, etc.)
- Research that leads to modifications

### Use `Plan` When:
- In plan mode gathering context
- Need read-only research for planning

## Task Tool Parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| `subagent_type` | Yes | Agent type to use |
| `prompt` | Yes | Instructions for the agent |
| `description` | Yes | 3-5 word summary |
| `run_in_background` | No | Run asynchronously (default: false) |
| `resume` | No | Agent ID to continue previous work |
| `model` | No | Override model (sonnet/opus/haiku) |

## Prompt Writing Best Practices

### 1. Single Clear Goal
```
prompt: "Find all files that handle user authentication and list their paths with a brief description of each"
```

### 2. Include Completion Criteria
```
prompt: "Research the payment module. Return:
  - File paths involved
  - Key functions and their purposes
  - External dependencies
  - Potential security concerns"
```

### 3. Specify Output Format
```
prompt: "Analyze error handling patterns. Return a markdown table with:
  | File | Pattern Used | Recommendation |"
```

### 4. Define Scope Boundaries
```
prompt: "Focus only on the src/api/ directory. Do not explore frontend code."
```

## Parallel Agent Spawning

### Capacity
- Up to 7 agents can run simultaneously
- Tasks queue if limit exceeded

### Pattern: Parallel Research
```
# Send multiple Task calls in single message:

Task(subagent_type: "Explore", prompt: "Analyze frontend architecture in src/components/")
Task(subagent_type: "Explore", prompt: "Analyze backend services in src/api/")
Task(subagent_type: "Explore", prompt: "Analyze database layer in src/models/")
```

### Best Practices for Parallel
- Each agent needs focused, non-overlapping scope
- Works best for read/research tasks
- Avoid parallel writes to same files
- Request synthesis of findings after completion

## Background Agents

### How to Use
```
Task(
  subagent_type: "general-purpose",
  prompt: "Comprehensive security audit of authentication system",
  run_in_background: true
)
```

### Limitations
- Inherit parent's permissions only
- MCP tools NOT available
- Cannot ask clarifying questions
- Permission failures fail silently

### Monitoring
- Use `/tasks` to view running agents
- Read output file to check progress
- Resume in foreground if permissions needed

## Resuming Agents

### When to Resume
- Continue previous work with additional instructions
- Add context after initial exploration
- Handle permission failures from background runs

### Pattern
```
# Initial task returns agent_id: "agent_abc123"

# Resume with additional instructions:
Task(
  resume: "agent_abc123",
  prompt: "Now also check for SQL injection vulnerabilities in the queries you found"
)
```

### Session Persistence
- Transcripts stored in `~/.claude/projects/{project}/{sessionId}/subagents/`
- Can resume after restarting Claude Code
- Auto-cleanup after 30 days (configurable)

## Common Patterns

### Pattern 1: Research Then Implement
```
# Step 1: Research with Explore
Task(subagent_type: "Explore", prompt: "Find all places where user roles are checked")

# Step 2: Implement with general-purpose
Task(subagent_type: "general-purpose", prompt: "Add admin role check to the endpoints found above")
```

### Pattern 2: Parallel File Analysis
```
# Spawn in parallel for independent analysis
Task(subagent_type: "Explore", prompt: "Analyze authentication module")
Task(subagent_type: "Explore", prompt: "Analyze authorization module")
Task(subagent_type: "Explore", prompt: "Analyze session management")
```

### Pattern 3: Background Long-Running Task
```
Task(
  subagent_type: "general-purpose",
  prompt: "Run full test suite and report failures",
  run_in_background: true
)
# Continue working while tests run
```

### Pattern 4: Chained Agents
```
# Use one agent's output as input to next
Task(subagent_type: "Explore", prompt: "Find performance bottlenecks")
# After completion:
Task(subagent_type: "general-purpose", prompt: "Optimize the bottlenecks found: [list from previous]")
```

## When NOT to Use Agents

### Use Main Conversation Instead When:
- Task needs frequent back-and-forth
- Quick, targeted changes (1-2 files)
- Multiple phases share significant context
- Latency matters (agents start fresh)

## Troubleshooting

| Issue | Solution |
|-------|----------|
| Agent can't find files | Use absolute paths or clear directory references |
| Background agent fails silently | Resume in foreground to see errors |
| Agent gives incomplete results | Make prompt more specific with explicit deliverables |
| Agent takes too long | Use `Explore` with `quick` thoroughness |
| Parallel agents overlap | Define non-overlapping scopes clearly |