subagent-teams

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

<objective> Orchestrate teams of Task tool subagents within a single Claude Code session. Unlike agent-teams-skill (which uses worktrees + terminals for full parallel sessions), this skill uses the Task tool for lightweight, in-session parallelism with shared codebase access. </objective>

<quick_start> Research fan-out:

Launch 3 Explore agents in parallel:
- Agent 1: Search for authentication patterns
- Agent 2: Search for database schema
- Agent 3: Search for API endpoints

Implementation fan-out:

1. Plan agent designs architecture
2. 3 general-purpose agents build components in parallel
3. code-reviewer agent validates all changes

</quick_start>

<success_criteria>

Subagents spawned with correct model tiers (Haiku for search/review, Sonnet for code, Opus for architecture)
Parallel agents complete independently without conflicting file edits
Fan-in synthesis captures key findings from all background agents
Total parallel agents stays within 5-7 limit to avoid context overflow
TaskCreate/TaskUpdate used for progress tracking with live UI spinners </success_criteria>

<triggers> - "set up subagent team", "fan out", "parallel tasks", "Task tool team" - "research in parallel", "explore in parallel", "review in parallel" - "spawn subagents", "in-session agents" </triggers>

<objective> 在单个Claude Code会话内编排Task工具子Agent团队。与agent-teams-skill（使用工作树+终端实现全并行会话）不同，本技能使用Task工具实现轻量级、会话内的并行处理，且支持共享代码库访问。 </objective>

<quick_start> 研究工作分发：

Launch 3 Explore agents in parallel:
- Agent 1: Search for authentication patterns
- Agent 2: Search for database schema
- Agent 3: Search for API endpoints

实现工作分发：

1. Plan agent designs architecture
2. 3 general-purpose agents build components in parallel
3. code-reviewer agent validates all changes

</quick_start>

<success_criteria>

子Agent使用正确的模型层级启动（搜索/评审用Haiku，代码生成用Sonnet，架构设计用Opus）
并行Agent可独立完成任务，不会出现文件编辑冲突
结果汇总需捕获所有后台Agent的关键发现
并行Agent总数保持在5-7个以内，避免上下文溢出
使用TaskCreate/TaskUpdate结合实时UI加载图标跟踪进度 </success_criteria>

When to Use This vs agent-teams

本技能与agent-teams的适用场景对比

Factor	subagent-teams (this)	agent-teams
Isolation	Shared codebase, shared context	Full worktree isolation
Overhead	Lightweight — just Task tool calls	Heavy — terminals, git branches, ports
Best for	Research, review, doc updates	Feature builds, conflicting file edits
Max agents	5-7 (context limit)	2-3 (M1 8GB RAM limit)
Duration	Minutes	Hours
Coordination	TeamCreate + TaskList/TaskUpdate	WORKTREE_TASK.md + git branches

Rule of thumb: If agents will edit the same files → use agent-teams (worktree isolation). If agents read-only or edit different files → use subagent-teams (faster, lighter).

因素	subagent-teams（本技能）	agent-teams
隔离性	共享代码库、共享上下文	完全工作树隔离
资源开销	轻量级 — 仅需调用Task工具	重量级 — 终端、Git分支、端口
最佳适用场景	研究、评审、文档更新	功能构建、存在文件编辑冲突的场景
最大Agent数量	5-7个（受上下文窗口限制）	2-3个（受M1 8GB内存限制）
任务时长	数分钟	数小时
协作方式	TeamCreate + TaskList/TaskUpdate	WORKTREE_TASK.md + Git分支

经验法则： 如果Agent可能编辑同一文件 → 使用agent-teams（工作树隔离）。如果Agent仅读取或编辑不同文件 → 使用subagent-teams（更快速、轻量）。

Task Tool Parameters (Complete Reference)

Task工具参数（完整参考）

Core Parameters

核心参数

javascript

{
  subagent_type: "Explore" | "general-purpose" | "Plan" | ...,
  model: "haiku" | "sonnet" | "opus",
  prompt: "...",
  description: "3-5 word summary",        // Required
  run_in_background: true,                 // For parallel execution
  team_name: "my-team",                    // Scope to a team's task list
  name: "agent-1",                         // Name for team messaging
  mode: "default"                          // Permission mode (see below)
}

javascript

{
  subagent_type: "Explore" | "general-purpose" | "Plan" | ...,
  model: "haiku" | "sonnet" | "opus",
  prompt: "...",
  description: "3-5 word summary",        // Required
  run_in_background: true,                 // For parallel execution
  team_name: "my-team",                    // Scope to a team's task list
  name: "agent-1",                         // Name for team messaging
  mode: "default"                          // Permission mode (see below)
}

Agent Frontmatter Fields (for .md agent files)

Agent前置字段（适用于.md Agent文件）

Field	Type	Purpose
`name`	string	Agent identifier
`description`	string	What the agent does (shown in routing)
`model`	string	Default model: haiku, sonnet, opus
`tools`	list	Allowed tools (restrict agent capabilities)
`disallowedTools`	list	Explicitly blocked tools
`permissionMode`	string	`default` , `acceptEdits` , `dontAsk` , `plan`
`mcpServers`	list	MCP servers available to the agent
`hooks`	object	Event-driven automation (PostToolUse, etc.)
`maxTurns`	number	Max API round-trips before stopping
`skills`	list	Skills available to the agent
`memory`	object	Persistent state: `scope: user\|project\|local`

字段	类型	用途
`name`	字符串	Agent标识符
`description`	字符串	Agent的职责（用于路由展示）
`model`	字符串	默认模型：haiku, sonnet, opus
`tools`	列表	允许使用的工具（限制Agent能力）
`disallowedTools`	列表	明确禁止使用的工具
`permissionMode`	字符串	`default` , `acceptEdits` , `dontAsk` , `plan`
`mcpServers`	列表	Agent可访问的MCP服务器
`hooks`	对象	事件驱动自动化（如PostToolUse等）
`maxTurns`	数字	停止前的最大API往返次数
`skills`	列表	Agent可用的技能
`memory`	对象	持久化状态： `scope: user\|project\|local`

Permission Modes

权限模式

Mode	Behavior
`default`	Normal approval flow
`acceptEdits`	Auto-approve file edits, prompt for Bash
`dontAsk`	Auto-approve everything (use with trusted agents)
`plan`	Agent must get plan approved before implementing
`delegate`	Agent can only delegate to sub-agents

模式	行为
`default`	常规审批流程
`acceptEdits`	自动批准文件编辑，执行Bash命令需提示
`dontAsk`	自动批准所有操作（仅用于可信Agent）
`plan`	Agent必须先获得计划批准才能执行实现工作
`delegate`	Agent仅能将任务委托给子Agent

Spawning Restrictions

启动限制

Restrict which subagents an agent can spawn using

Task(agent_type)

in the tools field:

yaml

tools:
  - Read
  - Glob
  - Task(Explore)        # Can only spawn Explore subagents
  - Task(code-reviewer)  # Can also spawn code reviewers

通过在tools字段中使用

Task(agent_type)

限制Agent可启动的子Agent类型：

yaml

tools:
  - Read
  - Glob
  - Task(Explore)        # 仅能启动Explore子Agent
  - Task(code-reviewer)  # 也可启动代码评审Agent

Model Selection Guide

模型选择指南

Task	Model	Why
File search, pattern matching	haiku	Fast, cheap, sufficient
Code review, bug finding	haiku	Pattern matching, not generation
Code generation, refactoring	sonnet	Quality matters for code
Architecture decisions	opus	Complex reasoning needed
Documentation writing	sonnet	Needs context understanding

任务	模型	原因
文件搜索、模式匹配	haiku	快速、低成本、性能足够
代码评审、漏洞检测	haiku	侧重模式匹配，无需生成
代码生成、重构	sonnet	代码质量至关重要
架构决策	opus	需要复杂推理能力
文档撰写	sonnet	需要上下文理解能力

Team Patterns

团队模式

1. Research Team (3 Explore agents)

1. 研究团队（3个Explore Agent）

Fan-out 3 search strategies, fan-in to synthesize:

Task 1 (Explore, haiku): "Search for [pattern] in src/"
Task 2 (Explore, haiku): "Search for [pattern] in tests/"
Task 3 (Explore, haiku): "Search for [pattern] in docs/"
→ Fan-in: Synthesize findings into summary

When: Exploring unfamiliar codebase, understanding how a feature works across layers.

分发3种搜索策略，汇总结果：

Task 1 (Explore, haiku): "Search for [pattern] in src/"
Task 2 (Explore, haiku): "Search for [pattern] in tests/"
Task 3 (Explore, haiku): "Search for [pattern] in docs/"
→ 汇总：将发现整理为摘要

适用场景： 探索不熟悉的代码库，了解功能在各层的实现逻辑。

2. Implement Team (architect → builders → reviewer)

2. 实现团队（架构师 → 构建者 → 评审员）

Sequential pipeline with parallel build phase:

Phase 1: Plan agent designs architecture (1 agent)
Phase 2: 2-3 general-purpose agents build components (parallel)
Phase 3: code-reviewer validates (1 agent)

When: Building a feature with multiple independent components.

包含并行构建阶段的顺序流水线：

阶段1：Plan Agent设计架构（1个Agent）
阶段2：2-3个通用Agent并行构建组件
阶段3：code-reviewer验证成果（1个Agent）

适用场景： 构建包含多个独立组件的功能。

3. Review Team (3 reviewers in parallel)

3. 评审团队（3个评审员并行工作）

Task 1 (code-reviewer, haiku): "Review src/auth/ for security"
Task 2 (code-reviewer, haiku): "Review src/api/ for consistency"
Task 3 (code-reviewer, haiku): "Review src/db/ for performance"
→ Fan-in: Aggregate findings, deduplicate

When: Pre-PR review of large changesets.

Task 1 (code-reviewer, haiku): "Review src/auth/ for security"
Task 2 (code-reviewer, haiku): "Review src/api/ for consistency"
Task 3 (code-reviewer, haiku): "Review src/db/ for performance"
→ 汇总：整合发现，去重

适用场景： 对大型变更集进行PR前评审。

4. Explore Team (3 search strategies)

4. 探索团队（3种搜索策略）

Task 1 (Explore, haiku): Glob for file patterns
Task 2 (Explore, haiku): Grep for code patterns
Task 3 (Explore, haiku): Read key entry points
→ Fan-in: Build mental model of codebase area

When: First time working in a new area of the codebase.

Task 1 (Explore, haiku): Glob for file patterns
Task 2 (Explore, haiku): Grep for code patterns
Task 3 (Explore, haiku): Read key entry points
→ 汇总：建立对代码库相关区域的认知模型

适用场景： 首次接触代码库的新区域。

5. Doc Team (N independent file updaters)

5. 文档团队（N个独立文件更新Agent）

Task 1 (general-purpose, haiku): "Update README.md with new API"
Task 2 (general-purpose, haiku): "Update CHANGELOG.md"
Task 3 (general-purpose, haiku): "Update API docs"
→ No fan-in needed (independent files)

When: Updating multiple independent documentation files.

Task 1 (general-purpose, haiku): "Update README.md with new API"
Task 2 (general-purpose, haiku): "Update CHANGELOG.md"
Task 3 (general-purpose, haiku): "Update API docs"
→ 无需汇总（文件相互独立）

适用场景： 更新多个独立的文档文件。

Progress Rendering

进度展示

Native Progress (TaskCreate/TaskUpdate)

原生进度跟踪（TaskCreate/TaskUpdate）

Use TaskCreate with

activeForm

for live UI spinners during execution:

javascript

// Create tasks for each agent's work
TaskCreate({ subject: "Search auth patterns", activeForm: "Searching auth patterns" })
TaskCreate({ subject: "Search DB schema", activeForm: "Searching DB schema" })
TaskCreate({ subject: "Search API endpoints", activeForm: "Searching API endpoints" })

// Track status transitions
TaskUpdate({ taskId: "1", status: "in_progress" })  // → shows spinner
TaskUpdate({ taskId: "1", status: "completed" })     // → shows checkmark

执行时使用带

activeForm

参数的TaskCreate显示实时UI加载图标：

javascript

// 为每个Agent的工作创建任务
TaskCreate({ subject: "Search auth patterns", activeForm: "Searching auth patterns" })
TaskCreate({ subject: "Search DB schema", activeForm: "Searching DB schema" })
TaskCreate({ subject: "Search API endpoints", activeForm: "Searching API endpoints" })

// 跟踪状态转换
TaskUpdate({ taskId: "1", status: "in_progress" })  // → 显示加载图标
TaskUpdate({ taskId: "1", status: "completed" })     // → 显示对勾

Task Dependencies (Sequential Phases)

任务依赖（顺序阶段）

Use

addBlockedBy

to sequence phases:

javascript

// Phase 1: Architecture (runs first)
TaskCreate({ subject: "Design architecture" })  // → task #1

// Phase 2: Implementation (blocked by Phase 1)
TaskCreate({ subject: "Build backend" })   // → task #2
TaskCreate({ subject: "Build frontend" })  // → task #3
TaskUpdate({ taskId: "2", addBlockedBy: ["1"] })
TaskUpdate({ taskId: "3", addBlockedBy: ["1"] })

// Phase 3: Review (blocked by Phase 2)
TaskCreate({ subject: "Code review" })  // → task #4
TaskUpdate({ taskId: "4", addBlockedBy: ["2", "3"] })

使用

addBlockedBy

参数编排阶段顺序：

javascript

// 阶段1：架构设计（先执行）
TaskCreate({ subject: "Design architecture" })  // → 任务#1

// 阶段2：实现（依赖阶段1完成）
TaskCreate({ subject: "Build backend" })   // → 任务#2
TaskCreate({ subject: "Build frontend" })  // → 任务#3
TaskUpdate({ taskId: "2", addBlockedBy: ["1"] })
TaskUpdate({ taskId: "3", addBlockedBy: ["1"] })

// 阶段3：评审（依赖阶段2完成）
TaskCreate({ subject: "Code review" })  // → 任务#4
TaskUpdate({ taskId: "4", addBlockedBy: ["2", "3"] })

Summary Rendering (Markdown)

结果汇总展示（Markdown）

After all agents complete, render a markdown summary:

undefined

所有Agent完成后，渲染Markdown格式的汇总：

undefined

Research Complete: 3/3 agents finished

研究完成：3/3 Agent已结束

Agent	Scope	Findings	Time
Auth search	src/auth/	12 files, JWT + session	8s
DB search	src/db/	8 tables, RLS policies	5s
API search	src/api/	15 endpoints, REST	6s

Agent	范围	发现	耗时
Auth search	src/auth/	12个文件，JWT + session	8s
DB search	src/db/	8张表，RLS策略	5s
API search	src/api/	15个端点，REST	6s

Key Insights

关键洞察

[Synthesized finding 1]
[Synthesized finding 2]

---

[汇总发现1]
[汇总发现2]

---

Team Coordination (Native Agent Teams API)

团队协作（原生Agent团队API）

For complex multi-agent work, use the native Teams API:

javascript

// Create a team with shared task list
TeamCreate({ team_name: "research-sprint" })

// Spawn teammates into the team
Task({ subagent_type: "Explore", team_name: "research-sprint", name: "searcher-1" })
Task({ subagent_type: "Explore", team_name: "research-sprint", name: "searcher-2" })

// Teammates coordinate via shared TaskList
// Send messages between teammates
SendMessage({ type: "message", recipient: "searcher-1", content: "Focus on auth/" })

// Shutdown when done
SendMessage({ type: "shutdown_request", recipient: "searcher-1" })

对于复杂的多Agent工作，使用原生团队API：

javascript

// 创建带共享任务列表的团队
TeamCreate({ team_name: "research-sprint" })

// 在团队中启动子Agent
Task({ subagent_type: "Explore", team_name: "research-sprint", name: "searcher-1" })
Task({ subagent_type: "Explore", team_name: "research-sprint", name: "searcher-2" })

// 子Agent通过共享TaskList协作
// 在子Agent间发送消息
SendMessage({ type: "message", recipient: "searcher-1", content: "Focus on auth/" })

// 完成后关闭团队
SendMessage({ type: "shutdown_request", recipient: "searcher-1" })

Prompt Templates

提示词模板

Research Spawn

研究启动模板

Search the codebase for [PATTERN]. Look in [SCOPE].
Report: file paths, line numbers, and a 2-sentence summary of each match.
Do NOT modify any files.

Search the codebase for [PATTERN]. Look in [SCOPE].
Report: file paths, line numbers, and a 2-sentence summary of each match.
Do NOT modify any files.

Build Spawn

构建启动模板

Implement [COMPONENT] in [FILE_PATH].
Requirements: [SPEC]
Follow existing patterns in [EXAMPLE_FILE].
Write code only — do not run tests.

Implement [COMPONENT] in [FILE_PATH].
Requirements: [SPEC]
Follow existing patterns in [EXAMPLE_FILE].
Write code only — do not run tests.

Review Spawn

评审启动模板

Review [FILE_PATH] for [CONCERN: security|performance|consistency].
Report only HIGH confidence issues.
Format: file:line — issue — suggestion

Review [FILE_PATH] for [CONCERN: security|performance|consistency].
Report only HIGH confidence issues.
Format: file:line — issue — suggestion

Constraints

约束条件

Max 5-7 parallel agents — beyond this, context window fills up
No conflicting file edits — if agents might edit the same file, use agent-teams instead
Fan-in is manual — you (team lead) synthesize results from background agents
Background agents can't see each other — design tasks to be independently completable

Deep dive: See

reference/task-tool-guide.md

reference/team-patterns.md

reference/prompt-templates.md

最多5-7个并行Agent — 超过此数量会导致上下文窗口耗尽
禁止文件编辑冲突 — 如果Agent可能编辑同一文件，请改用agent-teams
结果汇总需手动完成 — 由你（团队负责人）汇总后台Agent的结果
后台Agent无法互相感知 — 任务设计需确保各Agent可独立完成工作

深入参考： 详见

reference/task-tool-guide.md

reference/team-patterns.md

reference/prompt-templates.md