Claude Code Subagents: a beginner's guide step by step

What a subagent is, in plain words

Picture Claude Code as the head of a small team. It talks to you and keeps the whole task in mind, while bulky side jobs go to helpers: one rereads twenty files, another checks a text, a third gathers facts from the web. Each works quietly at their own desk and brings back a short note.

Those helpers are Claude Code subagents. People also call them "Claude Code agents" or "custom agents". It's the same thing.

Why bother with this setup when you could do everything in one chat? There are four reasons.

• The main Claude keeps a clear head. Every conversation has a memory limit called the context window. When Claude reads dozens of pages, all of that text piles up in the chat, and by midday it starts to lose track. A subagent reads everything in its own window and sends back only the gist.
• Narrow specialization. A subagent has its own instructions. A post editor checks the same things against the same list every time, and you don't have to explain the job again.
• Restrictions. You can let a subagent only read files. Then it physically can't break anything.
• Saving your usage limit. Simple work can go to the fast, cheap Haiku model, while the heavy thinking stays with Opus.

Some agents are already built in, and Claude calls them on its own. Explore searches files and changes nothing. Plan gathers context when you ask for a plan first. General-purpose handles multi-step tasks that need both finding and changing. A line like Explore(Find every mention of the price) in the window is a subagent at work.

Your own subagents make sense when you keep giving Claude the same assignment with the same explanations. Describe the helper once, and from then on it works to your standard.

What you need and what it costs

Subagents live inside Claude Code. So you need Claude Code itself and a paid plan: the Free plan doesn't include it. You can work in the terminal or in the Code tab of the Claude desktop app, and subagents load in both. If you don't have Claude Code yet, start with the guide on how to use Claude Code. On Windows, use the separate walkthrough for installing Claude Code on Windows.

Prices come from the official page claude.com/pricing. For a detailed breakdown of which plan fits which work, see Claude pricing plans.

One detail few people mention: every subagent spends the same usage limit as your main conversation. Five agents in parallel burn through it five times faster, so on Pro start with one or two on a cheap model.

Sign up at claude.ai with any email, pick a plan, and use the same account to sign in to Claude Code. If your card gets declined, the article on how to pay for Claude walks through the working options.

How to create subagents in Claude Code: your first one in 10 minutes

You don't create files by hand. Describe the subagent to Claude in plain words, and Claude writes the file. Let's build a post editor that checks a text before you publish and changes nothing without you.

Create a post-editor subagent in this project's .claude/agents folder.
Job: check a finished social media post or newsletter before it goes out.
It returns: a list of mistakes (typos, jargon, long sentences, repetition) with a quote and a fix for each, a rating of the first line, and a stronger version of it.
It only reads files and never changes anything. Model: haiku. Keep the answer to 15 lines or fewer.

To make the agent available in all your projects, ask Claude to save it to your personal folder: "save this agent to ~/.claude/agents so it works in every project". The official docs show the difference:

The .claude/agents/ folder inside a project holds agents for that project only. The ~/.claude/agents/ folder in your home directory holds agents for every project on your computer. If two agents share a name, the project one wins.

Older guides show the /agents command with a setup wizard. That wizard only exists up to version 2.1.197. Today /agents just reminds you to ask Claude or edit the agents folder, so chat is now the main way to create agents.

Real test: how the agent edited a post

I created this editor and gave it a deliberately bad post. The post was in Russian. Here's what it said, translated: "Friends, hello everyone! Today I would like to tell you about the fact that the carrying out of sales through a consultation is the most effective means of obtaining clients for specialists in the service sector. Sign up for a consultation."

Two takeaways from this test. First, even a cheap model with good instructions finds things in your text that you've stopped seeing. Second, read the agent's output yourself. A helper tries to be useful and may "improve" your text with invented facts. Add a line to the instructions, "don't add numbers or facts that aren't in the original text", and you'll get fewer surprises.

What's inside a subagent file

A subagent file is a plain text file in Markdown format. At the top, between two lines of three dashes, sit the settings. Below them are the agent's instructions in your own words. You don't have to edit it by hand: tell Claude what to change, and it will fix the file itself. Still, it helps to know what's in there.

Only two fields are required: name and description. Everything else is optional.

About tools. An agent that only checks and advises needs Read, Grep, and Glob: read files, search inside text, find files. An agent that has to create things also needs Write and Edit. An agent that searches the web needs WebSearch and WebFetch. The fewer permissions, the calmer you sleep.

Choosing a model for a subagent

Each agent can run on its own model: the main chat stays on a strong model while routine work goes to a cheaper one.

Claude Code picks the model in this order: the model Claude passes for a specific call, then the model field in the agent file, then the CLAUDE_CODE_SUBAGENT_MODEL setting, and finally your main conversation's model. Set the model in the file and you'll know what you get.

To see which model a running agent actually uses, type /tasks. Claude Code shows the model on each subagent's row.

How to call a subagent and write its description

There are three ways to call a subagent.

• Name it in your message. "Ask post-editor to check this post." Claude almost always hands the task over, but the decision stays with Claude.
• Mention it with @. Type @ and pick the agent from the list, the same way you pick a file. This guarantees the agent runs.
• Say nothing. Claude calls the agent on its own when the task matches its description. For that, the description has to be precise.

The third way is the most convenient, and it depends entirely on the description field. Claude reads the descriptions of all your agents and decides who gets what. A good description answers the question "when should I call this one".

A weak description: "Helps with texts". Almost anything fits it, so Claude will call the agent at random moments or never.

A strong description: "Checks a finished post before publishing. Use when asked to proofread, check, or clean up a post." It has the job and the trigger words that tell Claude it's time.

If you want the agent to kick in on its own for any matching task, add "use proactively" to the description. Anthropic's docs recommend exactly that. Keep descriptions short, too: when the descriptions of all your agents together go over 15,000 tokens, Claude Code shows a warning at startup. Put the details of how the agent should work below, in the instructions. They load only while the agent is running.

Subagents also run in parallel. Ask: "Run three agents at once: one checks the post, one finds every mention of the old price, one researches three competitors." By default they run in the background while you keep talking. Up to 20 can run at once in one session, and each spends your limit separately.

Claude Code subagent examples: 5 agents for people who sell services and courses

Here are five helpers worth building first. You create each one with a single message in chat, as in Section 03.

The competitor scout saves the most context. It opens ten pages, reads through them, and hands you back one tidy table:

Create a competitor-scout subagent in ~/.claude/agents so it works in every project.
Job: from a list of competitor website links, build a table with product, price, main promise, format (course, consultation, coaching program), bonuses, and guarantees.
Tools: WebSearch, WebFetch, Read. It never changes files. Model: sonnet.
If it can't find a price, it writes "not listed" and never guesses.

The landing page reviewer is where Opus is worth the limit. A weak spot in your offer costs more than a few extra requests:

Create a landing-page-reviewer subagent in this project.
Job: read the sales page at the link through the eyes of someone seeing it for the first time, and return:
1) is it clear within 5 seconds what's being sold and to whom;
2) the three main objections the page doesn't answer;
3) where the call to action gets lost;
4) five specific edits with new copy.
Tools: WebFetch, Read. Model: opus. Don't invent testimonials or numbers.

The voice of customer agent works with what you already have. Put your exported reviews, form answers, and client messages into a project folder and say:

Create a voice-of-customer subagent in this project.
Job: read every file in the "Reviews" folder and return 10 client pains in their own words (verbatim quotes), 5 common objections, and 5 ways clients describe their result in their own words.
Tools: Read, Grep, Glob. Model: sonnet. Don't paraphrase anything, quotes only.

Those quotes then go into your posts, landing page, and ads.

Subagents pair well with skills: the skill sets the order of work, the agent takes the bulky part. If you want an agent that runs on a schedule without you, that's the next level. Start with what an AI agent is and then how to build an AI agent without code.

Claude Code subagents vs skills

Both are instruction files in the .claude folder, and both can be created through chat. The difference is where the work happens.

A skill is a written-down procedure that Claude follows right in your main conversation. You see every step and can correct it along the way. A subagent does the job in a separate window and returns only the result. Anthropic's docs say the same: skills for reusable workflows in the main conversation, subagents for isolated work.

The two also combine. A subagent can load your skills at startup through the skills field, so your post editor checks texts against your own style guide. And a skill can run inside a subagent if you add context: fork to it. More on skills in the guide to Claude skills.

When you don't need a subagent

Anthropic's docs say plainly to stay in the main conversation in a few cases.

First, the task needs a lot of back-and-forth. You're writing a post and ask five times for "shorter", "warmer", "add an example". A subagent starts from a blank page each time and doesn't remember what you agreed on a minute ago. Working directly is faster here.

Second, a quick, targeted change. Changing a price in one place is easier yourself than waiting for an agent to gather context.

Third, several stages built on one shared conversation, like a strategy you discussed and now write texts from. An agent would need the whole strategy retold.

Subagents can also call their own subagents, up to three levels deep. You won't need this as a beginner, but the ceiling is high.

If something goes wrong

Cheat sheet

The whole path in one minute. Copy it for yourself.

Cheat sheet: Claude Code subagents
1. You need Claude Code on a paid plan (Pro from $20 a month). Free has no Claude Code.
2. Open your project folder and describe the agent to Claude in plain English.
3. In the description: the job, when to call it, which tools, which model, what not to do.
4. Agent for one project – .claude/agents, for every project – ~/.claude/agents.
5. Claude can't find the agent – restart Claude Code.
6. Call it by name in your message, or with @ to make sure it runs.
7. Checking agents get read-only tools, simple tasks get the haiku model.
8. Read the agent's output yourself: it may add things that weren't there.
9. Lots of back-and-forth and quick edits – stay in the main chat, no agent.
10. Repeatable procedure with you in the loop – a skill. Bulky solo work – a subagent.

Sources

• Claude Code: Create custom subagents (Anthropic docs), checked Nov 12, 2026
• Claude Code: Extend Claude with skills (Anthropic docs), checked Nov 12, 2026
• Claude pricing (official page), checked Nov 12, 2026
• Anthropic: supported countries and regions, checked Nov 12, 2026