How to Build Custom Claude Code Agents

What are Claude Code agents?

Claude Code agents are specialist subprocesses that handle complex tasks autonomously. Instead of doing everything in one conversation, you delegate work to focused agents that have their own tools, memory, and instructions.

Think of it like hiring specialists. Your main session is the project manager. Agents are the developers, reviewers, and analysts who do the actual work.

Why custom agents matter

The built-in Agent tool spawns general-purpose agents. That works for simple tasks. But when you need an agent that knows your codebase, follows your conventions, and remembers lessons from past work, you need custom agents.

Custom agents let you define:

• Which tools the agent can access (and which it can't)
• What model to use (haiku for speed, opus for quality)
• Specific instructions tailored to the task domain
• Persistent memory that survives across sessions

Creating your first agent

Agent definitions live in .claude/agents/. Each agent is a markdown file with YAML frontmatter.

Here's a minimal agent definition:

---
name: reviewer
model: haiku
tools:
  - Read
  - Grep
  - Glob
  - LS
---

# Review Agent

You are a code review specialist. Review changes for:
1. Security issues (hardcoded secrets, SQL injection, XSS)
2. Performance problems (N+1 queries, missing indexes)
3. Convention violations (naming, file structure)

You are READ-ONLY. Never modify files. Report findings only.

Save this as .claude/agents/reviewer.md and Claude Code can now spawn it as a subagent.

The YAML frontmatter explained

Every agent needs these fields:

name, How the agent identifies itself. Used in logs and when spawning.

model, Which Claude model to use. Options:

• haiku: Fast and cheap. Good for simple reviews, searches, formatting
• sonnet: Balanced. Good for most tasks
• opus: Most capable. Use for complex reasoning, architecture decisions

tools, A YAML list of tools the agent can access. This is your security boundary. A review agent that can only Read files can't accidentally delete your database.

Common tool patterns:

• Read-only agent: Read, Grep, Glob, LS
• Write agent: Read, Write, Edit, Bash
• Full agent: All tools including Agent (can spawn sub-agents)

Adding persistent memory

Agents forget everything between sessions by default. To give an agent persistent memory, create a memory file:

.claude/agent-memory/reviewer/MEMORY.md

The agent reads this file at startup and writes learnings after completing work. Over time, your review agent learns patterns specific to your codebase.

Example memory entry:

## Known Patterns
- API routes in `src/api/` always need auth middleware
- The `utils/` folder has no test coverage - flag any changes there
- Client-specific config lives in `.claude/clients.yml`, not hardcoded

This is how agents get smarter without you manually updating their instructions. For a deeper dive into memory architecture, see our guide on Claude Code memory systems.

Agent orchestration patterns

Sequential delegation

The simplest pattern. Your main session spawns Agent A, waits for results, then spawns Agent B with those results.

Main → Agent A (research) → Main → Agent B (implement) → Main

Parallel delegation

Spawn multiple agents simultaneously for independent tasks. This is the power pattern for large codebases.

Main → Agent A (frontend) + Agent B (backend) + Agent C (tests) → Main

Agent chains

Agents that spawn other agents. Your architect agent analyzes the task, then spawns implementation agents for each component. Learn more about this in our subagents guide.

Tool allowlists as security

The tools list isn't just configuration: it's a security boundary. Consider these patterns:

Auditor agent, Can read anything but only write to specific files:

tools:
  - Read
  - Grep
  - Glob
  - Edit  # Can edit, but hooks enforce which files

Research agent, Can search the web but not modify your code:

tools:
  - WebSearch
  - WebFetch
  - Read

Deployment agent, Can run specific bash commands:

tools:
  - Bash(git:*)
  - Bash(npm:*)
  - Read

The Bash(command:*) syntax restricts which commands the agent can run. A deployment agent that can only run git and npm commands can't accidentally rm -rf your project.

Real-world agent examples

SEO Agent

Runs audits, tracks rankings, analyzes competitors. Has its own memory of keyword data and content performance.

Content Engine

Produces content through a multi-step pipeline: research → outline → draft → review → publish. Each step can be a separate agent call.

Dashboard Agent

Syncs data from external APIs, manages database queries, monitors health metrics. Restricted to specific API endpoints and database tables. See how Claude Code hooks can enforce these restrictions automatically.

Common mistakes

Too many tools. Start restrictive, add tools as needed. An agent with every tool is just another general-purpose session.

No memory file. Without persistent memory, agents repeat the same mistakes every session. Always create a MEMORY.md.

Vague instructions. "Review code" is too broad. "Review for security issues in API routes, checking for auth middleware and input validation" gives the agent focus.

Wrong model. Don't use opus for simple grep-and-report tasks. Don't use haiku for complex architectural decisions. Match the model to the task complexity.

FAQ

How many agents can run simultaneously?

Claude Code can spawn multiple agents in parallel. The practical limit depends on your API rate limits and context window, not a hard cap. Three to five parallel agents is a sweet spot.

Do agents share context with the main session?

No. Each agent starts fresh with only the prompt you give it. They can read your project files, but they don't see the main session's conversation history. This is by design, it prevents context pollution.

Can agents spawn other agents?

Yes, if the Agent tool is in their tool allowlist. This enables hierarchical orchestration where a planning agent delegates to implementation agents.

---

Building custom agents turns Claude Code from a single assistant into a coordinated team. Start with one agent for your most repetitive task, give it memory, and iterate from there.

Want a complete agent system with 9 pre-built specialists, persistent memory, and orchestration patterns? Check out Claudify, it ships with everything described above, ready to use.