agent-builder

# Agent Builder

A comprehensive guide for creating custom agents in Claude Code. Agents are specialized AI assistants that run in **separate context windows**, enabling focused, autonomous task execution.

---

## Quick Reference

### YAML Frontmatter Fields

| Field | Required | Description |
|-------|----------|-------------|
| `name` | Yes | Unique identifier (lowercase-with-hyphens) |
| `description` | Yes | When to invoke — **critical for discovery** |
| `tools` | No | Allowed tools (inherits all if omitted) |
| `model` | No | `haiku`, `sonnet`, `opus`, or `inherit` |
| `permissionMode` | No | `default`, `acceptEdits`, `bypassPermissions`, `plan` |
| `skills` | No | Auto-load Skills when agent starts |

### File Locations

| Scope | Location | Use Case |
|-------|----------|----------|
| Project | `.claude/agents/agent-name.md` | Team workflows (git-shared) |
| Personal | `~/.claude/agents/agent-name.md` | Individual use (all projects) |

### Common Tool Patterns

```yaml
# Read-only (safest)
tools: Read, Grep, Glob

# File modification
tools: Read, Write, Edit, Grep, Glob

# Git operations only
tools: Bash(git:*)

# Specific commands
tools: Bash(npm test:*), Bash(npm run:*), Read, Grep

# Full shell (use sparingly)
tools: Bash
```

### Model Selection Guide

| Model | Best For | Tradeoff |
|-------|----------|----------|
| `haiku` | Quick checks, simple tasks | Fast, cheap, less capable |
| `sonnet` | Balanced work (default) | Good balance |
| `opus` | Complex analysis, critical tasks | Most capable, slower, expensive |
| `inherit` | Consistency with main conversation | Adapts to user's model |

---

## 6-Phase Workflow

### Phase 1: Requirements Gathering

**Use AskUserQuestion** to understand what the user needs:

**Key Questions**:
1. What task should this agent handle?
2. What expertise/role should it have?
3. Who will use it — team or personal?
4. What should it be able to do vs NOT do?
5. How should it present results?

**Example Questions**:
```
What s