You ask Claude Code to fix a bug. To track it down, it opens fifteen files, reads the logs, runs the tests twice. The bug is fixed, but your conversation now holds thousands of lines you will never read again. Claude gets slower, it forgets the instructions you gave it at the start, and you end up restarting everything from scratch.
Subagents exist for exactly this. A subagent is a secondary assistant that Claude Code launches in its own working memory: it does the digging, then hands you back the result and nothing else. Your main conversation stays readable.
Here you'll see what a subagent actually is, how to create one in five minutes with the /agents command, what the four settings in the config file are for, and above all when to delegate (and when it backfires). You don't need to be an experienced developer: if you can open a terminal and launch Claude Code, you're ready.
What Is a Claude Code Subagent, Exactly?
A subagent is a specialized assistant, with its own instructions, its own tools and its own working memory, that Claude Code calls on its behalf to carry out one specific task.
A simple picture: your main agent is a site foreman. It knows the project, it talks with you, it keeps track of the thread. When it needs an electrical diagnosis, it doesn't take the measurements itself — it calls the electrician, who comes back with a three-line conclusion. The foreman never saw the 200 intermediate readings, and that's exactly how it should be.
Technically, three things separate a subagent from a simple instruction typed into the conversation:
- A separate context window. The context window is the amount of text the model keeps in front of it during an exchange, measured in tokens (fragments of words). The subagent has its own, and it's wiped once the mission is over.
- A dedicated system prompt. You write the subagent's role yourself: what it should do, how to go about it, and what form its output should take.
- Restricted tool access. You can decide that a review agent reads files but has no right to modify them. That's a safety mechanism, not a detail.
At the end, the subagent returns a single message to your conversation: its summary. Everything else (the files it read, the commands it ran, the dead ends) disappears with it.
Why a Clean Context Genuinely Improves Your Results
Because answer quality drops long before the technical context limit is ever reached.
A Claude Code session works with a context window of roughly 200,000 tokens, or several hundred pages of text. That sounds enormous, right up until you have it explore a real project: a few dozen files read and you've already burned half of it.
Two concrete effects, which you may have already experienced without putting a name to them:
- Dilution. The more text piles up, the less weight your original instructions carry against the noise. Claude starts ignoring a rule you had laid out perfectly clearly at the beginning.
- Compaction. When the window saturates, Claude Code automatically summarizes the conversation so it can keep going. The summary keeps the essentials, but not your details — and it's often a detail that mattered.
Type /context in Claude Code to see live what's filling your window. If you're new to the tool, the 20 Claude Code commands worth knowing will save you time before you tackle what follows.
Delegating an exploration to a subagent turns 40,000 tokens of reading into a 400-token conclusion inside your conversation. The math does itself.
Create Your First Subagent in Five Minutes
The /agents command does all the work: you type it in Claude Code, you pick «Create New Agent», and the interface generates the config file for you.
If Claude Code isn't installed on your machine yet, start with the Claude Code tutorial for beginners, then come back here.
The walkthrough, step by step:
- Launch Claude Code in your project folder.
- Type /agents and hit Enter.
- Choose Create New Agent.
- Choose the scope: Project (the subagent is saved in the project's .claude/agents/ folder and travels with the project, including for your teammates) or Personal (it's saved in ~/.claude/agents/ and follows you across all your projects).
- Describe in one sentence what the agent should do. Claude drafts a first version of the instructions, which you read over and correct.
- Check off the tools it's allowed to use.
- Save.
That's it. The file it creates is a plain Markdown file: a config header framed by two lines of three dashes, then your free-form instructions underneath. You can open it in any editor and edit it by hand, which is often faster than going back through the interface. If two agents share a name, the project version wins over the personal one.
The Four Header Settings
| Setting | What it's for | Required |
|---|---|---|
| name | The subagent's identifier, lowercase with hyphens (for example: security-reviewer) | Yes |
| description | A plain-language sentence saying what the agent does and when to call it | Yes |
| tools | The list of allowed tools, comma-separated. Leave the field empty and the subagent inherits every available tool | No |
| model | The model to use (a fast model like Haiku for simple triage, a more powerful one like Opus for hard reasoning) | No |
The description field deserves your full attention: it's the only thing the main agent reads to decide whether to delegate or not. A vague description («help with code») will never trigger anything. A precise one («Analyzes test failures and identifies the root cause. Use as soon as a test command returns an error.») triggers delegation automatically, without you having to think about it.
It's the same reflex as with the global instructions file: writing a good CLAUDE.md and writing good subagent descriptions rest on the same principle — be explicit rather than polite. For the full syntax and the tool list, the official Claude Code subagents documentation is the reference.
You can also force the issue at any time, simply by writing: «use the reviewer subagent to check my changes».
When to Delegate, When to Keep Control
Delegate any task that produces a lot of intermediate text for a short conclusion, and keep in the main conversation anything that depends on your history.
Good candidates for delegation:
- Code exploration. «Find where billing is handled in this project and walk me through the flow.» The agent reads thirty files, you get a paragraph.
- Code review. A read-only agent that goes over your changes before you commit them.
- Log analysis. Thousands of lines in, five lines of explanation out.
- Independent verification. A second agent that checks the first one's work without having been influenced by the conversation, which avoids the «yep, all good» effect.
- Documentation research. Reading docs online and bringing back only the part that concerns you.
What's better kept in the main conversation:
- Tasks that take a few seconds (renaming a variable, fixing a typo): delegation costs more than it returns.
- Chained edits where each step depends on the result of the previous one.
- Anything that builds on what the two of you have already discussed: the subagent starts from zero and only has access to the instruction you give it.
And the limits, stated honestly:
- It restarts from scratch on every call. Everything it needs has to fit in its opening instruction.
- It consumes tokens. Each subagent loads its own context. In total, you often consume more: what you gain is quality and clarity, not savings.
- It adds latency. Expect a few dozen extra seconds compared to a direct answer.
- There's no back-and-forth. You can't correct it mid-flight; you relaunch it with a better instruction.
Three Useful Subagents to Create Today
An exploration agent, a review agent and a test agent cover, on their own, most of the situations where your context fills up for nothing.
- explorer. Tools: read and search only, no writing. Sample instruction: «You map existing code. You answer in three parts: the files involved, the data flow, the points to watch. 300 words maximum, no modification suggestions.»
- reviewer. Tools: read, search, and the command that shows pending changes. Sample instruction: «You review uncommitted changes. You flag only real problems, sorted by severity, with the file and the line. If everything is fine, say so in one sentence.»
- tester. Tools: read, search, command execution. Sample instruction: «You run the test suite, analyze the failures and identify the root cause. You fix nothing yourself; you deliver a diagnosis.»
Those three files take fifteen minutes to create. The real learning comes afterwards, when you refine the instructions over the following weeks and see which ones produce answers you can actually use.
If you'd rather have a guided path than trial and error, the Skilzy program on coding with Claude Code in the terminal covers the whole chain in order: installation, basic commands, the CLAUDE.md file, subagents, automations — all on real projects. Skilzy is a French AI learning platform covering more than fifteen programs (images, video, music, automation with n8n, prompt writing, code), with a built-in AI Lab that gives you access to the tools and their credits without stacking up subscriptions, starting at €29.90 per month with no commitment. The discovery demo lets you try it for 7 days with no credit card, including 1 image, 1 video, 1 music track and 10 messages.
Key Takeaways
A subagent doesn't make Claude Code smarter, it makes it more focused. You isolate the noisy work in a disposable memory, you get back a summary, and your main conversation keeps its instructions intact from start to finish. Create your first exploration agent today, use it for a week, then add a second one only when you spot a repetitive task that consistently clogs your context. That's the order in which the habit sticks.
