Claude Code Subagents

A Claude Code subagent is a specialized worker with its own context, instructions, and tool access. It can handle a bounded research or review task and return a summary to the main conversation. A template is just a starting definition; the most useful one states when to delegate, which tools are allowed, and what a successful answer contains.

Define the handoff before choosing a template: the question to answer, the relevant files, and the evidence required in the response. A focused review or research task is easier to evaluate than a general request to improve everything. Keep the result format short enough for the main conversation to use directly.

Inspect the template’s tools and instructions together. A role called reviewer may still request shell or write access. If you only want observations, begin with a read-only definition and test it on a known issue. Change permissions when the task requires it, rather than relying on the role name.

The word “agent” may refer to an entire workflow or collection, whereas a subagent is often one worker definition. In Claude Code’s own documentation, custom subagents are specialized agents, so the distinction is mostly about packaging and intent. Browse the agents page for plugin-led workflows; use this page when you want an individual Markdown file you can read and adapt.

The distinction helps with browsing, but does not make one category inherently more capable. A plugin can package the same kind of Markdown worker that you could save manually. Compare the definition, dependencies, and invocation instructions to understand what the project adds beyond a role description.

Use one worker when the question is narrow. Use a larger workflow only when the source explains how its roles coordinate and combine results. Adding several similar workers can produce repeated findings and conflicting suggestions, so decide who owns each output before starting the task.

Save a project-specific file under `.claude/agents/` or a user-wide file under `~/.claude/agents/`. Use a descriptive filename ending in `.md`, include YAML frontmatter, and restart Claude Code if the agent directory was created after the session began. A plugin can install a collection for you, but a manual file is easier to inspect before use.

Download the example as code-reviewer.md and place it in the appropriate agents directory. Inspect the saved frontmatter and use /agents for setup guidance if needed. Keep project-specific instructions in the project version so a teammate can review the same definition rather than relying on your personal configuration.

Give the reviewer a specific question and a small set of files. Verify that it returns file paths and explains each issue. If the result is vague, improve the description and output requirements before expanding tool access; broader permissions do not fix an unclear task definition.

Keep each subagent focused on one type of task. Give it only the tools required, define the expected output, and try a small example before relying on automatic delegation. Treat copied definitions as code review material: a prompt can instruct a worker to run commands or disclose information just as scripts can. Revise templates when the project’s rules change.

Keep a small collection of representative tasks for manual checks when updating a template. Include a task with a known issue and one where no issue is expected. This helps reveal whether the worker is inventing findings or overlooking the conventions that matter to your project.

Ask the worker to separate observed facts from assumptions and unresolved questions. Review suggestions before applying changes, especially when several workers examine related files. Record useful role adjustments in the template so improvements survive beyond one conversation.