Claude Code Sub-agents Tutorial: How to Create and Use Sub-agents

Claude Code Sub-agents Tutorial: How to Create and Use Sub-agents

This is a practical guide to using Claude Code sub-agents, based on Anthropic's public documentation and common usage patterns. Commands and configuration fields may change — always check the official docs for the authoritative version.

If you use Claude Code for serious work, you have probably hit these two problems: the main conversation keeps growing, and the files it has read fill the context until the model starts to "forget" things; and for repeating task types (code review, writing tests) you have to restate the same requirements every time. Sub-agents exist to solve both: hand a class of work to a dedicated assistant with its own context window, and bring only the conclusion back to the main conversation. This tutorial walks through what sub-agents are, how to create them, how they get invoked, practical configurations, and common pitfalls — enough to get started today.

1. What a sub-agent is: a dedicated assistant with an isolated context

A sub-agent is a customizable "clone" inside Claude Code. Three properties matter:

• Isolated context window: once dispatched, the sub-agent reads files and runs commands on its own. None of that intermediate work takes up the main conversation's context; only the final result comes back.

• Its own system prompt and tool set: you write a separate job description (system prompt) for each sub-agent and limit which tools it may use — for example, a review-only sub-agent gets read access but no write access.

• Selectable model tier: use a stronger tier for heavy work and a cheaper tier for routine work, so you can control cost separately.

A one-line test for whether to use a sub-agent: the intermediate work is long, but you only need the conclusion — full-repository searches, batch reviews, parallel research. If the task is small, doing it in the main conversation is faster.

2. How to create a sub-agent: the agents directory and frontmatter

Claude Code sub-agents are defined as Markdown files in one of two places:

• .claude/agents/ — project level, committed with the repository, shared by the team;

• ~/.claude/agents/ — user level, applies to all of your projects.

Each file is YAML frontmatter plus a body (the body is the sub-agent's system prompt). A minimal code-review sub-agent looks like this:

---
name: code-reviewer
description: Reviews changes on the current branch for defects and security issues. Use proactively after writing code.
tools: Read, Grep, Glob, Bash
---

You are a senior code reviewer. Review the supplied changes file by file and output a list of
issues graded BLOCKER / MAJOR / MINOR, each with file and line number. Read only, do not modify;
if you find nothing blocking, say so explicitly.

Three fields matter:

• name: lowercase with hyphens; this is the name used for explicit invocation.

• description: the most important line and the easiest one to get wrong — it drives automatic delegation and should say when to use the sub-agent. Recommended format: "what it does + when to use it".

• tools: optional. Omit it and the sub-agent inherits every tool; follow least privilege and grant only what is needed (a reviewer should not get file-write access).

You can also skip the file and run /agents in an interactive session to create one through the guided flow; the result is the same.

3. How sub-agents get invoked: automatic delegation vs explicit calls

Once configured, there are two ways to use them:

1. Automatic delegation: Claude Code matches the current task against each sub-agent's description and hands the task over when it matches. This is why the description must spell out the use case — the more specific it is, the more accurate automatic triggering becomes.

2. Explicit invocation: name the sub-agent in the conversation, e.g. "use code-reviewer to review this change". Use the same channel to specify behavior, e.g. "use code-reviewer, auth module only".

Two usage notes:

• Parallelism: several independent sub-agents can be dispatched in the same message (for example, researching two different modules at once); total time is roughly that of the slowest one.

• Pass context: sub-agents cannot see your earlier conversation — they start as a newcomer. Put the necessary background into the request (goal, constraints, relevant file paths); do not expect them to guess.

4. Three configuration patterns worth copying

Dedicated reviewer: build a code-reviewer as in section 2, with read-only tools and graded output. It applies the same standard on every review, which is far more stable than an ad-hoc "take a look" in the main conversation.

Debugging squad: a debugger sub-agent with Bash and search tools, whose system prompt hard-codes the workflow — reproduce first, then localize, then give a root cause and the smallest proposed fix, with no opportunistic refactoring. The enormous logs produced during debugging stay in its own context; the main conversation only receives the conclusion.

Model tiering: routine, mechanical sub-agents (bulk renames, format checks) can specify a lightweight tier in frontmatter; only difficult analysis uses the heavy tier. Each sub-agent bills at its own tier, so tiering is a direct cost lever.

Finally, advice on quantity and naming: prefer few and specialized over many and generic. One sub-agent should own one class of task, and the name should say what it does (code-reviewer, test-writer). Keep the list under ten — the longer it gets, the less accurate automatic delegation becomes, and the higher the maintenance cost. Start with one or two high-frequency tasks and add more as the setup proves itself.

5. Common pitfalls and troubleshooting

• The sub-agent never triggers: nine times out of ten the description is too vague (e.g. "help me work"). Make the use case concrete: what the input is, and when it should be used.

• The sub-agent "does not know" what you discussed: that is not a bug, it is the design. Put the needed background into the request.

• Permission errors: check whether the frontmatter tools list is missing a tool the job requires.

• Poor result quality: usually the system prompt is too thin. Write the output format, grading standards, and prohibitions into the body — treat it as a job description for a new hire.

If you have not used Claude Code yet, read our Claude Code getting-started tutorial first, then come back to configure sub-agents; when you need to give a sub-agent external tools, see the Claude Code MCP server setup guide.

6. No official key? Start on CodeGateway

Using Claude Code through the official channel requires an API key and an overseas payment method, which stops a lot of people. If you do not have an official key, or do not want to bind a foreign card, you can get one directly at [CodeGateway](https://www.codegateway.dev/pricing): sign up and go, with OpenAI- and Anthropic-compatible endpoints, and Claude Code and sub-agents work as usual. Check the model catalog for available models, run your first sub-agent on a small budget, and scale up once the flow is verified.

This is a tool usage tutorial compiled from Claude Code's public documentation; the interface and fields may change between versions — refer to the official documentation.