Skip to content
explainroo
Working with AI agents

Claude Code Subagents: When and How to Use Them

Updated 4 min read

With explainroo How to Prompt a Coding Agent to Make an Explainer Video
On this page
  1. Delegate bounded, independent work
  2. Keep coupled work in the main session
  3. Create a subagent in Claude Code
  4. Write instructions the parent can use
  5. Choose between subagents, skills, and hooks

When Claude Code needs to inspect several parts of a codebase, research an unfamiliar library, or review changes, a subagent can handle one defined task and keep detailed exploration out of the main conversation. A subagent is a separate Claude assistant with its own context, instructions, and tool access. It returns a summary or result to the main Claude Code session, which coordinates the work.

Use subagents for independent, clearly defined tasks when the extra model work is worthwhile. Handle closely connected decisions in the main session, where Claude has the full conversation. Anthropic’s subagent documentation describes how to define and use them.

Delegate bounded, independent work

Subagents work best on tasks they can advance without frequent input from the main session. For example, one subagent can trace how authentication works while another examines the test suite. The main session can then compare their findings and decide what to change.

When an investigation produces many details, a subagent can inspect files and report the relevant findings without filling the main conversation with its exploration. Common uses include code review, debugging, test analysis, documentation research, and other read-heavy investigations. The Anthropic subagent tutorial covers delegating tasks with focused instructions.

Give each subagent a separate task. “Review the API” is broad and can overlap with other tasks. “Find where API requests validate user permissions, and report relevant files and missing checks” gives the agent a clearer boundary and a useful result to return.

Keep coupled work in the main session

A subagent is a poor fit when a task depends on many decisions from the conversation or on another agent’s findings. Subagents do not share their working context directly. The main session must pass information between them and resolve any differences in their results. That coordination can outweigh the benefit of splitting the task.

Avoid assigning multiple subagents to edit the same files at once. They can make conflicting changes, and the parent session then has to resolve them. For a small change or a task with closely linked steps, have Claude Code do the work in the main session.

Subagents also add model work, which increases token use. Delegate when the benefit is worth the extra work. Reviewing separate modules in parallel can make sense, while splitting a simple one-file fix usually adds overhead without much benefit.

Create a subagent in Claude Code

To set up an agent interactively, use the built-in /agents command. To define a reusable agent in a file, create a Markdown file with YAML frontmatter in .claude/agents/ for the current project or ~/.claude/agents/ for your user account. The Claude Code SDK documentation also describes defining agents programmatically through the SDK.

Give the agent a specific role, clear instructions, and only the tools it needs. For example, a code-review agent should know whether to report findings only or also make changes. Limiting its tools to the task reduces the chance that it takes unrelated actions. Use project-level definitions for instructions tied to a codebase. Use user-level definitions to make an agent available across projects.

Do not assume Claude Code will choose a custom agent every time. If you need a particular role, name it in your prompt and say which task to delegate. Reports about automatic selection describe it as inconsistent, so direct delegation gives you more control.

Write instructions the parent can use

A useful delegation prompt tells the main session what to assign, what the subagent should return, and what to do if it cannot finish the task. For example, ask one agent to inspect a module for input-validation gaps and return file paths with concise findings. Have it report any tests or permissions it could not verify. The parent can then decide whether to request a fix or investigate further.

Say what the subagent should return before it starts. A short report is easier to use than an open-ended summary. It should give the findings and relevant file paths, and flag any unanswered questions. For implementation tasks, state which files the agent owns and whether it should run tests. The main session should review the work and check important changes instead of treating the subagent’s report as proof.

Choose between subagents, skills, and hooks

Use a subagent when Claude needs to hand off a task to a separate assistant and receive a result. A skill provides reusable instructions or knowledge that Claude can apply in a session. A hook runs a configured command when a Claude Code event occurs. The feature comparison summarizes these different roles.

For example, use a skill for a review procedure Claude should follow repeatedly. A check that should run automatically after a tool event fits a hook. A separate investigation of a specific pull request fits a subagent. These features can complement each other: a subagent can follow a review skill, while a hook runs a check at a configured point.

Free and open source

Let your AI agent make the video

explainroo lets a coding agent like Claude Code or Codex make narrated explainer videos and product demos. The voice, the word timing and the rendering run on your own computer, with no API key and no cost per video. Optional outside services use your own key.

Copy this into your AI agent

Make me a short explainer video about [your topic]. Use explainroo for it: run npx --yes explainroo docs and follow what it prints.

Getting started Example videos GitHub

Made with explainroo: How explainroo makes a video

More on working with ai agents

All guides on working with ai agents