DEV Community

Cover image for Claude Code Subagents vs Agent Teams: A Better Default for Sequential Workflows
Michał Król
Michał Król

Posted on Originally published at krolmic.dev

Claude Code Subagents vs Agent Teams: A Better Default for Sequential Workflows

TL;DR

  • Subagents (.claude/agents/*.md) define a role: tools, model, system prompt, skills.
  • Agent teams are a communication group of named, still-running agents that can SendMessage each other while both are alive.
  • They're orthogonal primitives, not alternatives. A team uses subagents as the role each member plays; subagents work fine without a team.
  • For a sequential plan → approve → implement workflow, main Claude already orchestrates and shuttles output between agents — there's no live back-and-forth, so a team is overhead.
  • This post shows the two custom subagents (planner.md, implementer.md) and a /task slash command I use instead — and how I run them automatically inside a GitHub Action for a client project.

What is a custom subagent in Claude Code?

A custom subagent in Claude Code is a Markdown file under .claude/agents/ that defines a role: which tools the agent can call, which model it runs on, its system prompt, and which skills it has access to. Main Claude can spawn it as a child task, hand it work, and read its final output back into the parent context.

Subagents are personas. Each invocation gets a fresh context, scoped by the role you defined. They don't share state with each other and they don't talk to each other.

The misconception: teams are not an upgrade of subagents

This is the bit I got wrong for months.

I'd been treating "agent teams" and "custom subagents" as two ways to do the same thing. They aren't. They're orthogonal primitives.

  • Subagent = a role definition (tools, model, prompt, skills). A persona.
  • Team = a communication group of named, still-running agents that can SendMessage each other directly while both are alive. The team is the runtime that lets multiple personas talk in real time.

A team uses subagents as the role each member plays. Subagents work fine without ever being in a team.

The decision rule that finally clicked for me: reach for a team only when agents need to converse while both are alive. If your workflow is sequential — agent A produces output, you (or main Claude) approve it, then agent B starts — you don't need a team. Main Claude is already the orchestrator. It can spawn one subagent, read the output, then spawn the next.

My old approach: spawning a team for every multi-agent task

Whenever a task felt like it needed more than one agent, I'd send Claude something like this:

Create an agent team for the following task:

Before creating an agent team ask me questions if anything is unclear.

Spawn two teammates:

1. Planner (name: "planner")
   - Model: Opus
   - Mode: Default
   - Role: Analyze the codebase and produce a detailed implementation plan with file-level changes. Flag ambiguities or risks. Output the plan as a structured message.

2. Implementer (name: "implementer")
   - Model: Sonnet
   - Mode: Default
   - Role: Implement the approved plan step by step. After 2 failed fix attempts on the same issue, report the blocker to the lead.

Coordination:
- Create tasks with dependencies: implementer is blocked until planner's
  plan is approved.
- The planner's plan requires approval from both you (the lead) and me
  before the implementer starts.

Figma:
...
Enter fullscreen mode Exit fullscreen mode

This worked. It also did three things I didn't actually need:

  1. Held two agents alive in parallel when only one was active at a time.
  2. Re-defined the planner and implementer roles from scratch in every prompt, so the role definitions drifted between sessions.
  3. Burned coordination overhead on a workflow that was already strictly sequential.

The role definitions weren't version-controlled. The skill list wasn't tied to the agent. The whole thing lived in my prompt history.

My new approach: two custom subagents + a /task command

Same workflow, expressed as two .claude/agents/*.md files and a /task slash command that orchestrates them. The role definitions live in the repo, get version-controlled, and carry their tool and skill lists with them.

planner.md

---
name: planner
description: "Analyzes the codebase and produces a detailed file-level implementation plan for a given task. Flags ambiguities and risks."
model: opus
color: pink
tools: Read, Glob, Grep, Bash, WebFetch, WebSearch, Skill, TaskCreate, TaskGet, mcp__figma__*
skills: flutter-apply-architecture-best-practices, flutter-build-responsive-layout, flutter-fix-layout-issues, flutter-implement-json-serialization, flutter-use-http-package, flutter-add-widget-test, flutter-accessibility-audit
---

You are the Planner. Your job is to produce a detailed, file-level implementation plan for given task — nothing more.

## What you do

1. **If the task contains Figma links, fetch the design first — before anything else.** Extract every relevant design detail: layout, spacing, colors, typography, component structure, text content (labels, button text, headings, body copy), icons, images, and interactive states. Do not draft the plan or list open questions until the design has been fully read — many "questions" answer themselves once you see the file.
2. Read the relevant existing code so the plan is grounded in the real codebase, not assumptions.
3. Produce a structured plan covering:
   - **Goal**: one-paragraph restatement of the task.
   - **Files to change**: every file you expect to touch, listed at the function/class/method level with the specific change and the reason.
   - **Files to add**: new files with their purpose and approximate shape (key classes, public API).
   - **Test plan**: which tests to add or update.
   - **Risks & ambiguities**: anything that could go wrong.
   - **Open questions for the lead**: things that must be resolved before the implementer starts.
4. Be honest about uncertainty. If you are unsure, list it as an ambiguity with options — do not guess.

## What you do NOT do

- Do not modify files. You have no Edit/Write tools by design.
- Do not implement the work. Your output is the plan only.
- Do not pad the plan with restatements of project conventions the lead already knows. Focus on what is specific to this task.

## Output format

Return one structured message in this shape:

# Plan: <task title>

## Goal

## Files to change
- `path/to/file.dart`
  - `ClassName.methodName`: <what changes and why>

## Files to add
- `path/to/new_file.dart`: <purpose, key classes/functions>

## Test plan
- ...

## Risks & ambiguities
- ...

## Open questions for the lead
- ...

End your message with the literal line **`Plan ready for approval.`** so the lead knows to gate the implementer on it.
Enter fullscreen mode Exit fullscreen mode

A few things worth calling out about this file:

  • The planner has no Edit or Write tool. That's intentional — you cannot accidentally let the planner start coding. The role boundary is enforced by the tool list, not just by the prompt.
  • Skills are declared explicitly in skills:. Subagents don't automatically inherit the project's skills — you have to list them in the agent's frontmatter. (Built-in agents like Explorer / Plan / Verify can't access skills at all.)
  • color: pink. Pink is one of my favorite colors and the planner header pops in the terminal output. Genuine question for anyone reading: what color is your planner?

implementer.md

---
name: implementer
description: Implements a plan step by step.
model: sonnet
tools: Read, Write, Edit, Glob, Grep, Bash, WebFetch, WebSearch, Skill, TaskCreate, TaskGet, TaskUpdate, TaskList, mcp__figma__*
skills: flutter-apply-architecture-best-practices, flutter-build-responsive-layout, flutter-fix-layout-issues, flutter-implement-json-serialization, flutter-use-http-package, flutter-add-widget-test, flutter-accessibility-audit
---

Your key responsibility is to implement the given plan.

## Inputs you expect

- Implementation plan
- Any modifications the lead and user agreed on during plan approval

## What you do

Work through the plan step by step. Treat each "Files to change" / "Files to add" entry as a discrete unit of work.

## Blocker rule

If the same issue fails twice after you tried to fix it, **stop and report**. Send a single message to the lead with:

- What you were trying to do.
- The two attempts you made and why each failed.
- Your best hypothesis for the root cause.
- What you would try next, or what input you need from the lead.

Do not loop on a third attempt. The lead decides whether to redirect, re-plan, or escalate to the user.

## Reporting back

When the plan is fully implemented:

- Summarize what changed (files + one-line per change).
- List the verification checks you ran and their outcomes.
- Note anything you intentionally deferred and why.
Enter fullscreen mode Exit fullscreen mode

Two details that matter here:

  • The blocker rule lives in the implementer's prompt, not the orchestrator's. Two failed fix attempts on the same issue → stop and report. No third try without input from the lead. This used to live in my team-spawning prompt and would silently drop out whenever I rewrote the prompt. Now it's pinned to the role.
  • The implementer runs on Sonnet. Most of what an implementer does — applying a plan that's already been thought through — does not need Opus. Opus is reserved for the planner where actual reasoning happens.

/task command

For interactive use, you could just run main Claude and ask it to use the planner subagent first, then the implementer. That works, but it's repetitive. So I wrapped the orchestration in a slash command:

---
description: Run a workflow with planner and implementer subagents for a task
argument-hint: [--auto] <task description>
---

Run the workflow described below — using the `planner` and `implementer` subagents — for the following task:

$ARGUMENTS

## Mode

- **Interactive (default)**: analyze code related to the task ask clarifying questions if anything is unclear, and require my approval of the plan before implementation.
- **Automated**: if the message above contains `--auto`, skip clarifying questions and skip my approval gate. Strip the `--auto` token from the task before passing it to the planner.

## Workflow

1. **Clarify** — interactive mode only. If the task is unambiguous, skip to step 2. Otherwise ask me clarifying questions before spawning anything.

2. **Plan** — spawn the `planner` subagent with the task. Wait for the plan.

3. **Approve**
   - Interactive mode: present the plan to me. Both you and I must approve before implementation. If either of us has changes, send them back to the planner.
   - Automated mode: review the plan yourself. If it has critical issues (architectural conflicts, missing prerequisites, contradictions with `CLAUDE.md`), send it back to the planner with feedback. Otherwise approve and proceed.

4. **Implement** — spawn the `implementer` subagent with the approved plan. The implementer is blocked until approval.

5. **Blockers** — if the implementer reports a blocker after 2 failed fix attempts on the same issue:
   - Interactive mode: surface it to me with the implementer's hypothesis and options. Do not loop on a third attempt without my input.
   - Automated mode: halt the workflow and report the blocker with full context. Do not retry.
Enter fullscreen mode Exit fullscreen mode

Two modes:

  • Interactive (default) — clarify if needed, plan, present plan, wait for human approval, implement, surface blockers to me.
  • Automated (--auto) — skip the interview and the human approval gate. Use this only when the input task is well-refined. (You can — and should — write a separate skill that enforces the refinement standard before --auto ever runs.)

The --auto mode is what makes the command usable inside CI.

Real-world example: a GitHub Action for Aparkado

For Aparkado (the team behind LKW.APP), I run this as part of an end-to-end automation:

  1. A team member adds an @automation-claude comment on a Linear issue labeled App + Automation.
  2. A Make.com scenario calls GPT to validate the issue against the project's Definition of Ready and posts the JSON result (confidence score + comments) back to Linear. If the confidence score clears the threshold, Make.com creates a branch from develop, commits a task.md containing the refined task, and opens a PR.
  3. A GitHub Action triggers on PR creation. It runs Claude Code, which executes /task --auto against the contents of task.md. The two subagents do the work — plan, then implement — commit, push, and remove task.md in a final cleanup commit.
  4. A human reviews the PR. We deliberately keep this step for knowledge sharing, not because the code needs it.

The whole point of this pipeline is that the expensive part — refining the task to a state Claude can implement well — happens before the agents run. The DoR check enforces it. By the time /task --auto fires, the input is good enough that no clarifying questions are needed.

If I'd built this same pipeline with agent teams, every PR would have been spawning a runtime communication group, paying the coordination tax, and re-defining the planner and implementer roles from scratch in every CI run. With custom subagents, the roles are committed to the repo and the pipeline is just claude --slash-command "/task --auto $TASK".

FAQ

Are subagents and agent teams interchangeable?
No. Subagents define a role; teams define a runtime communication group. A team uses subagents as the role of each member, but subagents work without a team.

When should I actually use an agent team?
When you need agents to converse while both are alive — a debate, a back-and-forth code review, a long-running pair-programming session. If your workflow is sequential, main Claude is already the orchestrator and you don't need a team.

Why does the planner have no Edit or Write tools?
Role separation is enforced by the tool list, not just by the prompt. Removing those tools makes it physically impossible for the planner to start implementing the task.

Do subagents inherit the project's skills automatically?
No. You have to list each skill explicitly in the agent's skills: frontmatter. Built-in agents (Explorer, Plan, Verify) can't access skills at all — only custom subagents in .claude/agents/ can.

Can I run /task in CI without a human in the loop?
Yes — /task --auto skips the clarifying interview and the approval gate. Only do this when the input task is well-refined; otherwise the planner has nothing solid to ground its plan on. A well-defined Definition of Ready, enforced before the action runs, is what makes this safe.

What's next

This post focused on subagents. The same Anthropic Skills course also reshaped how I think about skill descriptions, the SKILL.md structure, the priority order between enterprise / personal / project / plugin skills, and when to reach for a hook or slash command instead of a skill. I'll write those up next.

If this kind of orchestration is something you're building into a client project and you want a second pair of eyes on it, get in touch — it's the work I do.

Top comments (5)

Collapse
 
skillselion profile image
Skillselion •

You have to list each skill explicitly in the agent's skills: frontmatter.

The sub-agents reference describes that field more narrowly: it decides which skills are preloaded, and has no effect on which ones the subagent can reach. Without it, a subagent can still find and invoke project, user and plugin skills through the Skill tool while it runs. Both of your agents list Skill under tools, so the Flutter skills would stay reachable with the skills: line removed.

What the field does change is context cost. The full content of every listed skill is injected when the subagent starts, so all seven skill bodies load into the planner and again into the implementer on each /task run, including runs that never touch JSON serialization or accessibility. Listing only the skills every task needs and leaving the rest to on-demand invocation would make each spawn lighter.

The same section covers the opposite case: to stop a subagent from invoking skills at all, leave Skill out of tools or add it to disallowedTools. On built-in agents the page is narrower than "can't access skills at all": it says only that they don't preload skills.

Collapse
 
kami_butt_69b922ade8de012 profile image
Agentic Affairs •

The orthogonal-primitives correction is the whole post — a team is a runtime for live conversation, a subagent is a role, and treating them as alternatives is how you end up holding two agents alive for a strictly sequential workflow. The bigger win than dropping the team is the roles living in the repo: version-controlled definitions beat re-inventing planner and implementer in every prompt. Does your /task command enforce the plan-approval gate itself, or does main Claude still shuttle the plan to you by hand?

Collapse
 
capita_harlock profile image
Ricart •

The no-back-and-forth assumption holds until the implementer finds the plan ambiguous or just wrong halfway through. A subagent can't ask anyone mid-run: it only hands back its final message, so the best it can do is return early with a blocked result and let main Claude relay that into a fresh planner run with no memory of the first one.

That round trip is where a team starts to earn its overhead, since the implementer could message a planner that is still alive instead of waiting for a re-spawn. How often does the implementer bounce a plan back in your GitHub Action runs, or does the approve step catch most of it?

Collapse
 
maxritter profile image
Max Ritter •

Keeping the role definitions in the repo gives the approval step something concrete to refer to. In my workflow, the plan is also a repo file that I approve before code exists. I then have a separate agent check each numbered requirement with evidence from the running program. I built QualityLayer for this: github.com/maxritter/qualitylayer

Collapse
 
promptalo profile image
PromptAlo •

Putting the planner and implementer roles in versioned files is the part I would keep, so the definitions cannot drift in prompt history. I would also write the approved plan to a file in the repo before the implementer starts, so the next run does not depend on the parent still holding that plan in chat.