"Claude Code agents" usually means subagents: specialised helpers that Claude Code hands a side-job to, each working in its own separate context and reporting back with a summary. You are already using some of them without knowing. This guide explains what they are, when a custom one is worth making, and how to write one.
If Claude Code itself is still new, read the Claude Code beginner's guide first — subagents make sense once the basic session feels familiar.
First, a word about "agent"
Claude Code is itself an agent: rather than answering once, it works in a loop — read, plan, act, check — until a job is done, using tools such as reading files, editing them and running commands. That is what separates it from a chat window.
A subagent is an agent that Claude Code starts to handle one part of a job. The documentation describes them as "specialized AI assistants that handle specific types of tasks", each running "in its own context window with a custom system prompt, specific tool access, and independent permissions".
Why subagents exist: the context window
Everything in a conversation — your requests, Claude's replies, every file it has read — sits in the context window, the model's working memory. It is large but not unlimited, and the fuller it gets, the slower and more expensive each step becomes.
Some tasks flood it with material you will never look at again: searching two hundred files for one pattern, reading long logs, researching a question across many documents. A subagent does that work in its own context and hands back only the conclusion. Your main conversation stays short and focused.
The documentation lists the benefits as preserving context, enforcing constraints by limiting tools, reusing configurations across projects, specialising behaviour, and controlling costs by sending simple tasks to cheaper, faster models.
The built-in subagents
Claude Code uses some subagents automatically:
- Explore — a fast, read-only agent for searching and understanding a codebase or folder. Claude sends it off when it needs to look around without changing anything.
- Plan — a read-only research agent used in plan mode to gather information before presenting a plan.
Both are denied the tools that write and edit files. You will see them in the transcript as a line with the agent's name and a short task description.
Source: Claude Code documentation — Create custom subagents.
When a custom subagent is worth making
The documentation's own test is a good one: define a custom subagent "when you keep spawning the same kind of worker with the same instructions". Some examples for non-programmers:
- A proofreader that checks documents against your style rules and reports problems, but cannot edit anything.
- A fact-checker that reads a draft and lists every claim needing a source.
- A data checker that inspects a spreadsheet for duplicates, gaps and odd values before you use it.
- A researcher that reads a folder of reports and returns a one-page summary.
Notice the pattern: each has a narrow job, and most should be read-only. Restricting a subagent's tools is one of the main reasons to create one.
Subagents vs Skills
| Skill | Subagent | |
|---|---|---|
| What it is | Instructions for a task | A separate helper with its own instructions |
| Where it runs | In your current conversation | In its own context window |
| Tools | The session's tools | Can be limited to a specific set |
| Returns | Its work, inline | A summary to the main conversation |
| Use for | Repeatable procedures | Side-jobs that would clutter the conversation, or need restricted tools |
Our Claude Code Skills guide covers the other half. The two work together: a Skill can even be set to run inside a subagent.
How to create a custom subagent
A subagent is a Markdown file with a few lines of settings at the top. The easiest way to make one is to ask Claude Code to write it:
Create a personal subagent in ~/.claude/agents/ called proofreader. It should read documents and report spelling, grammar and consistency problems with the line and a suggested fix. Make it read-only and have it use Sonnet.
Claude writes a file like this:
---
name: proofreader
description: Checks documents for spelling, grammar and consistency problems. Use after drafting or editing any document.
tools: Read, Grep, Glob
model: sonnet
---
You are a careful proofreader. For each problem, give the file,
the line, what is wrong, and a suggested correction. Do not
rewrite whole paragraphs. Finish with a count of issues found.The fields do what they say: name, a description that tells Claude when to use it, a tools list (here, read-only tools), and a model. Everything below the settings is the subagent's own instructions.
Where the file goes
~/.claude/agents/— available in every project on your computer..claude/agents/inside a project — available in that project, and shareable with anyone who works on it.
Note that in current versions the /agents command no longer opens a creation wizard; it reminds you to ask Claude or edit the folder directly.
Using it
Claude may delegate to it automatically when a task matches the description. To be sure, ask explicitly:
Use the proofreader agent to check every document in the Drafts folder.
Good habits with subagents
- Keep descriptions short and specific. They are how Claude chooses, and they take up space in every session.
- Grant the fewest tools that work. A reviewer does not need to edit.
- Use a cheaper model for simple jobs. Searching and summarising rarely need the most capable model.
- Remember they cost usage too. A subagent reading a hundred files still reads a hundred files; it just keeps them out of your main conversation.
/usageshows what subagents consumed.
Beyond subagents
The documentation also describes larger arrangements — background agents running whole sessions in parallel, and agent teams that Claude coordinates. They are powerful, and they are not where a beginner should start. A single well-described subagent teaches you everything the bigger setups build on.
Custom agents are the final feature chapter of Claude Code for Beginners, after Skills and MCP, because they combine both: an agent can use MCP tools and follow Skills. The book then applies all three in worked projects — writing, research, a website, data and automation. The free Prompt Toolkit is on the book's page; for automation ideas to hand to an agent, see 10 things you can automate with Claude Code.
Frequently asked questions
Do I need subagents to use Claude Code?
No. Claude Code uses its built-in ones for you. Custom subagents are an optimisation for jobs you repeat.
Can a subagent change my files?
Only if its tool list includes editing tools and the permission settings allow the change. You control both, and a read-only tool list is the simplest guarantee.
Are Claude Code agents the same as AI agents in general?
The idea is the same — an AI working in a loop with tools. Claude Code's subagents are a specific, configurable version of it inside a Claude Code session.