Claude Code Agents — How They Work and When to Use Them

Claude Code is great when you're driving one thread of work. When you need to run three threads in parallel, or want a fresh pair of eyes on a decision, or need to scope out a large refactor without polluting your main session — that's what Agents are for.

This is what Claude Code Agents actually are, when to use them, and how to write your own.

What Claude Code Agents actually are

An Agent (sometimes called a subagent) is an isolated work thread you spawn from the main Claude Code session via the Agent tool. It has its own context — fresh, with no visibility into your conversation. You hand it a self-contained prompt; it does the work; it returns a single message at the end.

Three things make this different from just asking Claude another question:

1. Isolated context. The agent doesn't see what you've been doing. It can't drift on assumptions from your conversation. You brief it like a colleague who just walked in.
2. Parallel execution. You can spawn multiple agents in one message. They run concurrently, each on its own task.
3. Contained output. The agent's full reasoning happens in its own context. Only its final message comes back to your main session. Your main context stays clean.

That last point matters more than people realize. Without agents, every research query, every search, every "let me look around the codebase first" eats your main session's context budget. Agents let you delegate that work and only see the conclusion.

When to spawn an agent (and when not to)

Spawn an agent when:

• You need parallel work. Three independent research questions = three agents running concurrently, not three sequential queries.
• The work produces verbose output you don't need to see. Searching the codebase for every reference to getSession(), scanning logs, scoping a big refactor — the output is large but only the summary matters.
• You want an independent opinion. Agents don't see your reasoning so far. A code-reviewer agent reviewing your diff gives you a real second opinion, not a confirmation of what you've already decided.
• You're building something agentic. If your final product is a multi-agent workflow (research → write → review), prototyping with Claude Code Agents is the fastest path.

Skip agents when:

• The task is a single step the main session can do directly (read one file, run one command). Agent overhead isn't worth it.
• You need the result in your working tree, not just summarized. Skills are the right tool for that.
• The task depends heavily on conversation context. An agent that doesn't know what you've been working on can't help.

How to spawn an Agent

In Claude Code, the Agent tool takes:

• subagent_type — which agent definition to use (general-purpose, Explore, Plan, or a custom one from .claude/agents/)
• description — a 3-5 word summary
• prompt — the full self-contained brief

The prompt is the most important part. The agent has no context — it cannot ask you questions, cannot see your files unless told to. Write the brief like an email to a smart colleague:

Audit what's left before this branch can ship. Check:
uncommitted changes, commits ahead of main, whether tests
exist, whether the GrowthBook gate is wired up, whether CI
files changed. Report a punch list — done vs missing.
Under 200 words.

Goal stated, scope listed, response length capped. The agent does the rest.

The three categories of Claude Code Agents

1. Built-in general-purpose agents. Handle open-ended research and multi-step tasks. Spawn one when you don't know exactly what you'll need, and the agent figures it out.

2. Specialized shipped agents. Claude Code ships with task-specific agents — Explore for code search, Plan for implementation planning, code-reviewer for diff review. Each is tuned for its job. Faster than writing your own when the use case matches.

3. Custom agents. This is the leverage point. You define your own specialists in .claude/agents/ (project) or ~/.claude/agents/ (user). Examples that ship value:

• migration-reviewer — reviews database migrations for safety under concurrent writes
• pr-summarizer — reads a diff and writes a PR description in your team's style
• dependency-auditor — scans package.json + lockfile for CVEs and outdated packages
• pricing-coach — challenges your pricing decisions with structured questions

Writing a custom Claude Code Agent

A custom agent is one Markdown file. Frontmatter on top, system prompt below.

---
name: migration-reviewer
description: Use this agent when reviewing database migrations for safety. Reads the migration file, checks for blocking locks under concurrent writes, evaluates backfill strategies, and reports a pass/fail with reasoning.
allowed-tools: Read, Bash, Grep
---
 
You are a senior database engineer reviewing a migration file
for safety in production.
 
For each migration you receive, evaluate:
1. Lock behavior under concurrent writes
2. Backfill safety on tables > 10M rows
3. Rollback path
4. Index creation strategy (CONCURRENTLY vs blocking)
 
Report: VERDICT (pass/fail), specific risks, recommended changes.
Keep the review under 300 words.

Save as .claude/agents/migration-reviewer.md. In the next session, when you ask Claude to review a migration, the routing prompt sees the description and Claude can invoke this agent via the Agent tool with subagent_type: "migration-reviewer".

The description is what Claude reads to decide when to route. Write it as a trigger sentence ("Use this agent when…"), not a description ("This agent reviews…"). Triggers route; descriptions don't.

Patterns that ship value

After building a stack of custom agents, the ones that get used share traits.

Single clear job. pricing-coach is for pricing decisions. seo-audit is for SEO audits. Avoid general-helper — no one remembers when to invoke it.

Self-contained prompts in the main session. The main Claude knows what the agent does, so it doesn't pass half-context. The agent gets a complete brief or the agent fails.

Concise output. A good agent returns 200-500 words of conclusions, not a 3000-word log of its reasoning. The user wants the verdict, not the journey.

Parallel-friendly. If you have an agent that takes 90 seconds to run, design it so 5 of them can run in parallel without stepping on each other. Stateless agents > stateful ones.

Claude Code Agents vs API Agents

A Claude Code Agent is a feature of the Claude Code CLI. It runs locally, has filesystem access, returns to your interactive session. Best for development workflows where the output lives in your terminal and your repo.

An Anthropic API Agent (built with the Claude API directly) is a programmatic agent you call from your own code — typically running on a server, returning JSON or text to your application. Best for production application logic.

Same model, different surface. Use Claude Code Agents for "I'm building" workflows; use API Agents for "I shipped this in production" workflows.

A first agent to try

Build a branch-readiness agent. Everyone has branches that should ship but aren't sure they're ready.

---
name: branch-readiness
description: Use this agent to audit what's left before the current branch can ship. Checks git state, test coverage of changes, feature flag wiring, and CI-relevant file changes. Returns a punch list.
allowed-tools: Bash, Read, Grep
---
 
Audit the current branch for ship-readiness.
 
Run:
- git status (check uncommitted changes)
- git log main..HEAD (changes since main)
- ls .github/workflows/ (which CI files exist)
 
For each modified file:
- Check if tests exist for it
- Check if feature flag wraps the change (if flag system present)
 
Report:
DONE: [list]
MISSING: [list]
RISKS: [list]
Verdict: SHIP / NOT YET / NEEDS REVIEW
 
Under 300 words.

Save it, run /agent branch-readiness or ask Claude "is this branch ready to ship?". Watch it audit your branch in 30 seconds and tell you what's left.

That's the entire point of Claude Code Agents: codify a senior teammate's checklist, summon it on demand, parallelize it.

Related: Claude Code Subagents — deep dive on parallel spawning · Claude Code Skills — workflows you reuse · Claude Code Plan Mode — shortcut and full guide · Claude Code MCP — connect servers and add tools