How to Use Claude Sub-Agents: A Developer's Guide to Task Delegation in Claude Code

Most developers get real value from Claude Code long before they need sub-agents. A single session can inspect a repo, edit files, run tests, and explain tradeoffs. The trouble starts when one conversation becomes your implementation thread, your research notebook, your browser scratchpad, your log sink, and your review checklist all at once.

That is where sub-agents become useful. In Claude Code, a sub-agent is a specialized worker with its own system prompt, its own context window, its own tool access, and optionally its own model, permission mode, memory, or MCP servers. Instead of stuffing every side task into the main session, you delegate bounded work outward and get a distilled answer back.

For developers already using Claude Code, this is one of the cleanest ways to reduce context bloat and make delegation feel practical instead of theatrical. For teams evaluating agent workflows from Cursor or VS Code, sub-agents are also a helpful mental model: the real unlock is not "more AI," it is giving different AI workers different jobs, boundaries, and output contracts.

One caveat matters for AICoach readers: the current AICoach VS Code / Cursor extension at /extension does not yet ship a dedicated sub-agent management UI. Today, you still create and manage Claude sub-agents inside Claude Code itself with /agents, claude agents, or markdown files in .claude/agents/. AICoach is still useful around that workflow because it already helps you browse skills, discover MCP servers, and compare surrounding tooling on /marketplace, but the dedicated agent-management layer is still planned rather than shipped.

What A Claude Sub-Agent Actually Is

Claude Code already includes built-in sub-agents such as Explore, Plan, and general-purpose. Those cover common delegation patterns:

• Explore is a fast, read-only researcher for code search and repo discovery.
• Plan is a read-only research agent used while Claude is gathering context for a plan.
• general-purpose is the broader worker Claude can delegate to when a task needs both investigation and action.

Custom sub-agents let you define your own versions of that pattern. Each one lives as a markdown file, usually in .claude/agents/ for project-shared agents or ~/.claude/agents/ for personal agents. Claude uses the agent's description field to decide when it should delegate to it, so the definition is both configuration and routing logic.

The key thing to understand is separation. A sub-agent does not simply continue your current conversation in a smaller box. It gets its own prompt and its own working constraints. That is exactly why the feature is useful: a reviewer can be strict and read-only, a test triager can run shell commands but not edit files, and a browser tester can get Playwright access without polluting the main session with browser tool descriptions.

If you need multiple agents coordinating across separate sessions, that is a broader agent-team problem. Sub-agents are the lighter-weight, single-session delegation mechanism.

Main Claude session
   |
   |-- Explore --------------------> "Map auth flow across the repo"
   |
   |-- code-reviewer -------------> "Review staged changes, findings only"
   |
   |-- browser-smoke-tester ------> "Validate signup flow in a real browser"
   |
   +--------------------------------> Synthesize results and decide next step

When Delegation Actually Pays Off

Sub-agents are worth the extra setup when they create one of three advantages.

The first is context isolation. Suppose you are implementing a billing change and need to answer a side question like "where do we normalize subscription state?" That search may require reading ten files, tracing two services, and skimming old tests. Useful work, but noisy. Offloading that to an Explore-style sub-agent keeps the main thread focused on the actual implementation decision.

The second is parallelism. If three questions are independent, there is no reason to answer them sequentially in one conversation. "Trace the auth middleware." "Find existing button patterns." "Identify tests that cover the dashboard." These can often run in parallel, then come back as a structured summary.

The third is fresh perspective. Review is where this matters most. If the same conversation that wrote the code is also trying to review the code, it is more likely to rationalize the exact tradeoffs it just made. A fresh, read-only sub-agent can act more like a real second pass.

Use sub-agents when:

• The task would flood the main session with search results, logs, or exploratory notes.
• The work is independent enough to run in parallel.
• You want a specialist persona with narrower tools or permissions.
• You need a fresh review without all the assumptions in the parent thread.

Do not reach for sub-agents when:

• Two workers would be editing the same tightly coupled files.
• The task is simple enough to answer directly.
• The subtask depends on every nuance of the ongoing conversation.
• You are expecting one sub-agent to recursively orchestrate others. In Claude Code, sub-agents themselves do not spawn more sub-agents.

The right prompt usually sounds more like delegation than magic. Instead of "look into this," say something like: research these three areas in parallel, return a three-part summary, and do not make edits. Specific scope plus a concrete deliverable is what makes delegation reliable.

Quickstart: Create Your First Useful Agent

The easiest way to create a sub-agent is the /agents command inside Claude Code. That opens the built-in sub-agent manager, where you can create a personal agent in ~/.claude/agents/ or a project agent in .claude/agents/.

For most teams, the best default is project-scoped agents checked into version control. That turns good delegation habits into shared infrastructure instead of personal lore. Personal agents are still great for cross-project helpers like release-note writers or generic code reviewers.

A practical setup flow looks like this:

1. Run /agents.
2. Choose Project if the agent belongs to the repo, or Personal if it should travel with you.
3. Write a clear description that tells Claude when to delegate.
4. Pick the smallest useful tool set.
5. Choose a model based on the work: lower-cost for lightweight research or summarization, stronger reasoning for implementation or review.
6. Save it, then test it with an explicit prompt.

You can also list what Claude currently sees from the terminal with claude agents. If you create files manually, restart the session or reopen /agents so Claude reloads them.

Scope matters because different definitions can override each other. The practical precedence is:

Highest priority
1. Managed settings
2. `--agents` CLI definitions for the current session
3. `.claude/agents/`      project-scoped, ideal for teams
4. `~/.claude/agents/`    personal, available across projects
5. Plugin agents
Lowest priority

That order is useful in practice. A team can define project agents, while individual developers keep a few personal helpers without trampling shared conventions.

Anatomy Of A Good Agent File

A sub-agent definition is just a markdown file with YAML frontmatter followed by the prompt body. Only name and description are required, but the power comes from the rest of the fields.

• Field: name | Why it matters: Stable identifier for explicit invocation and organization
• Field: description | Why it matters: The routing trigger Claude uses to decide when to delegate
• Field: tools / disallowedTools | Why it matters: Least-privilege control over what the agent can do
• Field: model | Why it matters: Cost and capability tradeoff per agent
• Field: permissionMode | Why it matters: How aggressively the agent can operate without prompts
• Field: maxTurns | Why it matters: Prevents runaway or overly chatty sub-agents
• Field: mcpServers | Why it matters: Gives an agent task-specific external tools
• Field: skills | Why it matters: Preloads reusable workflow content into the agent
• Field: isolation | Why it matters: worktree lets risky or parallel edits happen safely
• Field: memory | Why it matters: Lets an agent accumulate persistent learnings over time

Two rules matter more than the rest.

First, your description is a trigger, not a slogan. "Security expert" is vague. "Reviews auth, payments, and data-handling changes for security issues before commits" is much easier for Claude to route correctly.

Second, the body prompt should define the output contract. Do you want prioritized findings, a patch plan, a repro command, a pass/fail test report, or a list of blockers? If you do not say that explicitly, you often get a rambling summary instead of a useful deliverable.

It is also important to know what a sub-agent does not inherit. In Claude Code, sub-agents get their own system prompt rather than the entire main-session prompt stack. They also do not automatically inherit whatever skills you happened to load in the parent conversation. If you want skill content available inside the sub-agent, list it with skills:.

Need an always-on rule for every session?  -> `CLAUDE.md`
Need a reusable specialist worker?         -> sub-agent
Need a reusable multi-step playbook?       -> skill
Need external systems or live tools?       -> MCP server

That distinction is useful if you are also using AICoach. Browse reusable playbooks in Skills, connect external tools through the MCP Registry, and use sub-agents as the specialist workers that combine those pieces at runtime.

Six Copyable Sub-Agent Templates

The fastest way to learn sub-agents is to define a few that solve real development pain. The examples below are intentionally practical, not clever. Copy them, then tighten the descriptions and prompts around your own stack.

1. A Read-Only Code Reviewer

This is the highest-ROI agent for most teams because it is safe, easy to reason about, and immediately useful.

---
name: code-reviewer
description: Reviews staged or recent code changes for correctness, maintainability, and security. Use proactively after implementation and before commits or pull requests.
tools: Read, Glob, Grep
model: sonnet
maxTurns: 6
color: blue
---

You are a senior code reviewer.

Focus on:
- correctness and edge cases
- security and data handling
- maintainability and readability
- regressions against existing patterns

Return:
1. A prioritized findings list
2. The risk of each finding
3. Concrete remediation advice

If you find no material issues, say so clearly.

2. A Test Failure Triager

This agent is useful when the job is not "fix everything," but "reproduce the failure, narrow the blast radius, and tell me the smallest next move."

---
name: test-triager
description: Reproduces failing tests, isolates the likely cause, and recommends the smallest next fix. Use for local failures, flaky CI runs, or red test suites after refactors.
tools: Bash, Read, Glob, Grep
model: sonnet
maxTurns: 8
color: orange
---

You are a test triage specialist.

When invoked:
- reproduce the failure with the smallest command possible
- identify whether the problem is test code, product code, environment, or data setup
- prefer narrowing the cause over broad speculation

Return:
1. The reproduction command
2. The suspected root cause
3. The smallest safe next action
4. Any blockers or missing environment details

Do not edit files.

3. A Browser Smoke Tester With Playwright MCP

This is where sub-agents start to feel like infrastructure rather than prompting tricks. The agent gets browser tooling only when you need it.

---
name: browser-smoke-tester
description: Runs browser smoke tests on user-facing flows after UI or auth changes. Use for navigation bugs, form regressions, and release checks.
disallowedTools: Write, Edit
mcpServers:
  - playwright:
      type: stdio
      command: npx
      args: ["-y", "@playwright/mcp@latest"]
model: sonnet
maxTurns: 10
color: cyan
---

You are a browser smoke tester.

Use the Playwright tools to validate the requested flow end to end.

Capture:
- the exact path taken
- any failing step or visual regression
- a concise pass/fail summary

If login, captcha, missing seed data, or permissions block progress, stop and report the blocker instead of guessing.

If you are not sure which tool integrations belong inside agents like this, the AICoach MCP Registry is the right place to discover candidates such as Playwright, GitHub, or database servers.

4. An API Implementer That Preloads Skills

Sub-agents and skills work especially well together. The sub-agent gives you the specialist persona and permissions; the skill provides reusable workflow content.

---
name: api-implementer
description: Implements backend endpoints once the contract is clear. Use for focused API work that needs code changes, tests, and convention-following output.
tools: Read, Edit, Write, Glob, Grep, Bash
skills:
  - api-conventions
  - error-handling-patterns
model: sonnet
permissionMode: acceptEdits
maxTurns: 12
color: green
---

You are an API implementation specialist.

Follow the preloaded skills and existing project conventions.

When invoked:
- inspect nearby handlers, validation, and tests first
- implement the smallest complete solution
- run the most relevant verification commands

Return:
1. What changed
2. What was verified
3. Any follow-up risks or assumptions

This pattern is a strong fit for teams already standardizing workflows through shared skill libraries. If you are building that library, AICoach Skills is a useful reference point for how reusable agent workflows are structured.

5. An Isolated Refactor Worker

Sometimes the task is safe in principle but noisy in practice: a rename, a cleanup pass, or a contained extraction that touches several files. isolation: worktree is a good match there.

---
name: refactor-worker
description: Handles contained refactors that may touch several files but should stay isolated until reviewed. Use for renames, extraction work, and low-risk structural cleanup.
tools: Read, Edit, Write, Glob, Grep, Bash
model: sonnet
permissionMode: acceptEdits
isolation: worktree
maxTurns: 12
color: purple
---

You are a refactoring specialist working in an isolated git worktree.

Your job is to make a contained structural improvement without changing behavior.

Before finishing:
- summarize changed files
- note any behavior risks
- list verification commands run

Avoid opportunistic drive-by changes outside the requested scope.

This is one of the cleanest ways to combine parallelism and safety. You can ask the main session to keep moving while the refactor worker explores in isolation.

6. A Low-Cost Release Note Writer

Not every agent needs the strongest model. Summary and copy-heavy work is a good place to be cost-conscious.

---
name: release-note-writer
description: Drafts release notes and shipped summaries from recent code changes. Use after a merge batch, deploy window, or weekly release review.
tools: Read, Glob, Grep, Write
model: haiku
memory: project
maxTurns: 5
color: yellow
---

You are a technical release-note writer.

Write concise, user-facing release notes in plain English.

Prefer:
- outcomes over internal implementation details
- grouped bullets by feature area
- caveats when behavior changed or rollout is partial

Keep the tone clear and factual.

This example also shows why memory should be deliberate. Persistent memory can help an agent learn your preferred structure over time, but it can also carry stale assumptions if you never revisit it.

How To Get Claude To Use These Reliably

Defining the file is only half the job. Good delegation comes from how you ask.

The most reliable prompts do four things:

• They define the exact scope.
• They say whether work can run in parallel.
• They specify the output format.
• They say whether the agent should stay read-only or can make changes.

Good examples:

• "Use the code-reviewer agent on the staged changes and return prioritized findings only."
• "Research this in parallel: trace auth middleware, identify the database writes, and list tests touching signup. Return a three-part summary."
• "Use a fresh read-only sub-agent to review my payment flow implementation. I want an unbiased assessment, not a defense of our previous discussion."

Poor examples tend to be vague: "look around," "check if this is okay," or "handle the testing part." Those force Claude to guess the scope and the deliverable.

The description field matters even more than most people expect. That is the field Claude uses to decide when to route work automatically. Treat it like a trigger sentence: what task shape should make Claude think, "this belongs to that specialist"?

Use CLAUDE.md To Turn Good Habits Into Policy

Sub-agents define your specialists. CLAUDE.md defines when Claude should reach for them automatically.

That is the right place for team-wide delegation policy. If every review should use a read-only reviewer, or every UI validation should go through a browser tester, say that once in CLAUDE.md instead of relying on memory and repetition.

## Delegation policy

When asked to review code, use the `code-reviewer` sub-agent.
When asked to validate a user flow, use the `browser-smoke-tester` sub-agent.
When implementing backend endpoints, use `api-implementer` only after the API contract is clear.

This is also where Claude Code-specific workflows differ from Cursor-style general prompting. If your team uses both tools, it helps to keep the ideas portable but the implementation honest: the exact .claude/agents/ mechanism is Claude Code-specific, while the principle of bounded delegation applies more broadly.

How AICoach Fits Into The Workflow Today

Today, the AICoach extension available on /extension and the Visual Studio Marketplace is best thought of as the supporting layer around sub-agents, not the place where sub-agents themselves are managed.

What it already does well today:

• Browse and install reusable workflows from Skills
• Discover and install external tool integrations from the MCP Registry
• Audit the AI tools installed in your environment
• Track Claude and Cursor usage from the editor sidebar

What it does not yet do today:

• Provide a dedicated Agents tab for creating, discovering, and monitoring Claude sub-agents

That distinction matters because it changes how you should set expectations with your team. Right now, the practical workflow is:

1. Define and manage sub-agents in Claude Code.
2. Use AICoach to discover supporting MCP servers and shared skills.
3. Use project-level agent files plus CLAUDE.md to make delegation consistent.

For Cursor-heavy teams, that still makes AICoach relevant. You can use the extension for skills, MCP, setup visibility, and usage tracking while evaluating whether Claude Code's sub-agent model should become part of your workflow. Just do not present the current extension as if it already includes a shipped agent-management console.

Common Mistakes To Avoid

Most sub-agent failures are design failures, not model failures.

• Too-vague descriptions: If the description is generic, Claude will route inconsistently or not at all.
• Too many tools: Defaulting every agent to full write access defeats the point of specialization.
• Parallel edits to the same area: Two agents touching the same tightly coupled code is conflict bait.
• No output contract: If you do not define the deliverable, you often get verbose summaries instead of something actionable.
• Using memory casually: Persistent memory is powerful, but stale assumptions can accumulate.
• Creating an agent for every buzzword: Start with a few high-value specialists, not a zoo.

One simple rule helps: if an agent does not clearly save time, improve safety, or improve signal quality, do not keep it.

A Sensible Rollout Plan For Teams

If you are introducing sub-agents to a team instead of just experimenting solo, keep the rollout small.

1. Start with two or three shared agents, usually a reviewer, a test triager, and one domain-specific worker.
2. Store repo-specific agents in .claude/agents/ and check them into version control.
3. Add a short delegation policy to CLAUDE.md.
4. Keep tool permissions narrow until a broader set is justified.
5. Review agent prompts monthly the same way you would review scripts or CI jobs.

That last point is easy to miss. Sub-agents are part of your development system. Treat them like code: version them, simplify them, and remove agents that are no longer pulling their weight.

Final Takeaway

Claude Code sub-agents are not interesting because they are "multi-agent." They are useful because they make delegation concrete. A noisy research task can move out of your main thread. A review can come from a fresh, read-only perspective. A browser tester can get just the tools it needs. A refactor can happen in isolation.

If you are starting from zero, build three things first: a read-only reviewer, a test triager, and one domain-specific worker tied to the kind of work your team does every week. Then add policy in CLAUDE.md, connect external tools through MCP where it actually helps, and use AICoach for the surrounding skills and discovery layer.

That is usually enough to move from "one giant AI conversation" to a workflow that actually feels like task delegation.