Guide

Claude Code Subagents Explained for Non-Developers

By Scott Wilder · November 16, 2026 · 7 min read · All writing

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:

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:

  1. 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.
  2. 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:

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.

  1. Open Claude Code in your project folder and type /agents. That command lists your agents and lets you create or edit them (Medium guide).
  2. 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).
  3. 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.
  1. Read the description line 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.
  2. 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 tools line 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):

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

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.

Questions

Do I need to code to make a Claude Code subagent?

No. Type /agents in Claude Code, create a new agent and paste a short text file with a name, a description, a tools line and plain-English instructions.

What is the difference between a subagent and a skill?

A skill is instructions Claude reads inside your own chat. A subagent is a second Claude with its own window that does a separate job and sends back only the result.

Can a subagent change my files or use my connected tools?

Yes, if its file has no tools line. It then inherits every tool your main session has, MCP servers included. List only Read, Grep and Glob for a helper that should just look.

Does Claude Code use subagents without any setup?

Yes. It ships with built-in ones, Explore, Plan and a general-purpose agent, and picks them on its own. You can also ask for one by name, like the Explore subagent.

Can a subagent use a cheaper model than my main session?

Yes. Add model: haiku to its file for simple finding jobs. Leave the line out and it runs on the same model as your main session.

Where do subagent files live?

In the project's .claude/agents/ folder for helpers tied to one project, or in ~/.claude/agents/ in your user folder for helpers you want in every project.