Claude Code subagents: a practical guide to writing your own

Most people start with Claude Code as one long conversation. That works until the conversation fills up with test logs, search results and half-finished ideas, and the model starts losing track of what matters. Subagents fix that. They let you hand a focused job to a separate agent, with its own instructions and its own tools, and get back only the result.

I use custom subagents every day, including on a production trading terminal where implementer and reviewer agents do most of the volume. I wrote about that whole pipeline separately. This post is the practical part: how Claude Code subagents work and how to write good ones.

Claude Code changes fast. Everything below matches the official subagents documentation as of late 2026, but check the docs for your version before relying on a specific field.

What Claude Code subagents are

A subagent is a specialised assistant that the main Claude Code session can delegate to. Three things make it useful:

Its own context window. The subagent doesn't see your conversation history. The main session writes it a task, the subagent works independently, and only its summary comes back. Verbose output stays out of your main context.
Its own system prompt. The body of the subagent file becomes its instructions. You can write a strict rulebook for one job without cluttering every other task.
Its own tool access. You can give a subagent only the tools it needs. A reviewer can read code without being able to edit it.

The trade-off is that a subagent starts cold. It knows only what the delegation message tells it, so the quality of that handoff matters.

Where the files live

A subagent is a Markdown file with YAML frontmatter. The two locations you'll use most:

.claude/agents/ in your repository, for project subagents. Commit them so the whole team shares the same agents.
~/.claude/agents/ in your home directory, for personal subagents available in all your projects.

If two subagents share a name, the project one wins over the personal one. Claude Code also scans subfolders, so you can organise agents into directories. The agent's identity comes from its name field, not the file path.

The frontmatter fields that matter

Only two fields are required:

name: a unique identifier, for example code-reviewer.
description: when Claude should delegate to this agent. This is the most important line in the file.

The optional fields I use most:

tools: an allowlist of tools. If you leave it out, the subagent inherits all available tools.
model: which model runs the agent, or inherit to use the main session's model.
maxTurns: a cap on how many agentic turns the subagent can take before it stops.
permissionMode: how the subagent handles permission prompts.
isolation: set to worktree to give the subagent its own git worktree, so it can't collide with other work in your checkout.

There are more fields (hooks, skills, MCP servers, memory and others), but you can get far with the ones above.

How delegation works

Claude delegates automatically when a task matches a subagent's description. Writing "use proactively" in the description encourages it to delegate without being asked.

You can also be explicit:

By name, in plain language: "Use the code-reviewer subagent to review the auth changes."
By @-mention, which guarantees that specific subagent runs.
For a whole session, by starting Claude Code with that agent as the main agent.

Claude Code also ships with built-in subagents, including Explore (fast, read-only codebase search), Plan (read-only research used in plan mode) and general-purpose (full tools for multi-step tasks). Before writing a custom agent, check whether a built-in one already does the job.

Two example definitions

A read-only reviewer. It can look but not touch, and it has to back up every claim:

---
name: code-reviewer
description: Reviews a diff for correctness bugs. Use proactively after code changes.
tools: Read, Grep, Glob, Bash
model: inherit
maxTurns: 40
---

You review one change. Your job is to find what the author missed,
not to confirm it works.

Rules:
- Read the diff and the code it touches. Run the existing tests.
- Report only findings you can reproduce with a failing test or command.
- For each finding: file, line, what breaks, and the repro.
- If you find nothing provable, say "no findings". Do not pad the list.

An implementer that works in isolation and stops at the gates:

---
name: implementer
description: Implements one scoped ticket end to end in an isolated worktree.
isolation: worktree
model: inherit
---

You implement exactly one ticket.

- Read the ticket and the relevant contract or spec first.
- Write the code and the tests together.
- Before reporting done, run lint, the full test suite and the build.
- Report: what changed, which files, gate results. If a gate fails, say so.

The reviewer's rule about reproducible findings isn't decoration. Without it, AI reviewers produce plausible noise. I explain why in every AI code reviewer needs a failing repro.

Design tips

Write the description for the router

The description is what Claude reads to decide whether to delegate. Make it say when, not just what: "Reviews a diff for correctness bugs after code changes" beats "Expert code reviewer". Keep it short. Every description takes up space in the main session's context, and Claude Code warns you when the combined descriptions of your custom subagents get too large.

Give the fewest tools that work

A reviewer that can edit files will eventually "fix" what it was supposed to report. A research agent doesn't need write access. Narrow tool lists make agents more predictable and safer.

Define the return format

The main session only sees the summary. Tell the subagent exactly what to return: a list of findings with repros, a short report with gate results, a set of file paths. A rambling summary wastes the context you were trying to save.

One job per agent

"Implement, test, review and document" is four agents pretending to be one. An agent with a single job and a clear rulebook is easier to debug when it goes wrong.

Common pitfalls

Assuming the subagent knows the context. It doesn't see your conversation. If it needs the ticket, the branch or a constraint, the delegation has to say so.
Letting agents grade their own homework. The implementer shouldn't be the one deciding its work is correct. Use gates and a separate reviewer.
No turn limit. An agent stuck in a loop keeps spending tokens. maxTurns is cheap insurance. I cover more cost traps in how to reduce LLM costs.
Too many overlapping agents. If two descriptions match the same task, delegation becomes unpredictable. Merge or sharpen them.

Working together

I'm Driss Briksine, a software and ML engineer. I build multi-agent systems and use custom Claude Code subagents to ship production code, like the trading terminal I work on. If you want a subagent setup designed for your team's codebase, send me a short brief.