Claude Code Subagents: What They Are and the Best Subagent Skills

Claude Code subagents are separate Claude instances that take on one task in their own context window and send back a summary, so long searches, test output and reviews do not crowd your main conversation. This guide explains how they work using Anthropic's documentation, shows how to define one, and then compares the subagent and multi-agent skills in the directory by what each does, what it needs and what it costs.

If you want a pre-built workflow rather than a custom agent file, jump to the skills comparison. If you want to write your own subagent, the definition section has a working example.

What are Claude Code subagents?

According to Anthropic's subagent documentation, a subagent runs with a custom system prompt, its own tool access and independent permissions. It makes its own model requests, which count toward your usage. When it finishes, Claude receives the result and continues the main conversation.

Claude Code includes built-in subagents. Explore is a read-only agent for searching and analyzing a codebase. Plan researches during plan mode. A general-purpose agent handles multi-step tasks that need both exploration and changes. Claude picks among them, and your custom subagents, by reading each one's description.

What a standard subagent receives is narrow: the delegation prompt Claude writes, project instructions such as CLAUDE.md, a git status snapshot, and any skills you preload. It does not get your conversation history. That is the main benefit and the main risk, because a vague delegation prompt produces vague work.

How do you define a custom subagent?

A subagent is a Markdown file with YAML frontmatter. Only name and description are required. Typical optional fields include tools (an allowlist), model, permissionMode, maxTurns, skills, hooks, memory and isolation. Here is a small read-only reviewer:

---
name: change-reviewer
description: Reviews a diff for bugs and unclear code. Use after finishing a task or before a merge.
tools: Read, Grep, Glob, Bash
model: sonnet
---

You review code changes. Read the diff, check each changed function
against its callers, and report findings as Critical, Important or Minor
with a file and line for each. Do not edit files.

Where the file lives sets its scope. The documentation lists managed settings first, then the --agents command-line flag, then .claude/agents/ in a project, then ~/.claude/agents/ for your user, then agents bundled in a plugin. Earlier entries win when names clash.

You can ask for a subagent in plain language, mention it with @, or run a whole session as one with claude --agent. The isolation: worktree setting runs a subagent in a temporary git worktree, which helps when parallel agents might edit the same files.

Subagents, skills and the main conversation

The three tools solve different problems, and Anthropic's documentation draws the lines clearly.

Skills and subagents connect in two ways. A subagent's skills field preloads skill content into its startup context. In the other direction, a skill can set context to fork and name an agent, so the skill's content becomes the prompt for an isolated subagent. The Claude skills documentation describes that option. For the wider comparison with MCP servers and plugins, read Claude skills vs MCP, plugins and subagents.

Best subagent skills at a glance

The directory lists hundreds of skills under subagents and multi-agent orchestration. These are the ones that stand out for clear scope and a stated licence. All passed the directory's automated SKILL.md check, which is a pattern match and not an audit.

Skills that run a plan with subagents

Subagent-driven development is the most complete workflow. It sends each task to a fresh implementer subagent, handles one of four reported statuses, runs a spec and quality review, allows up to five fix rounds, and ends with a whole-branch review. It requires an isolated git worktree, a written plan and a ledger file, and it tells you to name the model for each subagent so cheap work does not run on an expensive default.

• Best for: long plans with independent tasks.
• Requirements: a plan file, worktrees, scripts the skill provides.
• Trade-off: its own comparison says it costs a fresh context per task and per review, whereas inline execution costs one context plus one final review.

The inline alternative is executing plans, which the skill itself recommends when tasks are mostly independent and cost matters more than a gate on every task.

Requesting code review is the smallest useful piece: a general-purpose reviewer subagent that receives a description, requirements and two commit hashes and returns Critical, Important and Minor findings. More choices are in our guide to code review skills.

Skills for parallel work and agent teams

Dispatching parallel agents is short and opinionated. Use it for two or more independent problems, such as test failures with different causes. It groups failures by domain, writes a focused prompt for each agent and sends all calls in one response. It warns against it when failures are linked or agents would share state.

• Best for: several unrelated failing tests or subsystems.
• Requirements: an agent that can run subagents in parallel.
• Trade-off: you must still check for conflicts and run the full suite afterward.

Harness designs a project-specific setup: agent files under .claude/agents and skills under .claude/skills. Its seven phases run from auditing the current state to validation, and it chooses between workflow coordination, persistent agents that message each other and plain subagent delegation.

• Best for: a repeatable pipeline you will run many times.
• Requirements: an agent runtime that supports the modes it describes.
• Trade-off: it writes several files into your project, so review them before committing.

CCPM turns a PRD into an epic, then GitHub issues, then parallel agents working those issues, with bundled scripts for status and blocked-work reports. It is built around GitHub and is not meant for debugging or review.

Skills that help you write subagents

Agent development is Anthropic's guide for agent files in Claude Code plugins. It sets rules such as a lowercase hyphenated name of 3 to 50 characters, a description that states when to trigger, and a body written in the second person. It treats the color field as required, while the main subagent documentation lists color as optional, so check which one your Claude Code version needs.

Agent builder argues for starting with a handful of capabilities and adding planning or subagents only when real use shows a need, which is a useful brake on over-building.

Skills that cross agent boundaries

O2 loop keeps a coder subagent alive across rounds, uses a fresh reviewer each time and makes only local commits. GitHub review iteration delegates triage and implementation of pull request comments to two sibling agents and loops until nothing actionable remains.

Paseo advisor launches one separate agent through the Paseo CLI for a second opinion, with a briefing that ends by forbidding edits. It needs Paseo, an Apache-2.0 app that runs several coding agents including Claude Code and Codex, but the skill's own repository licence shows as NOASSERTION, so read the licence file. Its sibling Paseo committee asks two agents with contrasting profiles to analyze a stuck problem in parallel and reconcile their answers.

tmux session control lets an agent send keystrokes to interactive programs and wait for output, and it advises separate git worktrees when orchestrating parallel coding agents. It needs tmux, so it runs on macOS and Linux or WSL, not native Windows.

Limits and costs to plan for

• Usage: every subagent makes its own requests, so parallel agents multiply token use.
• Context: standard subagents do not see your conversation, so write self-contained prompts.
• Conflicts: parallel agents that edit the same files need separate worktrees or clearly separate scopes.
• Review overhead: per-task review gates add quality and latency together.
• Licences: one skill here is AGPL-3.0 and another has no recognized licence identifier, which matters if you copy them into products.

Which subagent skill should you start with?

• First try: requesting code review, because it is one small step with a clear payoff.
• Several independent bugs: dispatching parallel agents.
• A written plan to execute: subagent-driven development, or executing plans if you prefer a single context.
• Writing your own agents: the agent development skill, then adapt the example above.
• Installing them: the Claude Code and Codex pages list where each agent keeps skills and the install methods.