orchestrating-swarms

用途

该技能用于在 Claude Code 中编排多智能体集群（swarm），核心依赖 Claude Code 的 TeammateTool 与 Task 系统。当需要协调多个智能体共同完成一项工作时，可使用本技能建立团队、分配任务并管理智能体之间的通信。

核心架构

一个集群由以下部分组成：

Leader（你）：创建团队、生成工作者、协调工作。
Teammates（被生成的智能体）：执行任务并回报结果。
Task List：带依赖关系的共享工作队列。
Inboxes：用于智能体间消息传递的 JSON 文件。

文件结构：

~/.claude/teams/{team-name}/
├── config.json              # Team metadata and member list
└── inboxes/
    ├── team-lead.json       # Leader's inbox
    ├── worker-1.json        # Worker 1's inbox
    └── worker-2.json        # Worker 2's inbox

~/.claude/tasks/{team-name}/
├── 1.json                   # Task #1
├── 2.json                   # Task #2
└── 3.json                   # Task #3

团队配置结构示例：

{
  "name": "my-project",
  "description": "Working on feature X",
  "leadAgentId": "team-lead@my-project",
  "createdAt": 1706000000000,
  "members": [
    {
      "agentId": "team-lead@my-project",
      "name": "team-lead",
      "agentType": "team-lead",
      "color": "#4A90D9",
      "joinedAt": 1706000000000,
      "backendType": "in-process"
    },
    {
      "agentId": "worker-1@my-project",
      "name": "worker-1",
      "agentType": "Explore",
      "model": "haiku",
      "prompt": "Analyze the codebase structure...",
      "color": "#D94A4A",
      "planModeRequired": false,
      "joinedAt": 1706000001000,
      "tmuxPaneId": "in-process",
      "cwd": "/Users/me/project",
      "backendType": "in-process"
    }
  ]
}

两种生成智能体的方式

方式一：Task 工具（子智能体）

用于短时、聚焦并返回结果的工作：

Task({
  subagent_type: "Explore",
  description: "Find auth files",
  prompt: "Find all authentication-related files in this codebase",
  model: "haiku"  // Optional: haiku, sonnet, opus
})

特点：同步运行（阻塞至完成）或通过 run_in_background: true 异步运行；结果直接返回给你；无需团队归属。适用于搜索、分析、聚焦研究。权限模式：除非需要特定模式（如 mode: "plan"），否则省略 mode 参数。传入 mode: "auto" 会覆盖用户配置的权限设置（例如 bypassPermissions）。省略它则应用用户自己的 defaultMode。

方式二：Task 工具 + team_name + name（队友）

用于生成持久队友：

// First create a team
Teammate({ operation: "spawnTeam", team_name: "my-project" })

// Then spawn a teammate into that team
Task({
  team_name: "my-project",        // Required: which team to join
  name: "security-reviewer",      // Required: teammate's name
  subagent_type: "security-sentinel",
  prompt: "Review all authentication code for vulnerabilities. Send findings to team-lead via Teammate write.",
  run_in_background: true         // Teammates usually run in background
})

特点：加入团队并出现在 config.json 中；通过收件箱消息通信；可从共享任务列表认领任务；持续存在直到被关闭。适用于并行工作、持续协作、流水线阶段。

关键区别

方面	Task（子智能体）	Task + team_name + name（队友）
生命周期	直到任务完成	直到请求关闭
通信	返回值	收件箱消息
任务访问	无	共享任务列表
团队归属	否	是
协调	一次性	持续

内置智能体类型

无需插件即可使用：

Bash：仅 Bash 工具，模型继承父级。适用于 Git 操作、命令执行、系统任务。
Explore：所有只读工具（无 Edit、Write、NotebookEdit、Task），模型为 Haiku（优化速度）。适用于代码库探索、文件搜索、代码理解。彻底程度级别："quick"、"medium"、"very thorough"。
Plan：所有只读工具，模型继承父级。适用于架构规划、实现策略。
general-purpose：所有工具（*），模型继承父级。适用于多步骤任务、研究加行动组合。
claude-code-guide：只读工具 + WebFetch + WebSearch。适用于关于 Claude Code、Agent SDK、Anthropic API 的问题。
statusline-setup：仅 Read、Edit，模型为 Sonnet。适用于配置 Claude Code 状态栏。

插件智能体类型

来自 compound-engineering 插件（示例）：

审查智能体包括：agent-native-reviewer、architecture-strategist、code-simplicity-reviewer、data-integrity-guardian、data-migration-expert、deployment-verification-agent、dhh-rails-reviewer、julik-frontend-races-reviewer、kieran-python-reviewer、kieran-rails-reviewer、kieran-typescript-reviewer、pattern-recognition-specialist、performance-oracle、security-sentinel。

研究智能体包括：best-practices-researcher、framework-docs-researcher、git-history-analyzer、learnings-researcher、repo-research-analyst。

设计智能体：figma-design-sync。

工作流智能体：bug-reproduction-validator。

TeammateTool 操作

spawnTeam：创建团队，生成 config.json 与 tasks 目录，你成为团队 Leader。
discoverTeams：列出可加入的团队。
requestJoin：请求加入团队。
approveJoin（仅 Leader）：批准加入请求。
rejectJoin（仅 Leader）：拒绝加入请求。
write：向单个队友发送消息。注意：队友的文本输出对团队不可见，必须使用 write 通信。
broadcast：向所有队友发送消息。警告：广播开销大，会为 N 个队友发送 N 条独立消息，优先使用 write。
requestShutdown（仅 Leader）：请求队友退出。
approveShutdown（仅队友）：接受关闭请求，发送确认并终止自身进程。
rejectShutdown（仅队友）：拒绝关闭请求。
approvePlan（仅 Leader）：批准队友的计划。
rejectPlan（仅 Leader）：带反馈拒绝计划。
cleanup：移除团队资源。若队友仍活跃会失败，需先 requestShutdown。

任务系统集成

TaskCreate：创建工作任务，可设置 subject、description、activeForm。
TaskList：查看所有任务及其状态、所有者、阻塞关系。
TaskGet：获取任务详情。
TaskUpdate：更新任务状态，可认领任务（设置 owner）、开始工作（status: in_progress）、标记完成（status: completed）、设置依赖（addBlockedBy）。

任务依赖：当阻塞任务完成时，被阻塞任务自动解除阻塞。

消息格式

智能体之间发送 JSON 对象，可以是文本或结构化消息（如 shutdown_request、idle_notification、join_request、plan_approval_request 等），存储在收件箱文件中。

适用场景

需要并行处理的多任务工作，如同时进行代码审查、研究、测试。
持续协作场景，多个智能体长期配合完成复杂功能。
流水线式工作，任务之间存在依赖关系，需按阶段推进。
需要专门智能体分工的场景，如安全审查、性能分析、架构评审。

限制

广播消息开销较大，应优先使用定向 write。
cleanup 在队友仍活跃时会失败，必须先请求关闭。
队友的文本输出对团队不可见，必须通过 write 通信。
关于环境变量、生成后端（in-process、tmux、iterm2）与错误处理的详细内容，资料中仅提及章节标题，具体细节暂未提供。