How to create a Claude Code subagent

Guide · checked against the docs on Oct 16, 2026

Long Claude Code sessions fill up with search results, test output and file dumps you only needed once. A subagent is a way to send that kind of side job off to a helper, so your main chat stays clean. This guide explains what subagents are, when to use one, and how to make your own. Everything below comes from Anthropic's subagents page in the Claude Code docs, read on October 16, 2026. We haven't tested these steps ourselves.

Not affiliated with or endorsed by Anthropic. Claude Code changes often, so check the docs for your version.

What a subagent is

The docs put it simply: "Subagents are specialized AI assistants that handle specific types of tasks." (checked Oct 2026)

The key idea is a separate workspace. The docs say: "Each subagent runs in its own context window with a custom system prompt, specific tool access, and independent permissions." (checked Oct 2026) The subagent does the messy work and hands back a short answer. In the docs' words, the subagent "does that work in its own context and returns only the summary". (checked Oct 2026)

One thing to know before you start: subagents aren't free extra capacity. The docs say each one "also sends its own requests, which count toward the same usage limits as your main conversation." (checked Oct 2026)

You may already be using one

Claude Code ships with built-in subagents and uses them on its own. One is called Explore, which the docs describe as "A fast, read-only agent optimized for searching and analyzing codebases." (checked Oct 2026) The docs say: "Claude delegates to Explore when it needs to search or understand a codebase without making changes. This keeps exploration results out of your main conversation context." (checked Oct 2026)

You only need a custom subagent when the built-in ones don't fit. The docs' rule of thumb: "Define a custom subagent when you keep spawning the same kind of worker with the same instructions." (checked Oct 2026)

When to use a subagent, and when not to

The docs give two short lists. Use a subagent when (checked Oct 2026):

"The task produces verbose output you don't need in your main context"
"You want to enforce specific tool restrictions or permissions"
"The work is self-contained and can return a summary"

Stay in the main conversation when, among other cases (checked Oct 2026):

"The task needs frequent back-and-forth or iterative refinement"
"You're making a quick, targeted change"

Our advice, not a vendor quote: running tests and reading long logs are good first jobs for a subagent. Fixing a bug together with Claude, step by step, is better kept in the main chat.

If what you really want is a saved prompt you can rerun, the docs point elsewhere: "Consider Skills instead when you want reusable prompts or workflows that run in the main conversation context rather than isolated subagent context." (checked Oct 2026)

Try one without making anything

You don't need a file to try the idea. The docs include this example prompt (checked Oct 2026):

Use a subagent to run the test suite and report only the failing tests with their error messages

Claude runs the tests in a separate context and brings back only the failures. If that feels useful, it's worth making a custom subagent for the jobs you repeat.

Make your own subagent

The docs say: "Subagents are Markdown files with YAML frontmatter. To create one, ask Claude to write it for you, or write the file yourself." (checked Oct 2026)

The easy way: ask Claude

Describe what you want and where to save it. For example:

Create a personal test-runner subagent in ~/.claude/agents/ that runs the
project's tests and reports only the failing tests and their errors.
Make it read-only apart from running the tests.

Then open the file Claude wrote and check it says what you asked for.

The manual way: write the file

Create a Markdown file in an agents folder. Here's our own example, modeled on the docs' code-reviewer example. Save it as ~/.claude/agents/log-reader.md:

---
name: log-reader
description: Reads long log files and reports only errors and warnings. Use when the user shares or mentions a log file.
tools: Read, Grep, Glob
---

You read log files. List each distinct error or warning once,
with the line it first appears on and how often it repeats.
Don't suggest fixes unless asked. Keep the report short.

Three parts matter:

name: the subagent's ID. The docs say "Only name and description are required." (checked Oct 2026)
description: when Claude should use it. The docs say "Claude uses each subagent's description to decide when to delegate tasks. When you create a subagent, write a clear description so Claude knows when to use it." (checked Oct 2026)
The text below the ---: this becomes the subagent's instructions. The docs note that "Subagents receive only this system prompt plus basic environment details like the working directory, not the Claude Code system prompt." (checked Oct 2026) So write everything it needs to know in that text.

Spell field names exactly. The docs warn that "Claude Code ignores a field it doesn't recognize without reporting an error." (checked Oct 2026)

Limit what a subagent can do

The tools line controls which tools the subagent gets. If you leave it out, the docs say it "Inherits every tool available to subagents if omitted." (checked Oct 2026)

Our advice, not a vendor quote: always set tools. A subagent that only reads and reports needs Read, Grep, Glob and nothing more. Only add tools that write or run commands when the job truly needs them. For more on approvals and allow and deny rules, see our permissions guide linked below.

Where to save it

Where the file lives decides who can use it:

~/.claude/agents/ in your home folder: the docs call these "personal subagents available in all your projects". (checked Oct 2026)
.claude/agents/ inside a project: these work in that project only. For project subagents, the docs suggest: "Check them into version control so your team can use and improve them collaboratively." (checked Oct 2026)

If two have the same name, the docs say "When multiple subagents share the same name, Claude Code uses the one from the higher-priority location." (checked Oct 2026) In the docs' priority table, .claude/agents/ (Current project) is priority 3 and ~/.claude/agents/ (All your projects) is priority 4, so the project subagent wins. (checked Oct 2026)

How to use your subagent

Claude can pick it on its own, based on the description. The docs add: "To encourage proactive delegation, include phrases like "use proactively" in your subagent's description field." (checked Oct 2026)

You can also ask for it by name in plain language, for example:

Use the log-reader subagent to check server.log

If you want to be sure it runs, type @ and pick it from the list. The docs say an @-mention "ensures that specific subagent runs rather than leaving the choice to Claude". (checked Oct 2026)

If Claude doesn't seem to know about a new subagent, the docs say: "If Claude can't find the new subagent, restart Claude Code and try again." (checked Oct 2026)

Things to watch

Permission prompts still come to you. For subagents running in the background, the docs say "Claude Code surfaces the prompt in your main session and names the subagent that is asking." (checked Oct 2026) Read which subagent is asking before you approve.
Many subagents add up. The docs warn: "Running many subagents that each return detailed results can consume significant context, and each subagent spends tokens of its own while it runs." (checked Oct 2026)

Our advice, not a vendor quote: start with one or two subagents for jobs you repeat every week. Add more only when you notice a real need.

What the docs don't say

The page we read doesn't say how many custom subagents a beginner should have, or which jobs to start with. Those suggestions are ours. We don't cover plugins, managed settings, agent teams or other advanced options here. See the docs for those.

We haven't tested these steps hands-on. This guide collects what Anthropic's own docs say.

Not affiliated with or endorsed by Anthropic. Claude Code changes often, so check the docs for your version.