subagents-reference

# Claude Code Subagents Reference

Subagents are specialized AI assistants that Claude can spawn for specific tasks. Define custom agents to extend Claude's capabilities.

## Agent File Locations

```
~/.claude/agents/              # User agents (all projects)
.claude/agents/                # Project agents (team shared)
```

## Agent File Format

```markdown
---
name: agent-identifier
description: What this agent does and when to use it
model: sonnet
tools:
  - Read
  - Grep
  - Glob
  - Bash
---

# Agent Name

Detailed instructions for the agent's behavior.

## Capabilities
- Specific task the agent handles
- Another capability

## Approach
How the agent should tackle problems.
```

## Frontmatter Fields

| Field | Required | Type | Description |
|-------|----------|------|-------------|
| `name` | No | string | Agent identifier for Task tool |
| `description` | Yes | string | When/why to use this agent |
| `model` | No | string | haiku, sonnet, opus |
| `tools` | No | array | Available tools |
| `allowed_tools` | No | array | Alias for `tools` |

## Built-in Agent Types

| Agent | Purpose | Tools |
|-------|---------|-------|
| `Explore` | Codebase exploration | Read, Grep, Glob |
| `general-purpose` | Multi-step tasks | All tools |
| `Bash` | Command execution | Bash |
| `Plan` | Implementation planning | All tools |

## Custom Agent Example

```markdown
---
name: security-reviewer
description: Review code for security vulnerabilities. Use when checking for injection, XSS, auth issues.
model: sonnet
tools:
  - Read
  - Grep
  - Glob
---

# Security Review Agent

You are a security specialist reviewing code for vulnerabilities.

## Review Checklist
1. SQL injection
2. XSS vulnerabilities
3. Authentication bypass
4. Sensitive data exposure
5. Insecure dependencies

## Process
1. Read the target files
2. Search for common vulnerability patterns
3. Report findings with severity ratings
```

## Invoking Agents

### Via Task Tool
```
Claude uses Task tool with:
- suba