Claude – Sub Agents

Anthropic Claude – Sub Agents

Sub Agents:

·       Subagents are specialized assistants that Claude Code can delegate tasks to.

·       Think of them as focused helpers: each one runs in its own conversation context window, does its work, and returns a summary to the main thread

·       They break work into focused pieces, letting each subagent concentrate on a specific task

·       They keep your main context window clean by isolating all the intermediate work

·       They bring back just the information you need as a concise summary

Creating a Subagent

·       /agents slash command

·       Project-level — available only in the current project

·       User-level — shared across all projects on your machine

Customizing Tools

·       Read-only tools

·       Edit tools

·       Execution tools

·       MCP tools

·       Other tools

Choosing a Model and Color

·       Haiku — best for fast, lightweight tasks

·       Sonnet — a good middle ground between speed and depth

·       Opus — best for complex analysis

·       Inherit — uses whatever model your main conversation is running

The Config File

In project  .claude/agents/your-agent-name.md

Config file:

—

name: code-quality-reviewer

description: Use this agent when you need to review recently written or modified code for quality, security, and best practice compliance.

tools: Bash, Glob, Grep, Read, WebFetch, WebSearch

model: sonnet

color: purple

—

You are an expert code reviewer specializing in quality assurance, security best practices, and adherence to project standards. Your role is to thoroughly examine recently written or modified code and identify issues that could impact reliability, security, maintainability, or performance.

System Prompts

The body of the markdown file (everything below the YAML frontmatter) is the system prompt. This is where you give the subagent its instructions: what it should focus on, how it should analyze things, and how it should report findings back to the main agent.

A well-written system prompt is the difference between a useful subagent and one that misses the point. Be specific about what the subagent should look for and how it should structure its output.

Making Claude Use Your Subagent Automatically

·       Include the word “proactively” in the description field

·       Example:

description: Proactively suggest running this agent after major code changes…

Built-in Subagents

·       General purpose subagent — for multi-step tasks that require both exploration and action

·       Explore — for fast searching and navigation of codebases

·       Plan — used during plan mode for research and analysis of your codebase before presenting a plan

Poor Sub-Agent:

A subagent that’s poorly configured will wander, run too long, or produce output the main agent can’t use.

Fix:

The fixes come down to four things: writing good descriptions, defining an output format, reporting obstacles, and limiting tool access.

How Subagent Config Data Gets Used

·       Main context window agent  System Prompt (the name and description of every available subagent are included)

·       Better control over when a subagent gets triggered automatically, the name and description are what you should tweak.

·       The description doesn’t just control when a subagent runs — it shapes what the subagent is told to do.

Writing Descriptions That Shape Input Prompts

Defining an Output Format

The single most important improvement in a subagent is defining an output format in its system prompt. This does two things:

• It creates natural stopping points — the subagent knows it’s done when it has filled in each section of the format.
• It prevents the subagent from running too long. Without a defined output, subagents struggle to decide when enough research has been done and tend to run much longer than necessary.

Example of structured output format for a code review subagent:

Provide your review in a structured format:

1. Summary: Brief overview of what you reviewed and overall assessment

2. Critical Issues: Any security vulnerabilities, data integrity risks,

   or logic errors that must be fixed immediately

3. Major Issues: Quality problems, architecture misalignment, or

   significant performance concerns

4. Minor Issues: Style inconsistencies, documentation gaps, or

   minor optimizations

5. Recommendations: Suggestions for improvement, refactoring

   opportunities, or best practices to apply

6. Approval Status: Clear statement of whether the code is ready

   to merge/deploy or requires changes

This format gives the subagent a clear checklist to work through. Once every section is filled in, the subagent knows it can stop.

Reporting Obstacles

When a subagent discovers a workaround during its work — like solving a dependency issue or finding that a certain command needs particular flags — those details need to appear in the summary it returns.

The kinds of things you want surfaced include:

·       Setup issues or environment quirks

·       Workarounds discovered during the task

·       Commands that needed special flags or configuration

·       Dependencies or imports that caused problems

The way to get this information is to explicitly ask for it in the output format. Adding an “Obstacles Encountered” section to your output template surfaces this information reliably.

·       7. Obstacles Encountered: Report any obstacles encountered during the review process. This can be: setup issues, workarounds discovered or environment quirks. Report commands that needed a special flag or configuration. Report dependencies or imports that caused problems.

Limiting Tool Access

Not every subagent needs access to every tool. Think about what a subagent actually needs to do, and only give it the tools required for that job. This does two things: it prevents unintended side effects, and it makes each subagent’s role clearer when you have several of them.

Think about tool access for common subagent types:

·       Research / read-only subagent — Only needs Glob, Grep, and Read. Cannot accidentally modify files.

·       Code reviewer — Needs Bash access to run git diff and see what changed, but still doesn’t need Edit or Write.

·       Styling / code modification agent — This is where you give Edit and Write access, because the subagent’s job is to actually change your code.

Effective subagents share four characteristics:

1.          Specific descriptions — The description controls when the subagent is launched and what instructions it receives. Write it to steer both.

2.          Structured output — Define an output format in the system prompt so the subagent knows when it’s done and returns information the main thread can use.

3.          Obstacle reporting — Include a section in the output format for workarounds, quirks, and problems so the main thread doesn’t have to rediscover them.

4.          Limited tool access — Only give a subagent the tools it actually needs. Read-only for research, bash for reviewers, edit/write only for agents that should change code.

When subagents shine

·       Subagents work best when the exploration is separate from the execution

·        If each step in a task depends on what the previous step discovered, you want that work in your main thread.

·       But if you just need an answer and don’t care about the journey, delegate it.

·       Subagents excel at tasks where:

o   You need a result, not a play-by-play of how it was found

o   The exploratory work would clutter your main thread’s context

o   The task benefits from a fresh perspective or a custom system prompt

Research tasks

·       Research is the classic subagent use case

·       investigating how authentication works in an unfamiliar codebase

·       our main thread needs to know where the JWT is validated, but it doesn’t need to see every file that was searched along the way.

·       A research subagent can read dozens of files, trace through function calls, and explore different code paths. All that exploration stays in the subagent’s context. Your main thread receives a clean summary like:

·       
JWT validation happens in middleware/auth.js line 42,

·       called from the Express router in route/api.js

·       The subagent did the heavy lifting. Your main thread gets exactly what it needs to move forward.

Code Reviews

A reviewer subagent sees the changes in a separate context. It runs git diff, reads the modified files, and applies its specialized review criteria without the history of how the code was written. This separation also lets you encode project-specific review standards in the subagent’s system prompt, ensuring consistent review criteria across the team.

Custom System Prompts

Copywriting subagent – instructions about tone, audience, and style

Styling subagent — Point it at your design system files. Color variables, spacing conventions, and component patterns before it even starts writing any CSS

When Subagents Hurt

·       The overhead of launching a subagent — losing visibility into its work and compressing its findings into a summary

·       only makes sense when the subagent does something the main thread can’t.

Three common anti-patterns

Expert Claims – Prompts like “you are a Python expert” or “you are a Kubernetes specialist” add no value because Claude already has that knowledge.

There’s nothing a so-called expert subagent can do that your main thread can’t do directly

Sequential Pipelines

·       Sequential subagent pipelines create problems. 

·       Consider a three-agent flow: one to reproduce a bug, one to debug it, and one to fix it. Pipelines work when tasks are truly independent.

·       They fail when each step depends on discoveries from the previous step — and bug fixing almost always does. Information gets lost in the handoff between agents.

Test Runners

·       Test runner subagents tend to hide information you need. When tests fail, you want the full output to diagnose issues. 

·       A subagent that returns “tests failed” forces you to create additional debug scripts to get details that would have been visible in direct output.

·       Testing has shown that the test runner pattern performed worse among all configurations.

The Decision Rule

·       Ask yourself one question: does the intermediate work matter?

o   If the answer is no — you just need the final result — delegate it to a subagent. If the answer is yes — you need to see and react to what’s happening along the way — keep it in your main thread.

Use subagents for:

·       Research and exploration

·       Code reviews

·       Tasks that need a custom system prompt

Avoid subagents for:

·       “Expert” personas that don’t add real capability

·       Multi-step pipelines where each step depends on the last

·       Running tests where you need full output for debugging