creating-agents

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

Project agents take priority over user agents.

Step 3: Select Tools and Model

Tools - Grant minimum needed:

Model - Choose based on task:

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:

When to create custom agents:

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

When to Use Each Type

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.