Subagents in Depth: A Crew of Specialists

A deeper dive, @name. Captain Redbeard wants you to truly master subagents - the newest way to turn one first mate into a whole specialized crew.

Why Subagents?

When you ask one agent to do everything, its context fills up with unrelated details - like one sailor trying to navigate, cook, and repair the hull at once. Subagents solve this: each is a focused crewmate with its own prompt, its own tools, and its own clean context. The main session delegates and stays uncluttered.

Defining a Subagent

A subagent is a single markdown file under

.claude/agents/

. The file has frontmatter (name, description, tools) and a body (the system prompt):

1# Project subagents
2.claude/agents/code-reviewer.md
3.claude/agents/test-writer.md

A

code-reviewer.md

describes what the reviewer looks for, and restricts it to read-only tools so it can analyze but never edit. A

test-writer.md

is allowed to write files so it can create test suites.

Managing Subagents

Use the

/agents

slash command in the REPL to list, create, and edit your crew:

1/agents

How Delegation Works

Claude decides when to call a subagent based on the task and the agent's description. Ask "review my changes," and Claude hands the work to

code-reviewer

. Ask "add tests for this module," and

test-writer

steps up. You can also request one explicitly: "use the code-reviewer agent on @src/auth.ts."

Subagents and Plan Mode Together

For a large feature, combine the newest tools: run in Plan Mode so Claude proposes the steps, then let it delegate the review step to your

code-reviewer

subagent before you approve the final diff:

1# Plan first, then let subagents handle focused steps
2claude \
3  --permission-mode plan \
4  "Build a notifications feature, then have the code-reviewer check it"

A Disciplined Crew

With a few subagents in

.claude/agents/

, your ship runs like a well-drilled pirate crew: the navigator plots the course (Plan Mode), the specialists do their duties (subagents), and the captain (you) approves the treasure. 🏴‍☠️

See you on deck! 🚀