Claude Code Subagents for Developers: When a Skill Is Not Enough

Reference

Most developers discover Skills first because they are easy to grasp: write a SKILL.md, add instructions, maybe add supporting files, and Claude can invoke that workflow when relevant. That model works well for reusable prompts, checklists, and narrow workflows.

But once your tasks get larger, noisier, or more isolated, Skills stop being enough on their own. That is where subagents become interesting.

In Claude Code, subagents are specialized assistants that run in their own context window, with their own system prompt, tool access, and permissions. Claude can delegate work to them automatically based on their description, and several built-in subagents already exist — including Explore and Plan.

A simple way to think about it:

A Skill is packaged guidance. A subagent is packaged execution in a separate working brain.

That distinction matters more than it first appears. Skills help Claude do something better. Subagents help Claude do something separately. Anthropic's docs explicitly describe subagents as a way to improve context management, preserve your main conversation, enforce constraints through tool restrictions, and route work to more appropriate models when needed.

Contents

The real difference between Skills and subagents
When a Skill is enough
When a Skill is not enough
When to fork context
The three practical patterns that matter most
Example use cases
A warning most developers should hear early
A practical decision framework
How to write better subagents
The architecture that actually makes sense

1. The real difference between Skills and subagents

A Skill extends Claude with instructions and reference material. Claude can load a Skill automatically when relevant, or you can invoke it directly. Skills live as files, can include frontmatter and supporting files, and are designed for reusable workflows.

Claude Code also supports running a Skill in a subagent by setting context: fork, which means the Skill content becomes the prompt that drives an isolated subagent rather than running inside the main conversation.

A subagent is broader. It is not just a prompt file. It is a specialized worker with its own context window, custom prompt, specific tool access, and independent permissions. Claude delegates to it when the task matches its description, and the subagent works independently before returning results to the main conversation.

A practical rule:

Use a Skill when you want a reusable playbook
Use a subagent when you want isolated execution
Use a Skill with context: fork when you want both

2. When a Skill is enough

A normal Skill is enough when the task should stay close to the current conversation — when the work depends heavily on current context, or when you want Claude to keep the reasoning, code exploration, and implementation all in one thread.

Examples:

review a small patch
apply your repo's coding conventions
generate a PR summary from already-known context
run a repeatable checklist
document an API handler in the current area of the repo

Skills are for extending Claude with instructions and workflows while keeping the default behavior inside the main conversation.

3. When a Skill is not enough

A plain Skill starts breaking down when one of these things becomes true.

The task generates a lot of noise

Anthropic explicitly recommends subagents for high-volume operations because verbose output — test logs, fetched documentation, log processing — can consume significant context. The point is to keep the noise inside the worker and return only the useful summary to the main conversation.

Examples: running large test suites, processing huge logs, searching many files for a bug pattern, reviewing many changed files.

You need strict tool boundaries

Subagents have their own tool access and permissions. That makes them useful when you want one worker to be intentionally limited — a read-only code explorer, a DB query validator, or a documentation agent that should never edit files. Anthropic calls out enforced constraints through tool restriction as one of the core benefits.

The work is self-contained

Use subagents when the work is self-contained and can return a summary. Use the main conversation when the task requires lots of back-and-forth, shared context across planning and implementation, or a quick targeted change.

You want parallelism

Subagents can run in the foreground or background. Background subagents run concurrently while you continue working. They inherit pre-approved permissions and auto-deny anything not approved up front — useful for research, long scans, and isolated checks happening while you keep moving.

4. When to fork context

If you only remember one thing from this article, remember this:

Fork context when the work would pollute the main conversation more than it would help it.

When you add context: fork to a skill, the skill runs in an isolated subagent context instead of directly inside the current conversation. The skill content becomes the prompt for that subagent, and the subagent does not get your main conversation history.

Fork context when:

the task is verbose
the task is mostly exploratory
you only need the result, not the full process
the worker should have tighter permissions than the main session
you want a specialist prompt or model for one step
the work can be summarized cleanly at the end

Do not fork context when:

you need frequent clarification and iteration
the planning, coding, and testing phases all rely on shared live context
the change is small and latency matters
you are doing a fast surgical edit in a file you are already discussing

Subagents are not free. They start fresh, so there is setup overhead. Latency can matter because subagents need time to gather context.

For the full breakdown of context: fork, see Claude Code context: fork Explained.

5. The three practical patterns that matter most

Pattern 1: Skill only

You stay in the main conversation and use a reusable workflow.

Good for: style checks, small reviews, deterministic repo conventions, short doc generation.

Pattern 2: Skill with context: fork

You already like the Skill model, but the task is noisy or self-contained enough that it should run in isolation.

Good for: deep codebase research, pull request summarization using fetched context, test-log analysis, documentation synthesis.

Pattern 3: Custom subagent that also uses skills

A subagent can preload Skills as reference material while also bringing its own system prompt and delegated task. In other words, Skills and subagents are not rivals — they stack.

Good for: a security reviewer with reference skills for internal standards, a debugger with repo-specific troubleshooting skills, a migration worker with validation skills and strict permissions.

6. Example use cases

Repository exploration

A common mistake is asking the main conversation to do big exploratory searches through a large codebase. That fills context fast and mixes raw exploration with the actual problem you are trying to solve.

Better pattern: a read-only research Skill with context: fork and the Explore agent. The subagent handles the search work and returns a distilled answer instead of dragging all the raw exploration into the main thread.

PR review at scale

A simple review Skill works when the diff is small. It stops working well when the PR is huge, has many files, or needs deep analysis.

Better pattern: a review-pr Skill with context: fork, or a dedicated code-reviewer subagent with strict read-only permissions. The noisy scanning stays isolated and the main conversation gets the conclusions.

Debugging production-like failures

Debugging is often messy: logs, traces, test reruns, grep output, docs, and dead ends. That is exactly the kind of work that can poison the main context if left inline.

A debugging subagent is a strong pattern because it can be tool-limited, consume noisy inputs, and return only hypotheses, evidence, and next steps.

Background research while you keep coding

You can run a subagent in the background, continue working in the main thread, and come back to the summary later. Ask a background subagent to map a subsystem, keep working, come back to the result when it finishes. That is materially different from a Skill in the main context.

For the full trade-off discussion on foreground versus background, see Foreground vs Background Subagents in Claude Code.

7. A warning most developers should hear early

Do not reach for subagents just because they sound more advanced.

Most teams should not turn every repeated workflow into a custom subagent. Skills are cheaper mentally, easier to author, and work well for reusable prompts and workflows. Also, subagents cannot spawn other subagents. If you imagine deeply nested delegation trees, that is not how this system works. Anthropic recommends chaining subagents from the main conversation, or using Skills when nested delegation would otherwise be needed.

In plain English: if a Skill works, keep it a Skill.

8. A practical decision framework

Ask these five questions before building a subagent.

Does this workflow need reusable instructions?

If yes → start with a Skill.

Does the work generate lots of output I do not want in the main thread?

If yes → fork context or use a subagent.

Does the worker need special permissions or tool restrictions?

If yes → use a subagent or a forked Skill.

Does the task need frequent interactive back-and-forth?

If yes → keep it in the main conversation.

Do I want a specialist worker that Claude can delegate to automatically?

If yes → define a subagent with a very clear description. Anthropic states that Claude uses the task description, the subagent's description, and current context to decide when to delegate, and even suggests including language like "use proactively" if you want more aggressive delegation.

For a detailed look at writing descriptions that actually trigger delegation, see How to Write Claude Code Subagent Descriptions That Trigger Delegation Reliably.

9. How to write better subagents

The biggest practical lesson from Anthropic's Skills best-practices guide also applies here: be concise, structure the instructions well, and write strong descriptions. Anthropic emphasizes that good Skills are concise, well-structured, tested with real usage, and that the description should say both what the Skill does and when to use it.

That same design instinct carries directly into subagents because delegation depends on the description.

For subagents:

describe the task type clearly
describe when delegation should happen
keep the role narrow
do not dump generic philosophy into the prompt
test it on real work, not toy prompts

10. The architecture that actually makes sense

The strongest setup for serious users is usually this:

CLAUDE.md for repo-wide conventions
A handful of Skills for repeatable workflows
2–4 subagents for noisy or specialized work
Some Skills with context: fork where reuse and isolation both matter
Hooks only where you need lifecycle enforcement or guardrails — Claude Code exposes hook events like SubagentStart and SubagentStop for automation and control

That is a sane architecture. Anything bigger risks creating complexity for its own sake.

Skills are the right first abstraction because they are simple, reusable, and cheap to reason about. But once your workflows become verbose, isolated, permission-sensitive, or parallel, a plain Skill is not enough. That is the moment to introduce subagents, or to run a Skill with context: fork.

Use Skills for repeatable playbooks. Use subagents for contained specialist work. Use both together when the workflow is reusable and should be isolated.

Further reading in this series: