You keep asking Claude Code to review a pull request, and the main conversation fills up with diffs, grep output and half-relevant file reads. By the time it writes feedback, the context is cluttered and the review reads like it. A subagent fixes this: a specialist with its own context window and its own instructions.
The direct answer is to create a Markdown file with YAML frontmatter in .claude/agents. The details are where most first attempts go wrong, so this walkthrough covers:
- where the file lives and what each frontmatter field does
- how to write a system prompt that the subagent follows
- how to test it and fix a subagent that never triggers
- example templates you can adapt
- how subagents differ from Skills, and when to use which
What users report
Users discussing subagents in Claude Code mostly describe how to trigger them, control them and keep them from cluttering a session. The threads below are short community posts, not verified guides.
What users say works
- One Reddit user says subagents can be used anywhere, and that you can simply tell Claude to use one. They add that this is useful in planning because file-reading noise doesn't pollute the main context.
- A post on How to force the use of subagent says a built-in "Plan" subagent can be triggered manually by typing @agent-plan.
- Another user reports in Made Claude spawn its own sub-agents (recursive that sub-agents can spawn further sub-agents, creating a recursive exploration tree.
Gotchas
- Claude may launch subagents when you don't want them. In How to disable subagents on Claude Code?, a user says deterministic blocks require hooks, and shares a hook that blocks the Explore subagent type.
- A thread on skills versus spawned subagents notes that subagents don't automatically get skills. According to that user, you define the skills in the subagent's front matter.
Tips users share
- Name the subagent explicitly in your prompt when you need it to run.
- Use subagents for file-heavy exploration to protect the main context.
- Use hooks, not instructions alone, if a subagent type must never run.
- List any skills a subagent needs in its front matter.
What is a Claude Code subagent?
A Claude Code subagent is a specialist assistant that runs with its own context window, its own system prompt, and its own set of allowed tools. The main Claude Code session hands it a task, the subagent works on it separately, and only the result comes back to the main conversation.
This separation is the main reason claude code subagents are useful. Searching a codebase, reading logs, or reviewing a diff can fill a context window with material you do not need later. A subagent absorbs that noise and returns a summary.
When a subagent beats a single prompt
A single general prompt works for small, self-contained tasks. A subagent tends to be the better choice when:
- The task is noisy. Heavy exploration or verbose output stays out of your main context.
- The role is repeatable. A code reviewer or test runner follows the same instructions every time.
- Tools should be limited. A reviewer can be restricted to read-only tools, which lowers the risk of unwanted edits.
- The work is specialized. A narrow, focused prompt usually keeps the agent on task better than one prompt covering everything.
How Claude decides to delegate
Each subagent has a name and a description. Claude reads these descriptions and compares them with your request, then delegates when one clearly fits. You can also name a subagent directly and ask for it.
Because of this, a precise description matters. A vague one makes automatic delegation less reliable.
How to create a Claude Code subagent
You create a Claude Code subagent by adding a Markdown file with YAML frontmatter to an agents folder, either inside your project or in your user-level Claude directory. The file defines the agent's name, purpose, tools and system prompt. Claude Code then loads it and can delegate matching tasks to it.
Step 1: Create the agents folder
In your project root, create a .claude/agents directory:
mkdir -p .claude/agentsFor an agent you want available in every project, use ~/.claude/agents instead.
Step 2: Create a Markdown file with frontmatter
Add a file such as code-reviewer.md. The frontmatter sits between two --- lines at the top:
---
name: code-reviewer
description: Reviews code changes for bugs, style and security issues. Use after edits are made.
tools: Read, Grep, Glob
model: sonnet
---The fields work like this:
- name: a unique identifier, usually lowercase with hyphens.
- description: tells Claude when to delegate to this agent. Be specific about the task and trigger.
- tools: a comma-separated list of tools the agent may use. If you omit it, the agent typically inherits the available tools.
- model: the model the agent runs on, such as sonnet, opus or haiku. Omitting it uses the default.
Step 3: Write the system prompt
Everything below the frontmatter becomes the agent's system prompt. State its role, the steps it should follow and the format of its output.
You are a senior code reviewer. Examine the recent changes,
list problems by severity, and suggest concrete fixes.
Do not modify files.Keep the prompt focused on one job. Narrow agents with limited tools are easier to predict than broad ones.
Step 4: Choose project or user scope
| Scope | Location | Best for |
|---|---|---|
| Project | .claude/agents | Team-shared agents, committed to version control |
| User | ~/.claude/agents | Personal agents used across all projects |
If two agents share a name, the project-level one generally takes priority over the user-level one.
Step 5: Confirm it appears in /agents
Open Claude Code and run /agents. Your new agent should be listed with its scope. You can also create and edit agents from this interface, which writes the same kind of file for you.
If the agent is missing, check that the file ends in .md, the frontmatter is valid, and the folder path is correct. Restarting the session often resolves loading issues for manually created files.
How do you write a good subagent prompt and description?
Write the description as a trigger: it should say what the agent does and when Claude should hand work to it. Write the prompt as a short job brief with a clear role, steps, an output format and limits. The description decides whether the agent gets used at all, and the prompt decides how well it does the work.
Write the description as a delegation rule
Claude reads the description to decide whether a task belongs to this subagent. Vague text such as "helps with code" gives it nothing to match against. Name the task, the situation and, if you want proactive use, say so.
- Weak: "Reviews code."
- Better: "Reviews recently changed code for bugs, missing tests and unclear naming. Use right after code is written or modified."
Give each agent one job
An agent that reviews, refactors and writes docs will have a fuzzy description and a bloated prompt. Split these into separate agents. Narrow agents are easier to trigger correctly, easier to debug and easier to restrict to only the tools they need.
Structure the prompt
A reliable prompt has four parts:
- Role: one sentence on who the agent is and what it is responsible for.
- Steps: the order of work, such as inspect the diff, check each file, then summarize.
- Output format: exactly what to return, for example a list grouped by severity.
- Limits: what not to do, such as editing files, guessing when information is missing, or going beyond the assigned scope.
Because a subagent starts with its own context, the prompt should contain everything it needs to work without the earlier conversation.
Template to copy
---
name: code-reviewer
description: Reviews recently changed code for bugs, missing tests and unclear naming. Use right after code is written or modified.
---
You are a careful code reviewer.
When invoked:
1. Run git diff to see what changed.
2. Read each changed file in context.
3. Check for bugs, missing tests and unclear naming.
Output: a list grouped as Critical, Warning and Suggestion. Each item gets the file, the line and a one-line fix.
Limits: do not edit files. If something is unclear, say so instead of guessing.Which tools and model should a subagent get?
Give each subagent only the tools its job requires, and pick the cheapest model that can do that job reliably. Tool access limits what can go wrong, and model choice controls cost and speed.
Restrict tools by role
In a subagent's configuration, the tools field lists which tools it may use. If you omit the field, the subagent inherits all the tools available to the main conversation, including file editing and shell commands. That is convenient, but it is broader access than most subagents need.
Least privilege is the safer default. Match the allowlist to the role:
- Code reviewer or auditor: read-only tools such as Read, Grep and Glob, so it can inspect code but not change it.
- Researcher or explorer: read and search tools, plus web access only if the task needs it.
- Implementer or fixer: read, edit and shell tools, because it has to modify files and run tests.
A reviewer that cannot write files cannot quietly "fix" something it was only asked to assess.
Choose a model by difficulty and cost
The model field lets a subagent run on a different model than the main session. Larger models handle ambiguous, multi-step reasoning better but cost more and respond more slowly. Smaller models suit well-defined, high-volume work.
| Task | Reasonable model choice |
|---|---|
| Searching files, summarizing, formatting | Smaller, faster model |
| Routine edits and test runs | Mid-tier model |
| Architecture review, tricky debugging | Most capable model |
Start small, check the output, and move up only when quality falls short. If you leave the model unset, the subagent uses its default, so set it deliberately when cost matters.
Claude Code subagent examples and templates
The four roles below cover most day-to-day needs: reviewer, debugger, test writer and architect. Each is a Markdown file with YAML frontmatter (name, description, tools) followed by a system prompt. Adapt the wording to your stack and conventions.
| Role | Description pattern | Typical tools |
|---|---|---|
| Code reviewer | "Use proactively after code changes to review quality, security and maintainability." | Read, Grep, Glob, Bash (for git diff) |
| Debugger | "Use when encountering errors, failing tests or unexpected behavior." | Read, Edit, Bash, Grep, Glob |
| Test writer | "Use when new code needs unit or integration tests." | Read, Write, Edit, Bash, Grep |
| Architect | "Use for design decisions, refactoring plans and dependency questions." | Read, Grep, Glob |
Why the tools differ
The reviewer and architect are mostly read-only, so leaving out Edit and Write keeps them from changing code unprompted. The debugger needs Bash to reproduce failures and Edit to apply fixes. The test writer needs Write to create new files and Bash to run the suite.
A minimal reviewer template
---
name: code-reviewer
description: Reviews code for quality, security and maintainability. Use proactively after code changes.
tools: Read, Grep, Glob, Bash
---
You are a senior code reviewer. Run git diff, focus on modified files, and report issues grouped by priority: critical, warning, suggestion.Where to find more
Community collections on GitHub are a good source of ready-made files you can copy into .claude/agents/. If you want a curated shortlist, see our comparison of the best Claude Code subagent collections and packs. Whichever you pick, read the prompt and tool list first, since the best claude code subagents are the ones whose permissions match the job.
Subagents vs Skills: which should you build?
Build a subagent when a task needs its own isolated context, tool access or model. Build a skill when you want a reusable set of instructions that Claude loads into the work it is already doing.
The core difference is where the work happens. A subagent runs in a separate context window, does its job, and hands a result back to the main conversation. A skill is a packaged instruction set, typically a folder with a SKILL.md file, that gets pulled into the current session when it is relevant.
When to pick each
| Choose a subagent when... | Choose a skill when... |
|---|---|
| The task produces lots of noisy output (searches, logs, test runs) you don't want in the main context | You want Claude to follow the same procedure or conventions every time |
| You want to restrict tools or use a different model for the job | The guidance is mostly knowledge, templates or steps, not a separate worker |
| The work is self-contained and can return a short summary | The instructions should shape the main conversation directly |
Using them together
The two are not exclusive. A subagent can follow a skill's instructions for a specialized job, and a skill can describe when to hand work to a subagent. For example, a code review subagent can apply a team's review checklist that lives in a skill.
If you go the skill route, you can validate your SKILL.md file before relying on it, to catch formatting problems early.
How to test and improve your subagent
Treat the first draft as a hypothesis: run a real task, see whether Claude hands it off, then tighten the file based on what happens. Most subagent problems come from the description or the prompt, not the idea itself.
Run a real task and check delegation
Pick a task your subagent was built for and phrase it the way you normally would. Watch whether Claude delegates to the subagent or handles the work in the main conversation. You can also name the subagent explicitly to confirm the file loads and behaves as intended.
Tighten the description if it is not triggered
Claude uses the description to decide when to delegate, so vague wording leads to missed handoffs. Fix it by:
- Stating the specific situations that should trigger the subagent
- Naming the kinds of tasks or files it handles
- Adding a phrase such as "use proactively" when you want automatic delegation
Retest after each change so you know which edit helped.
Review the output and trim the prompt
Read what the subagent returns. If it rambles, repeats context, or drifts outside its job, cut instructions that do not change behavior and add a clear output format. Shorter, sharper prompts are easier to maintain and tend to produce more consistent results.
Commit the file for your team
Project-level subagents live in the repository, so commit the file to version control. Teammates then get the same subagent, and changes can be reviewed like any other code. For broader habits around prompting and workflow, see these Claude Code best practices.
Skip the blank file: generate a subagent file
If you would rather not start from an empty file, you can generate one. The Subagent Generator lets you describe a role, pick the tools and model, and download a valid .claude/agents file in seconds.
The result is a starting point, not a finished agent. Read the generated description and prompt, tighten them to your project, and test it the way you would a hand-written file.
What the generator covers:
- Role: the job the subagent is responsible for
- Tools: only the access that role needs
- Model: the model it should run on
- Output: a valid file you drop into .claude/agents
The free tools for people building with Claude Code run in the browser. There is no signup, and nothing leaves your browser, which matters if your role description mentions internal details.
If you would rather not write your own at all, Agentsforce also includes 55 ready-made specialists. That can help when you want working claude code agents quickly and prefer to review an existing file instead of drafting one.
Related articles
Frequently asked questions
Can a Claude Code subagent call another subagent?
Generally no. Subagents are not meant to spawn further subagents, so keep the orchestration in the main conversation and chain them from there. For example, ask a test writer subagent to add tests for a change, then, once it returns, ask a reviewer subagent to check both the code and the new tests.
Where should I save subagent files so my team gets them?
Save them in the project folder .claude/agents and commit that folder to git. Everyone who clones the repository then gets the same subagents. Files in the user-level ~/.claude/agents folder are personal and available across all your projects. If a project file and a user file share a name, the project file takes priority.
Why is Claude not using my subagent automatically?
Claude decides when to delegate mainly from the description field, so a vague description rarely triggers it. Add a clear trigger phrase such as "use proactively after code changes" and state what the agent is for. If you need it right now, invoke it by name in your prompt, for example "use the code-reviewer subagent to check my last commit.".
How many subagents is too many?
Start with 3 to 5 single-purpose agents. When descriptions overlap, Claude has a harder time choosing between them, and delegation becomes unreliable. If you cannot tell two subagents apart by reading their descriptions, merge them or sharpen what each one is responsible for.