Skip to main content
skill CX Codex

orchestrating-subagents — Claude Code skill: setup and usage

orchestrating-subagents is a Claude Code skill for dividing project tasks among subagents, with parallel explorers and independent code review in isolated contexts.

MIT ★ 539 updated 2026-10-29

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add ZaxbyHub/opencode-swarm --skill orchestrating-subagents -a claude-code
Open on GitHub

What orchestrating-subagents does

This skill establishes economics and discipline for delegating tasks across subagent roles. Explorers can run on lighter models with lower effort settings because downstream review catches omissions. In contrast, reviewers and critics must use the strongest session model with high effort. They always launch in fresh contexts so prior conversation history never biases their code validation.

Parallel fan-out requires disjoint work boundaries. The orchestrator must fire independent agents within a single prompt, avoiding overlapping directories or redundant file inspections. Every delegation prompt specifies the deliverable structure, concrete file:line citation requirements, and rigid outcome labels. Heavy search outputs stay encapsulated inside subagents, which keeps the primary context uncluttered.

Direct execution handles single-fact lookups that need only one or two Grep or Read calls. Spawning overhead makes sense only when buying breadth or independent verification.

What it helps with

  • Assign subagent roles with dedicated model tiers for discovery, implementation, and critique
  • Run independent code reviews using fresh agents with no prior conversational bias
  • Restrict subagent prompt scopes and require precise file and line evidence in results
  • Keep the orchestrator context uncluttered by offloading heavy reading tasks

Example prompts for the agent

  • Launch parallel subagents to map out payment webhook handlers in src/billing/ without overlapping scopes
  • Spin up an adversarial reviewer in a fresh context to evaluate the latest diff against our conventions
  • Draft a bounded prompt for an explorer agent to locate unused database models and report file:line references

How to install orchestrating-subagents

1Skills CLI (Vercel)

npx skills add ZaxbyHub/opencode-swarm --skill orchestrating-subagents -a claude-code

2Manually: put the files in place

~/.claude/skills/orchestrating-subagents/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/orchestrating-subagents/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about orchestrating-subagents

How to install orchestrating-subagents in Claude Code?

Run npx skills add ZaxbyHub/opencode-swarm --skill orchestrating-subagents -a claude-code in your terminal.

Which subagent roles can use smaller models?

Down-tiering model selection and reasoning effort is allowed only for explorer roles that gather candidates. Reviewers and critics require the primary session model running at high effort in a fresh context.

What happens if the harness cannot spawn subagents?

The agent runs the review checklist directly as an explicit fallback self-review and notes in the final report that an isolated reviewer was unavailable.

Source text

SKILL.md · MIT
---
name: orchestrating-subagents
description: >
  Tiering and economics for delegating to subagents: which agent type, model,
  and effort to use per role (explorer, implementer, reviewer, critic), how many
  agents to launch in parallel, how to write scoped subagent prompts with
  bounded structured returns, and how to keep the main context clean. Use when
  launching subagents, parallel explorers, independent reviewers, or critic
  passes — especially for swarm-mode, qa-sweep, or issue-tracer work.
metadata:
  audience: swarm-plugin
---

# Orchestrating Subagents

Swarm-mode work in this repo delegates heavily (explorer → reviewer → critic).
This skill defines HOW to delegate so validation gates stay strong while
breadth stays fast and cheap. It complements — never replaces — the gates in
`.claude/session/swarm-mode.md`, qa-sweep, and swarm-implement.

## Role → tier mapping

| Role | Agent type | Model / effort | Rationale |
|---|---|---|---|
| Explorer (mapping, candidate findings) | `Explore` when read-only suffices | Cheaper/faster tier acceptable; low–medium effort | Recall-bound, not reasoning-bound; the reviewer gate catches misses |
| Implementer (scoped edits) | general-purpose | Session model; medium–high effort | Edits need project conventions (CLAUDE.md context) |
| Reviewer (independent validation) | general-purpose, **fresh context** | Session (strongest) model; high effort | Precision-bound; false approvals are the expensive failure |
| Critic (final challenge) | general-purpose, **fresh context** | Session (strongest) model; high effort | Same — this is the last line of defense |

Hard rule: economize on explorers, never on reviewers or critics. If the
harness exposes model or effort overrides for subagents, tier explorers down;
do not tier the reviewer or critic below the session model or below high
effort. If no override is available, tier by agent type (`Explore` is
lightweight: read-only tools, skips CLAUDE.md) and by prompt scope.

## Fan-out discipline

- Launch parallel agents only for **disjoint scopes**. Before launching, write
  one line per agent stating its scope; if two overlap, merge them.
- 2–4 explorers per wave is a heuristic only when the active workflow does
  not define its own fan-out contract. A workflow-specific contract overrides
  this heuristic: PR review, for example, requires all six base dimensions and
  all eleven risk families to be covered on every PR — its capability profiles
  and depth tiers (see swarm-pr-review) govern how many lanes carry that
  coverage, and under the plugin's mechanical controller the tier is computed
  from the bound diff and the matching lane floors are enforced outright. No
  time, cost, repository-size, or simplicity
  rationale may reduce the coverage a workflow mandates.
  Outside fixed-fan-out workflows, more agents than distinct scopes adds token
  cost and synthesis burden without adding recall.
- Launch independent agents **in a single message** so they run concurrently.
- Do not re-run a search an agent is already doing; wait for its report.
- Scale waves, not width: if the first wave surfaces new territory, launch a
  second targeted wave rather than one giant speculative first wave.

## Subagent prompt contract

Every delegation prompt must state:

1. **Scope** — exact directories, files, or question. Name what is out of scope.
2. **Deliverable** — the structure of the report (per-item findings, then a
   ranked summary). The agent's final message is the only thing you receive.
3. **Evidence bar** — exact `file:line` references; no invented paths; verify a
   path exists before citing it.
4. **Status labels** — explorers return CANDIDATE findings only; reviewers
   classify CONFIRMED / DISPROVED / UNVERIFIED / PRE_EXISTING; reviewer and
   critic verdicts are APPROVE / NEEDS_REVISION / BLOCKED.
5. **Output bound** — compact structured returns; no full-file dumps.

For reviewers and critics additionally:
- Give the **claims and locations**, not the author's justification — the
  reviewer must re-derive, not confirm, the reasoning.
- State the adversarial default explicitly: "default to DISPROVED/UNVERIFIED
  unless the code evidence supports the finding."
- A reviewer or critic must be a **fresh agent**, never a continued
  conversation with the agent whose work it judges.

## Independence and staleness

- Reviewer and critic review the **latest diff**, not a description of it. Give
  them the branch state and the validation evidence, and require them to run
  `git diff`/`git log` themselves.
- Any edit after an approval invalidates it. Record what was approved (e.g.
  `git rev-parse HEAD`, `git diff --stat`) so staleness is checkable — see the
  durable-session-state skill.

## Nesting limitation

Whether a subagent can spawn further subagents depends on the harness and
agent type — check whether a subagent tool (`Agent` or `Task`) is actually
available in your context before assuming either way. If a skill mandating
fresh-subagent review (qa-sweep, swarm-implement) executes in a context
**without** a subagent tool:
- perform the same review checklist yourself as a clearly labeled
  **fallback self-review**, and
- disclose in your report that independent review was unavailable in this
  context, so the orchestrator can re-run the gate with a real fresh agent.
Never silently present self-review as independent review.

## Main-context hygiene

- Push reading-heavy work into subagents; keep the main thread for scoping,
  synthesis, and decisions.
- Do not paste subagent transcripts or large tool outputs back into the main
  thread; carry forward only validated findings and verdicts.
- When a subagent report arrives, extract the load-bearing facts into your
  durable task artifacts (see durable-session-state) before moving on.

## When not to delegate

Answer directly, without a subagent, when the task is a single-fact lookup you
can resolve with one or two targeted Grep/Read calls, or when you already know
the file and symbol. Delegation overhead should buy breadth, isolation, or
independence — if it buys none of those, skip it.

© ZaxbyHub · MIT · ZaxbyHub/opencode-swarm

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set121

The whole set →
test-file-split test-file-split breaks an oversized test file into parts along describe() boundaries when it nears the 500-line cap or blows past it. CX Codex +1 ★ 539repo stars fork-pr-operations fork-pr-operations guides agents through fork pull request workflows: GitHub Actions approval, safe rebasing with force-with-lease, and handling multi-round bot reviews. CX Codex +1 ★ 539repo stars parallel-work-check parallel-work-check is a Claude Code skill that compares local and remote commits on an existing branch and reviews new changes. It helps catch overlapping work before editing. CX Codex +1 ★ 539repo stars design-docs Writes and syncs a project's design docs: domain, technical spec, behavior spec, plus a traceability registry and changelog. CX Codex +1 ★ 539repo stars commit-pr The commit-pr skill guides commits, pull request updates, and CI checks in opencode-swarm. Use it when publishing issue-related code changes or closing out a PR. CX Codex +1 ★ 539repo stars contributing contributing walks an agent through the full pull-request cycle in the opencode-swarm repo: branch naming, commit format, a release-notes fragment, local checks and the PR template. CX Codex +1 ★ 539repo stars clarify-spec clarify-spec resolves spec clarification markers and ambiguous requirements in Swarm projects by asking targeted questions one at a time. CX Codex +1 ★ 539repo stars pre-phase-briefing pre-phase-briefing builds phase-start context, reviews prior retrospectives, and checks whether the referenced codebase matches the planned work. CX Codex +1 ★ 539repo stars

Project sponsors

Companies that keep this analytics open