How to Create Custom Claude Code Subagents (Config Guide)

There’s a hard limit in any single AI coding session: the context window. If one conversation contains a large refactor, multiple test runs, review notes, and follow-up fixes, the agent eventually loses focus. Claude Code subagents solve this by splitting work into focused workers. Each subagent has its own context window, instructions, and tool permissions. It completes one job, returns a result, and keeps the main thread clean.

Try Apidog today

This guide shows how to create Claude Code subagents as Markdown config files, how each frontmatter field works, how Claude decides when to delegate, and how to set up a practical workflow where one subagent reviews code while another writes and runs API tests. For the conceptual overview, read what Claude Code sub-agents are and why they matter. Here, the focus is implementation.

TL;DR

Create a Claude Code subagent by adding a Markdown file to .claude/agents/.

The file contains:

• name: the subagent identifier
• description: the delegation trigger Claude reads
• tools: an optional tool allowlist
• model: an optional model override
• body content: the subagent’s system prompt

Each subagent runs in its own context window with its own tools and instructions. Claude can delegate automatically based on the description, or you can invoke a subagent by name.

Official reference: Claude Code subagents docs.

Subagents in 60 seconds

A subagent is a separate agent instance that the main Claude Code agent delegates work to.

Think of the main agent as the lead engineer and subagents as specialists:

• a code reviewer
• a test writer
• a security auditor
• a documentation writer
• an API verification agent

Subagents are useful because they have three key properties.

1. Separate context window

A subagent starts with the task it is given, not the entire main conversation. Its intermediate work does not pollute the main context.

2. Custom system prompt

You define how the subagent behaves. For example:

• “Review for security issues and correctness bugs.”
• “Write tests using the existing project style.”
• “Validate API responses against the OpenAPI schema.”

3. Configurable tools

You can restrict what each subagent can access. A reviewer might only need read tools. A test runner might need shell access. This supports least-privilege workflows.

For more background on why this matters, see the conceptual overview and the related Claude Code agent harness architecture.

Why use subagents?

Use subagents when you want isolation, parallelism, and specialization.

Context isolation

Long coding sessions degrade as the context fills with file reads, test output, implementation notes, and unrelated branches of reasoning.

Delegating a large task to a subagent keeps that work out of the main thread. The main agent receives a summary instead of thousands of tokens of intermediate output.

This also helps with cost control because the main context stays smaller. For more on that angle, see reducing agent token costs.

Parallelism

Independent tasks do not need to run sequentially.

For example, after implementing an endpoint, the main agent can dispatch:

• one subagent to review the implementation
• one subagent to write tests
• one subagent to update docs

The total time becomes closer to the slowest single task instead of the sum of all tasks.

Claude Code’s dynamic workflows push this further with large fan-out patterns.

Specialization

A general agent can do many things, but a focused subagent can do one thing more consistently.

A reviewer with an adversarial prompt will find different issues than a generalist. A test writer that knows your conventions will produce tests that better match your project.

How to create a custom subagent

Subagents are plain Markdown files.

Use:

.claude/agents/

for project-level subagents.

Use:

~/.claude/agents/

for personal subagents.

Each file has YAML frontmatter plus a body that becomes the system prompt.

Here is a code-reviewer subagent:

---
name: code-reviewer
description: "Reviews code changes for bugs, security issues, and convention violations. Use after writing or editing code."
tools: Read, Grep, Glob
model: sonnet
---

You are a senior code reviewer. When given a diff or a set of files:

1. Look for correctness bugs, security holes, and missed edge cases.
2. Check that the code matches the project's existing conventions.
3. Report only high-confidence issues, ranked by severity.

Be specific. Cite file and line. Do not rubber-stamp.

Frontmatter fields

Field	Purpose
name	Identifier used to invoke the subagent
description	Delegation trigger Claude reads
tools	Optional allowlist of tools
model	Optional model override

The description field is especially important. Write it as a usage trigger, not just a label.

Good:

description: Reviews code changes for bugs, security issues, and convention violations. Use after writing or editing code.

Weak:

description: Code reviewer.

The body is the subagent’s system prompt. Treat it like onboarding instructions for a specialist:

• what to do
• what to prioritize
• what to ignore
• how to report results

If your project uses a design.md or AGENTS.md, reference those conventions instead of repeating them in every subagent file.

How to invoke subagents

There are two ways to use a subagent.

Automatic delegation

Claude reads the description field of available subagents and delegates when the task matches.

For example, after editing code, Claude may call code-reviewer if its description says:

Use after writing or editing code.

Clear descriptions make automatic delegation more reliable.

Explicit invocation

You can also call a subagent directly:

Use the code-reviewer subagent on the changes in the orders module.

Or:

Use the api-test-writer subagent to write tests for the new POST /orders endpoint.

The subagent runs in its own context, completes the task, and returns a result to the main thread.

For deterministic chaining, slash commands and the SDK provide more control than ad hoc prompting. See the Claude Code overview for the broader configuration surface.

Subagents vs Agent SDK vs dynamic workflows

These tools overlap, but they fit different control models.

Tool	Control model	Best for
Subagents	Model decides when to delegate, or you invoke one by name	In-session specialization and light parallelism
Dynamic workflows	Model orchestrates large fan-out in one session	Many parallel tasks and broad sweeps
Agent SDK	You write the control flow in code	Deterministic loops, scheduled jobs, and unattended runs

Use subagents when you are working interactively in Claude Code and want focused specialists.

Use the Claude Agent SDK when you need programmatic orchestration, scheduled runs, or unattended loops.

If you are comparing hosted and custom orchestration approaches, see managed agents vs Agent SDK.

Practical example: parallel review and test writing

Assume the main agent just implemented a new orders endpoint.

You want two things:

1. a code review
2. API test coverage

Those tasks are independent, so run them in parallel.

First, define the code-reviewer subagent from above.

Then add an API test writer:

---
name: api-test-writer
description: Writes API test cases for new or changed endpoints. Use after an endpoint is implemented.
tools: Read, Grep, Write, Bash
model: sonnet
---

You write API tests against the project's OpenAPI spec.

1. Read the spec and the endpoint implementation.
2. Write tests covering success, validation errors, and auth.
3. Assert status codes and validate response bodies against the schema.
4. Run the suite and report pass/fail with reasons.

Now prompt the main agent:

The orders endpoint is implemented. Use code-reviewer to review the changes and api-test-writer to write and run API tests.

Claude can dispatch both subagents:

• code-reviewer reads the diff and reports issues
• api-test-writer reads the OpenAPI spec, writes tests, runs them, and reports pass/fail

The main thread receives two focused summaries instead of all intermediate review and test output.

Make the test subagent a verification gate

The test-writing subagent is most useful when it does more than generate test files. It should run the tests and return a verdict.

That turns it into a verification gate:

Endpoint implementation -> test subagent -> pass/fail verdict

This follows the core idea behind coding agent loops: the agent’s confidence does not count; the gate’s result does.

For API work, wire the test subagent against a real API testing workflow. Teams using Apidog can point the subagent at an Apidog test scenario so responses are schema-validated. You can also route live endpoint calls through the Apidog AI agent debugger to inspect requests and responses more like a human tester would.

The same pattern can be wrapped into unattended workflows, like the setup described in Claude workflows that run without you.

If you want schema-aware API testing available out of the box, download Apidog.

Best practices

Keep one responsibility per subagent

A reviewer should review. A tester should test. A documentation subagent should write docs.

Avoid building one large “do everything” subagent. That recreates the main-agent problem.

Write descriptions as delegation triggers

The description field controls automatic delegation.

Use trigger language:

description: Reviews code for correctness and security. Use after editing code.

Avoid vague labels:

description: Code review expert.

Grant least privilege

Do not give every subagent every tool.

For example:

tools: Read, Grep, Glob

is enough for a read-only reviewer.

A test runner may need:

tools: Read, Grep, Write, Bash

Restricting tools matters more when agents run unattended.

Choose the right model per job

Use faster or cheaper models for mechanical tasks. Use stronger models for hard reasoning tasks.

For example:

• test fixture generation: faster model
• security review: stronger model
• documentation cleanup: faster model
• architectural analysis: stronger model

Return structured results

Ask subagents to report in a predictable shape.

Example reviewer output format:

## Verdict
Pass | Needs changes

## Issues
1. Severity: High
   File:
   Line:
   Problem:
   Suggested fix:

## Notes
Additional observations.

Example test output format:

## Verdict
Pass | Fail

## Tests added
- ...

## Test results
- ...

## Failures
- ...

Structured results are easier for the main agent to act on.

Avoid deep nesting

Do not create chains where subagents call subagents that call more subagents. It becomes hard to debug and can increase cost.

Keep the hierarchy shallow:

Main agent -> subagent

or:

Main agent -> several parallel subagents

These patterns match the wiring principles in agentic workflow tool wiring.

When to use subagents

Use subagents for tasks that are:

• bounded
• independent
• noisy

Good examples:

• reviewing a completed diff
• writing tests for a new endpoint
• reproducing a bug
• auditing a module for security issues
• checking API responses against a schema
• summarizing a large part of the codebase

These tasks have a clear scope and produce lots of intermediate work that does not need to live in the main context.

When not to use subagents

Skip subagents for tasks that are:

• small
• tightly coupled to the main conversation
• sequential with the current implementation work

Examples:

• renaming a variable
• fixing a one-line bug
• changing a single import
• editing code where the main agent already has all context in view

If the main agent would need to explain half the conversation just to brief the subagent, keep the work in the main thread.

Rule of thumb:

Delegate work that is self-contained enough to describe in a paragraph and valuable enough to run in parallel.

A new endpoint that needs review and tests fits. A typo fix does not.

For larger fan-out, see dynamic workflows.

Common mistakes

Vague descriptions

Bad:

description: Testing agent.

Better:

description: Writes and runs API tests for new or changed endpoints. Use after endpoint implementation.

One bloated subagent

Do not combine review, testing, docs, and deployment checks into one subagent.

Split by responsibility.

Inheriting all tools by default

If you omit tools, the subagent inherits the main agent’s tools.

That may be fine for trusted interactive work, but it is risky for automated workflows. Prefer explicit allowlists.

No verification subagent

A review-only workflow can still ship broken code.

Add a subagent that actually runs tests and reports pass/fail.

Treating subagents like the SDK

Subagents are in-session and model-dispatched.

If you need deterministic scheduled control flow, use the Agent SDK instead of trying to build a large orchestration system from subagents alone.

Anthropic’s building effective agents makes the broader point: good structure around the model often beats one larger prompt.

Frequently asked questions

What is a Claude Code subagent?

A Claude Code subagent is a separate agent instance delegated to by the main Claude Code agent. It has its own context window, custom system prompt, and configurable tools. It performs a focused task and returns the result.

How do I create a Claude Code subagent?

Create a Markdown file in .claude/agents/ for project-level use or ~/.claude/agents/ for personal use.

Add YAML frontmatter:

---
name: code-reviewer
description: Reviews code changes for bugs and security issues. Use after editing code.
tools: Read, Grep, Glob
model: sonnet
---

Then write the subagent’s system prompt in the body.

How does Claude decide which subagent to use?

Claude reads each subagent’s description field and delegates when the current task matches. You can also invoke a subagent explicitly by name.

What is the difference between subagents and the Claude Agent SDK?

Subagents are interactive and model-dispatched inside Claude Code.

The Agent SDK is programmatic. You write the control flow in code, which makes it better for deterministic loops, scheduled jobs, and unattended automation.

Can subagents run in parallel?

Yes. The main agent can dispatch multiple subagents for independent tasks. For example, review, testing, and documentation can run at the same time.

How do subagents help with API testing?

Define a subagent that writes and runs API tests against your OpenAPI spec. It becomes a verification gate that checks whether the endpoint actually works.

Pointing that workflow at a platform like Apidog makes the feedback schema-aware because responses can be validated against the API contract.

The takeaway

Claude Code subagents help you avoid overloading one context window. Each task gets its own context, instructions, and tools, so the main agent can coordinate a small team of specialists instead of doing everything itself.

Start with two subagents:

1. a code reviewer
2. an API test writer

Give each a clear delegation-oriented description, restrict tools to what the role needs, and make the test subagent run real verification.

For endpoint work, Apidog gives your test gate a schema to validate against. Download it if you want your subagent to prove the API works before you trust the diff.