Creating Agents

Guides creation of Claude Code subagents for task delegation.

Quick Start

1. Define agent purpose (what task does it handle?)
2. Choose location (project or user level)
3. Select tools (minimal set needed)
4. Write system prompt
5. Save to .claude/agents/

Workflow: Create New Agent

Progress:
- [ ] Define purpose and triggers
- [ ] Choose storage location
- [ ] Select tools and model
- [ ] Write system prompt
- [ ] Create agent file

Step 1: Define Purpose

Ask user:

• What specific task should this agent handle?
• When should it be invoked? (trigger phrases)
• Should it run proactively or on-demand?

Step 2: Choose Location

Location	Path	Use For
Project	.claude/agents/	Team-shared, project-specific
User	~/.claude/agents/	Personal, cross-project

Project agents take priority over user agents.

Step 3: Select Tools and Model

Tools - Grant minimum needed:

Tool	Purpose
Read	Read files
Write	Create files
Edit	Modify files
Glob	Find files
Grep	Search content
Bash	Run commands
Task	Spawn subagents

Model - Choose based on task:

Model	Best For
opus	Complex reasoning, nuanced decisions
sonnet	General tasks (default)
haiku	Quick lookups, simple analysis
inherit	Use parent's model

Step 4: Write System Prompt

Keep prompts focused:

• State the agent's role clearly
• Define scope and constraints
• Provide examples if helpful
• Avoid unnecessary detail

Step 5: Create Agent File

---
name: {agent-name}
description: {when to use - include trigger words}
tools: Read, Grep, Glob
model: sonnet
---

{System prompt here}

Save to .claude/agents/{name}.md

Agent File Format

---
name: agent-name          # Required: lowercase, hyphens
description: |            # Required: when to invoke
  Reviews code for quality issues.
  Use when user asks for code review.
tools: Read, Grep, Glob   # Optional: omit to inherit all
model: sonnet             # Optional: opus, sonnet, haiku, inherit
permissionMode: default   # Optional: permission handling
skills: skill1, skill2    # Optional: auto-load skills
---

System prompt defining the agent's behavior.

Built-in Agents

Before creating custom agents, know what's built-in:

Agent	Model	Tools	Purpose
general-purpose	sonnet	All	Complex multi-step tasks
plan	haiku	Read, Glob, Grep, Bash	Research and strategy
explore	haiku	Read, Glob, Grep	Fast codebase exploration

When to create custom agents:

• Need different tool restrictions
• Want domain-specific prompts
• Need proactive invocation

When to Use Each Type

Need	Use
Quick file search	Built-in explore
Research before planning	Built-in plan
Multi-step code changes	Built-in general-purpose
Code review with specific rules	Custom reviewer agent
Security analysis	Custom security agent
Domain expertise (DB, API, etc.)	Custom specialist agent

Proactive Invocation

To make Claude automatically use your agent, include in description:

• "PROACTIVELY" or "MUST BE USED"
• Clear trigger conditions

description: |
  PROACTIVELY reviews all code changes before commit.
  MUST BE USED when user mentions "review" or "check code".

Templates

Use templates from templates/ directory:

• templates/reviewer.md - Code review agent
• templates/researcher.md - Read-only research
• templates/specialist.md - Domain expert

See reference.md for complete configuration details.