creating-subagent

# Custom Subagent Creation Guide

## Quick Start

**First, ask the user**:
- Where to create the subagent file?
  - `.claude/agents/` (project-scoped, shared via git)
  - `~/.claude/agents/` (user-scoped, personal across all projects)

Then create a `.md` file:
```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.
```

## Essential Structure

### YAML Frontmatter (Required)

| Field | Required | Description |
|-------|----------|-------------|
| `name` | Yes | Unique identifier (lowercase, hyphens) |
| `description` | Yes | When Claude delegates to this subagent |
| `tools` | No | Allowed tools (inherits all if omitted) |
| `disallowedTools` | No | Tools to deny |
| `model` | No | `sonnet`, `opus`, `haiku`, or `inherit` |
| `permissionMode` | No | `default`, `acceptEdits`, `dontAsk`, `bypassPermissions`, `plan` |
| `skills` | No | Skills to inject at startup |
| `hooks` | No | Lifecycle hooks for this subagent |

See [frontmatter.md](references/frontmatter.md) for complete reference.

### System Prompt (Body)

The markdown body becomes the subagent's system prompt. Include:
1. Role definition
2. Invocation behavior
3. Workflow steps
4. Output format

## Best Practices

### DO

**Write specific descriptions** (Claude uses this for delegation):
```yaml
# Good
description: Expert code reviewer. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.

# Bad
description: Reviews code
```

**Restrict tools appropriately**:
```yaml
# Good - read-only reviewer
tools: Read, Grep, Glob, Bash
disallowedTools: Write, Edit

# Bad - too permissive for a reviewer
tools: Read, Write, Edit, Bash
```

**Specify model based on task complexity**:
```yaml
# Fast exploration
model: haiku

# Complex analysis
m