Home › Rules › Claude Code subagents examples

Claude Code subagents examples: 7 beginner-safe subagents to copy (and how they work)

Built from Anthropic's, Cursor's and OpenAI's own docs, checked Oct 26, 2026. Sources below.

• Guide
• Subagents
• Claude Code
• Cursor
• Codex
• .claude/agents

Short answer: a subagent is a helper Claude hands a side job to, like reviewing your changes or running the tests. It works in its own context window, with its own instructions and its own list of allowed tools, and sends back only a summary, so your main chat doesn't fill up with logs and search results. Each one is a Markdown file with a short YAML header, saved in .claude/agents/ (one project) or ~/.claude/agents/ (all your projects). Claude reads each subagent's description to decide when to use it.

Subagents vs skills vs hooks vs CLAUDE.md vs agent teams

Anthropic's docs draw the lines this way. Stay in the main conversation for back-and-forth work, quick targeted changes, or when several steps share a lot of context. A subagent starts fresh and may need time to gather context. Use a subagent when the job makes verbose output you don't need to see, when you want to limit which tools it can use, or when the work can come back as a summary. Use a skill instead when you want a reusable prompt that runs in your main conversation. A skill can also run inside a subagent if you add context: fork to its frontmatter.

Agent teams are a different feature. They're experimental and turned off until you set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1. Subagents report back to the main chat. Teammates share a task list and message each other directly. Anthropic's comparison lists the token cost of subagents as lower and teams as higher, because each teammate is a separate Claude instance. For most beginners, subagents are the place to start.

Where subagent files go

Subagents can also come from managed settings (your organization), the --agents flag (one session only), and plugins. Claude Code scans both folders including subfolders, so agents/review/ is fine; only the name field identifies a subagent.

The easiest start is to ask Claude to write one: "Create a code-reviewer subagent in .claude/agents/ that reviews my changes. Make it read-only." Then open the file and check it. Or paste one of the files below. Claude Code picks up new and edited files within a few seconds. The one exception: if the agents folder didn't exist when the session started, restart Claude Code.

In current Claude Code versions, /agents just reminds you to ask Claude or edit those folders directly. On v2.1.197 and earlier it opened a menu for creating and editing subagents.

The file format

---
name: my-helper
description: When Claude should hand work to this subagent
tools: Read, Grep, Glob
model: inherit
---

The instructions for the subagent go here, in plain Markdown.
This part becomes its system prompt.

The part between the --- lines is the frontmatter (settings). Everything below it is the subagent's system prompt. A subagent gets only that prompt plus basic details like the working directory, not Claude Code's full system prompt. Only name and description are required. These are the fields beginners are most likely to use:

The docs list a few more (mcpServers, hooks, background, omitClaudeMd, autoCompactWindow, initialPrompt, experimental). Field names are camelCase and must match exactly: Claude Code ignores a field it doesn't recognize without any error, so disallowed-tools silently does nothing.

Read-only subagents: give them tools: Read, Grep, Glob. Without Edit and Write they can't change files. If you add Bash (for example so a reviewer can run git diff), keep in mind Bash can run any command. To block a specific command but keep Bash, add a deny rule like Bash(git push *) to permissions.deny in your settings. Putting Bash(git push *) in disallowedTools removes Bash entirely.

What a subagent can and can't see

• It doesn't see your chat. It starts with a fresh context: no conversation history, no files Claude already read. Claude writes it a task message, and it works from that.
• It does get your CLAUDE.md files and a git status snapshot (the built-in Explore and Plan subagents skip both). If one rule really matters for the job, say it again in your request.
• Only its summary comes back. The logs, test output and search results stay in the subagent's context.
• It uses your plan's usage. A subagent's requests count toward the same usage limits as your main chat. Running many at once also brings many summaries back into your chat.

How subagents get used

• Automatically. Claude delegates when a task matches a subagent's description. To make that more likely, Anthropic suggests phrases like "use proactively" in the description.
• By name. Just ask: Use the test-runner subagent to fix failing tests. Claude usually delegates, but it decides.
• @-mention. Type @ and pick it from the list, or type @agent-code-reviewer. This makes sure that subagent runs.
• The whole session. claude --agent code-reviewer runs the main chat itself as that subagent, with its tools, model and prompt (its prompt replaces the default Claude Code system prompt). To make that the default in a project, set "agent": "code-reviewer" in .claude/settings.json.

When it works, you'll see a row like code-reviewer(Review recent changes) in the transcript. Subagents Claude starts from your main chat run in the background by default, so you can keep working. If one needs a permission, the prompt shows up in your main session with the subagent's name. Run /tasks to see running subagents and the model each one is using.

Picking a model

Set model in the frontmatter. The aliases, as Anthropic's model docs describe them:

• haiku: fast and efficient, for simple tasks
• sonnet: daily coding tasks
• opus: complex reasoning
• fable: the hardest and longest-running tasks, where available
• inherit: the same model as your main chat

If you leave model out, Claude Code picks the model in this order: a model Claude passes when it starts the subagent, then the subagent's model field, then the CLAUDE_CODE_SUBAGENT_MODEL environment variable, then your main chat's model. Anthropic lists "control costs by routing tasks to faster, lower-cost models like Haiku" as one reason to use subagents. A simple way to apply that: put read-only search and summary jobs on haiku, and keep review and debugging on inherit.

• Same family as your main chat? If your main chat is on an Opus model and the subagent says opus, the subagent runs on your main chat's exact model.
• Smaller model, smaller window. A subagent's context window is sized by its own model, not your main chat's.
• One model for every subagent. CLAUDE_CODE_SUBAGENT_MODEL on its own is only a default. To force it, also set CLAUDE_CODE_SUBAGENT_MODEL_FORCE to 1:

{
  "env": {
    "CLAUDE_CODE_SUBAGENT_MODEL": "haiku",
    "CLAUDE_CODE_SUBAGENT_MODEL_FORCE": "1"
  }
}

While the force setting is on, the model field in your subagent files is ignored. Your organization's model allowlist can also swap a blocked model for another one; Claude Code shows a warning when it does.

7 subagents to copy

Examples 2 and 5 are taken from Anthropic's and Cursor's docs. The others follow the patterns in those docs, adjusted for beginners. Save each file under the path shown, then ask Claude to use it by name once to check it works. Each one has a single job, and the read-only ones have no Edit or Write tool.

1. Code reviewer (read-only)

---
name: code-reviewer
description: Reviews recent code changes for bugs, security problems and readability. Use proactively after writing or changing code.
tools: Read, Grep, Glob, Bash
model: inherit
---

You are a careful code reviewer. You never edit files.

When invoked:
1. Run git diff to see what changed
2. Read the changed files
3. Start the review right away

Check for:
- Code that is hard to read or badly named
- Missing error handling
- Secrets or API keys in the code
- User input that isn't validated
- Changes with no tests

Report by priority:
- Must fix
- Should fix
- Nice to have

For each item, name the file and line and show how to fix it.
Explain everything in plain English.

Reviews what changed and reports by priority. It can't edit files. It has Bash so it can run git diff, the same as the reviewer in Anthropic's docs. For a strictly read-only version, delete Bash from the tools line and it will read the files instead. Try it: Have the code-reviewer subagent look at my recent changes.

2. Debugger

---
name: debugger
description: Debugging specialist for errors, test failures, and unexpected behavior. Use proactively when encountering any issues.
tools: Read, Edit, Bash, Grep, Glob
---

You are an expert debugger specializing in root cause analysis.

When invoked:
1. Capture error message and stack trace
2. Identify reproduction steps
3. Isolate the failure location
4. Implement minimal fix
5. Verify solution works

For each issue, provide:
- Root cause explanation
- Evidence supporting the diagnosis
- Specific code fix
- Testing approach

Focus on fixing the underlying issue, not the symptoms.

This is Anthropic's example, slightly trimmed. Unlike the reviewer, it has Edit, because fixing a bug means changing code. You still get the normal permission prompts unless your main chat is in a mode that skips them.

3. Test runner

---
name: test-runner
description: Runs the test suite and fixes failing tests. Use proactively after code changes or when tests fail.
tools: Read, Edit, Bash, Grep, Glob
---

You run tests and report back briefly.

When invoked:
1. Find how this project runs its tests (package.json scripts, Makefile or README)
2. Run the tests
3. If any fail: read the failure, find the cause, and fix the code
   while keeping what the test checks
4. Run the tests again

Never delete a test or weaken it just to make it pass.

Report:
- How many tests passed and failed
- Only the failing tests, with their error messages (not the full log)
- What you changed to fix them

Running tests is the kind of job Anthropic's docs suggest for a subagent: lots of output, and you only need the failures. The "never delete a test" line is there because a quick way to make a failing test pass is to remove it.

4. Security checker (read-only)

---
name: security-checker
description: Security checker for auth, payments, user data and API keys. Use when that kind of code is added or changed.
tools: Read, Grep, Glob
model: inherit
---

You check code for security problems. You never edit files.

When invoked:
1. Find the security-sensitive code: login, payments, user data, API routes
2. Look for hardcoded secrets, API keys and passwords
3. Look for common holes: injection, XSS, missing auth checks
4. Check that user input is validated and cleaned

Report findings by severity:
- Critical (fix before you deploy)
- High (fix soon)
- Medium (fix when you can)

For each one, name the file, explain the risk in plain English,
and say what to change.

Based on the security auditor in Cursor's docs, with Claude Code tool limits added. Read, Grep and Glob only, so it reports and you decide. Pairs with our vibe coding security checklist. It's a second pair of eyes, not a security audit.

5. Verifier: "is it really done?"

---
name: verifier
description: Validates completed work. Use after tasks are marked done to confirm implementations are functional.
tools: Read, Grep, Glob, Bash
---

You are a skeptical validator. Your job is to verify that work
claimed as complete actually works. You never edit files.

When invoked:
1. Identify what was claimed to be completed
2. Check that the implementation exists and is functional
3. Run relevant tests or verification steps
4. Look for edge cases that may have been missed

Report:
- What was verified and passed
- What was claimed but incomplete or broken
- Specific issues that need to be addressed

Do not accept claims at face value. Test everything.

This is Cursor's verification agent. Cursor's docs describe the problem it solves: the AI marks a task done when the work is incomplete or broken. We added the tools line and "never edit files" so it checks and reports instead of patching things.

6. Docs writer

---
name: docs-writer
description: Writes and updates README and docs files after features change. Use when asked to document something.
tools: Read, Grep, Glob, Edit, Write
model: sonnet
---

You write documentation for beginners.

When invoked:
1. Read the code that changed and the existing README and docs
2. Update only Markdown files (.md). Don't change code.
3. Write short sentences. Show the exact commands to run.
4. Keep the existing structure; add a section rather than rewriting everything

When done, list the files you changed and one line about each.

This one has Edit and Write so it can update the README. "Only Markdown files" is an instruction, not a hard limit. Check its list of changed files when it's done. It's set to sonnet, which Anthropic's model docs describe as the everyday coding model.

7. A cheaper Explore (on Haiku)

---
name: Explore
description: Fast, read-only search of the codebase. Use to find files, code or how something works without changing anything.
tools: Read, Grep, Glob
model: haiku
---

Search the codebase and return the relevant file paths and short code snippets.
Don't suggest edits. Keep the answer short.

Claude Code has a built-in read-only Explore subagent it uses for searching your code. By default it runs on your main chat's model (in some setups, on Opus). Anthropic's docs say a user or project subagent named Explore replaces the built-in one and keeps its own model field, so this file moves code searches to Haiku. Keep the name exactly Explore. If the results get worse, delete the file to go back to the built-in one.

Tell Claude about them

Subagents get picked by their description, but you can also say how you want them used in CLAUDE.md:

## Subagents
- This project has subagents in .claude/agents/: code-reviewer, test-runner, security-checker.
- After you change code, use the code-reviewer subagent before you tell me you're done.
- When tests fail, hand them to the test-runner subagent and show me only its summary.

Subagents in Cursor

Cursor has subagents too, in the editor, the CLI and Cloud Agents. Cursor also reads .claude/agents/ and ~/.claude/agents/ (its docs call this Claude compatibility), next to its own .cursor/agents/ and ~/.cursor/agents/. If two have the same name, the .cursor/ one wins, and project subagents win over user ones.

• Cursor's documented fields are name, description, model, readonly and is_background. Its list doesn't include tools. To make a subagent read-only in Cursor, use readonly: true, which blocks file edits and shell commands that change things.
• For model, Cursor documents inherit (the default) or one of its own model IDs. Use model: inherit in files you share between both tools.
• You can call a subagent with /name, like /verifier confirm the auth flow is complete, or by asking for it by name.
• Cursor's built-in subagents are Explore (code search, on a faster model) and Browser (browser control through MCP).

---
name: security-checker
description: Security checker for auth, payments, user data and API keys. Use when that kind of code is added or changed.
model: inherit
readonly: true
---

You check code for security problems. Report findings by severity
(critical, high, medium) with the file and a plain-English fix.

Claude Code ignores frontmatter fields it doesn't know, so a readonly: true line won't break a file Claude Code also reads. It won't make the file read-only in Claude Code either; that still takes the tools line.

Subagents in OpenAI Codex

Codex runs subagents in the ChatGPT desktop app, the Codex CLI and the IDE extension. It delegates when you ask directly ("spawn two agents", "use one agent per point") or when your AGENTS.md or a skill tells it to. In the CLI, /subagents lets you look at and switch between agent threads. Built-in agents are default, worker and explorer.

Custom agents are TOML files, not Markdown: ~/.codex/agents/ for personal ones, .codex/agents/ for a project. Each needs name, description and developer_instructions. Here's the reviewer from OpenAI's docs, lightly trimmed and without the model lines, so it uses the parent session's model:

name = "reviewer"
description = "PR reviewer focused on correctness, security, and missing tests."
developer_instructions = """
Review code like an owner.
Do not edit files.
Prioritize correctness, security, behavior regressions, and missing test coverage.
Lead with concrete findings and avoid style-only comments unless they hide a real bug.
"""

One difference matters. Codex custom agents inherit the parent session's permissions and sandbox, and a custom agent file can't override them. OpenAI's docs say "do not edit files" in the instructions doesn't create a separate read-only sandbox. OpenAI also notes that subagent runs use more tokens than one agent doing the same work.

Best practices from the docs

• One job each. Both Anthropic and Cursor say to keep each subagent focused. Cursor suggests starting with 2 or 3 and warns against vague "helps with coding" agents.
• Specific descriptions. The description decides when it gets used. "Use when implementing authentication flows" beats "use for general tasks".
• Keep descriptions short. All descriptions are loaded into context. Over 15,000 tokens combined, Claude Code warns you at startup. Put the detail in the prompt body, which only loads when the subagent runs.
• Only the tools it needs. Reviewers and checkers don't need Edit or Write.
• Commit project subagents in .claude/agents/ so everyone on the project gets them.
• Don't use a subagent for a quick task. Cursor's docs point out a subagent can be slower than the main agent on simple tasks, because it starts fresh.

Subagent not showing up or not being used? Check these

• New folder? If .claude/agents/ or ~/.claude/agents/ didn't exist when you started the session, restart Claude Code. After that, edits load on their own.
• Header problems make Claude Code skip the file without telling you: no name, no description, the opening --- not on the very first line, or YAML that doesn't parse (a stray colon in an unquoted description can do it). Run claude plugin validate .claude/agents to check for YAML errors (v2.1.233 or later), or start with claude --debug and read the debug log.
• Bad name. Names can't contain :, start with -, or be longer than 256 characters.
• Two with the same name. A project subagent beats a user one, and inside one folder only one of the duplicates loads. /doctor reports duplicate names in the same folder.
• A setting does nothing. Check the spelling and camelCase (disallowedTools, maxTurns). Unknown fields are ignored without an error.
• "Spawned with zero tools" error. Every name in your tools line is misspelled or not available. Tool names are like Read, Grep, Glob, Bash, Edit, Write.
• Claude never uses it on its own. Make the description more specific and add "use proactively", or call it by name or with an @-mention.
• Blocked on purpose. Check permissions.deny in your settings for Agent(its-name), or Agent on its own, which blocks all subagents.
• A tool works in one run but not another. Background subagents (the default) get a smaller set of built-in tools than foreground ones.
• You got a teammate instead of a subagent. With agent teams turned on, a subagent Claude gives a name to starts as a teammate. Set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS to 0 to stop that.
• Wrong model? Run /tasks while it runs to see the model, and check whether CLAUDE_CODE_SUBAGENT_MODEL_FORCE is set.

Related

• Claude Code hooks examples (7 copy-paste hooks)
• Claude Code skills examples (7 copy-paste SKILL.md files)
• Custom slash commands (Claude Code, Cursor, Codex, Copilot)
• CLAUDE.md examples (copy-paste template)
• Plan mode guide (6 tools + 6 plan prompts)
• AGENTS.md vs CLAUDE.md
• Cursor vs Claude Code vs Codex for beginners (real prices)

Sources

• Claude Code docs: Create custom subagents
• Claude Code docs: Agent teams
• Claude Code docs: Skills (run skills in a subagent)
• Claude Code docs: Model configuration (aliases)
• Cursor docs: Subagents
• OpenAI docs: Codex subagents

Checked Oct 26, 2026. These tools change often; if something here no longer matches, tell us at [email protected].