nested-subagents

Spawns nested sub-agent trees up to five levels deep via Claude Code's Task tool for context-managed delegation.

70.1k|8.4k|Updated Jun 2, 2025
One-click install
npx skills add https://github.com/ruvnet/claude-flow --skill nested-subagents
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: nested-subagents
Source: https://github.com/ruvnet/claude-flow/tree/main/plugins/ruflo-agent/skills/nested-subagents
Command: npx skills add https://github.com/ruvnet/claude-flow --skill nested-subagents

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Deep, multi-layered problems (research → expand → verify → synthesize) can exhaust a single agent's context window. This Skill delegates work through a tree of sub-agents where each level gets a fresh context window, so intermediate state never pollutes the top-level agent.

Core Features & Use Cases

  • Nested delegation up to depth 5: A nested-coordinator agent decomposes the problem with TodoWrite, then spawns children that can themselves spawn children via the Task tool.
  • Context isolation per level: Children return ~200-token structured summaries instead of full transcripts, keeping the parent's context clean.
  • Depth guard rails: A pre-task hook enforces a default cap of 4 levels (configurable in claude-flow.config.json) and returns a typed NESTING_DEPTH_EXCEEDED error at the limit.
  • Tree-shaped cost attribution: A post-task hook persists parent_agent_id and depth to AgentDB for per-tree spend analysis.
  • Use Case: A recursive investigation where a coordinator spawns research agents, each of which spawns verification and synthesis agents, with only summaries climbing back to the root.

Quick Start

Ask the agent to decompose your problem statement into a nested sub-agent tree using the nested-coordinator, then review the proposed spawn tree before approving deep work.

Frequently Asked Questions about nested-subagents

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I spawn nested sub-agents in Claude Code?

Invoke the nested-coordinator agent via the Task tool with your problem statement. The coordinator plans the spawn tree with TodoWrite, then any agent whose frontmatter includes Task in its tools list can spawn the next level, up to the depth cap.

What is the maximum nesting depth for sub-agents?

The Anthropic API supports 5 levels, while the default pre-task hook enforces 4 levels as a guard band. The cap is configurable in claude-flow.config.json, and CLAUDE_FLOW_STRICT_NESTING=true enforces it strictly.

When should I use nested sub-agents instead of flat fan-out?

Use nesting when the problem decomposes into layers that would each pollute the parent's context, such as research then verify then synthesize. If a single flat fan-out of Task calls suffices, skip nesting because it adds latency.

What happens when the nesting depth limit is exceeded?

The pre-task hook returns a typed NESTING_DEPTH_EXCEEDED error containing the full agent chain. The parent agent can then decide to summarize, hand off, or abort the delegation.

Can leaf agents spawn their own sub-agents?

No. Leaf agents must not include Task in their tools list, so they cannot spawn children. Only coordinators or agents explicitly granted the Task tool can delegate to the next level.