A Claude Code subagent is a second Claude that your main session hands one job to. It works in its own window, uses only the tools you give it, and sends back a short result. By the end of this guide you'll have a read-only helper set up and know the one line that keeps it safe.
Here's the plain version. Your main Claude session is the manager. A subagent is a temp worker with a job description and a key ring. Almost every risk comes down to how many keys you put on that ring.
If Claude Code isn't installed yet, start with the safe setup for non-developers, then come back.
You already use subagents, even if you never made one
Claude Code ships with built-in subagents and picks them on its own, with no setup. Anthropic's docs list three:
- Explore searches through your project.
- Plan does research while Claude is in plan mode.
- General-purpose handles bigger multi-step jobs.
You can also call one by name. Try this in any project today:
Use the Explore subagent to find where the signup form is and tell me in three lines.
That's a subagent doing real work before you've written a single file.
A subagent works alone and only reports back
Each subagent gets its own instructions, its own context window, its own tool list and its own permission mode. It does the job and returns only the final result to your main session (Claude Code docs).
Two things follow from that:
- Your main chat stays short. If a job means reading 40 files, the subagent reads them and you get the summary. The 40 files never fill up your main window.
- It doesn't know what you said earlier. The subagent starts fresh. Anything it needs, like the file name, the goal or the rule it must follow, has to be in the task you hand it or in its instructions.
The second point trips people up more than anything else. If you spent ten minutes explaining your pricing page to Claude, the subagent heard none of it.
Skills shape your chat, subagents do separate jobs
People mix these two up constantly. A skill is a set of instructions Claude reads inside your own chat. A subagent is a second Claude with its own window that goes off, does the job and comes back with a note (crystl.dev). A skill is a recipe card the manager reads. A subagent is a temp worker.
Use this table to pick:
| Your job looks like this | Use | Why |
|---|---|---|
| Short, needs what you already said, should change how Claude answers | A skill | It runs inside your chat, so it sees the conversation |
| Lots of reading, a search or a review, and you only need the answer | A subagent | The reading stays out of your main window |
| A one-off question | Just ask the main session | Setting anything up costs more than it saves |
| The same check you run after every change | A saved subagent | You write the instructions once and reuse them |
The split between the first two rows comes from Zencoder's comparison. My rule on top: don't save a subagent until you've done the same job by hand at least three times. Before that, you don't know what its instructions should say.
Leave out the tools line and your helper gets every key
This is the one risk worth memorizing. If a subagent file has no tools line, the subagent inherits every tool your main session has, MCP servers included (schoettler.io).
So a helper you named "reviewer" can also edit files. If you've connected outside services through MCP, it can reach those too. A name and a description don't limit anything. Only the tool list does. If MCP is new to you, MCP servers explained covers what those connections can do.
You have two ways to shorten the key ring:
toolsis an allowlist. Only what you list is allowed. Use it for helpers that should just look.disallowedToolsis a denylist. Everything is allowed except what you list. Use it when you want to remove one or two risky tools and keep the rest.
For non-developers, start with the allowlist every time. It fails safe: if you forget a tool, the helper can't do something, and it tells you.
Set up a read-only reviewer in five steps
This is the copy-and-use part. The file below is an example you can paste as is.
- Open Claude Code in your project folder and type
/agents. That command lists your agents and lets you create or edit them (Medium guide). - Choose to create a new agent for this project. Claude Code saves it as a Markdown file in the project's
.claude/agents/folder (Claude Code docs). - Make the file say this:
---
name: reviewer
description: Reads changed files and reports problems. Use after any edit, before saying the work is done.
tools: Read, Grep, Glob
permissionMode: plan
---
You review files. You never edit anything.
List each problem with the file name and a one-line fix.
If you find nothing, say "No problems found" and list the files you checked.
- Read the
descriptionline once more. It's what tells the main session when to use this helper, so a vague one means it gets picked at the wrong time or never (computingforgeeks). "Helps with code" is vague. "Use after any edit, before saying the work is done" is a trigger. - Test it. Ask your main session: "Use the reviewer subagent to check what you just changed." You should get a list of problems or "No problems found", and no file should change. If anything changed, your
toolsline is wrong.
Here's what each line does:
| Line | What it does | What to put |
|---|---|---|
name |
What you call it | One short lowercase word |
description |
When the main session should use it | A trigger: "Use after X" or "Use when Y" |
tools |
The key ring | Read, Grep, Glob for look-only helpers |
permissionMode |
How it handles permission requests | plan or default while you're learning |
| The text below the dashes | Its job description | What to do, what never to do, what the report looks like |
The last line in the instructions matters more than it looks. "List the files you checked" lets you see whether it actually looked. How to tell if an AI agent actually finished the task goes deeper on that.
Match the key ring to the job
permissionMode accepts default, acceptEdits, dontAsk, bypassPermissions or plan, and model accepts haiku, sonnet, opus or inherit (Claude Code docs). You don't need most of them. Use this:
| Helper's job | tools | model | permissionMode |
|---|---|---|---|
| Find where something is | Read, Grep, Glob | haiku | plan |
| Review what changed | Read, Grep, Glob | leave it out | plan |
| Fix typos you'll check after | Read, Edit | leave it out | default |
| Anything that sends, posts or spends | Don't build it yet |
Leaving model out means inherit: the helper runs on the same model as your main session (Claude Code docs). Put haiku on simple finding jobs, where a smaller model is enough. Keep judgment jobs like reviews on the main model.
acceptEdits stops the helper from asking before it edits, which suits automated helpers (Steve Kinney). Only use it on a helper you already trust. Skip dontAsk and bypassPermissions while you're learning. On a file with no tools line, they hand over every key and remove the check.
Whether haiku saves you money on your own jobs is something to test, not assume. Run the same task with and without it and count the results you'd actually keep. Judge cost per kept result, not cost per run (Claude Code best practices). A cheap run you have to redo isn't cheap.
Save project helpers in the project, general ones in your user folder
A subagent can live in one project or follow you everywhere (Claude Code docs):
.claude/agents/inside a project: only that project sees it.~/.claude/agents/in your user folder: every project you open sees it.
The rule: if the instructions mention one app's folders, pages or rules, keep the helper in that project. If it would work the same anywhere, like the reviewer above, move it to your user folder. A project helper saved at user level shows up in every project, where its folder names and rules don't apply.
Four mistakes and what each one costs
- No
toolsline. Cost: a "read-only" helper that can edit files and use every connected service. - A vague
description. Cost: the main session calls it at the wrong time, or never, and you think subagents don't work. - Assuming it heard the chat. Cost: it works from half the picture and reports confidently on the wrong thing. Put the goal and file names in the task.
- Heavy reading in a skill instead of a subagent. Cost: everything the skill pulls in lands in your main window and crowds it (chudi.dev).
Tick each one off against any helper you already have.
Do this in the next ten minutes
Open a project, type /agents and look at what's already there. Create the reviewer above, paste the file, and ask it to check one file you changed this week. If it returns a list and touches nothing, you have a working helper with a short key ring.
Turn the check you keep doing by hand into a helper
Most people find their first good subagent by noticing the check they keep doing by hand. If there's a manual task you'd like turned into a working helper, Email Me with the task in one sentence.
