代理团队

人工智能 社区

技能解读

当前原文的自动摘译,尚未人工审校。

何时使用此技能

在以下情况下使用代理团队 · 在以下情况下使用子代理 · 多个代理需要并行工作 · 任务是连续且相互依赖的 代理之间需要持续通信 · 一项重点任务产生一个结果 后台任务需要进度报告 · 代理输出直接反馈到下一步 复杂的工作流程受益于任务协调 · 简单、有限、隔离的执行

子代理警告:从主线程生成团队

TeamCreate、Agent和相关的并行生成工具可能不会出现在子代理的工具表面中,即使父对话有它们。旨在协调自己团队的子代理可以默默地降级为顺序单线程执行(相同的内容,更长的挂钟),而不会在完成后总结之前显示故障。创作指导:情况·推荐模式

本地团队工具

工具·目的TeamCreate·创建团队和共享任务列表目录TeamDelete·所有工作完成后清理团队SendMessage·发送DM、广播、关闭请求、计划批准TaskOutput·从后台代理获取输出

1. 创建团队

这将创建: ~/.claude/teams/<team-name>/ — 团队配置目录 ~/.claude/tasks/<team-name>/ — 共享任务列表目录

3. 生成队友

使用代理工具通过团队上下文生成每个队友:

流狐档案 运行与权限由流狐静态检查推断,不代表作者声明或实际测试结果。
领域
人工智能
作者声明的智能体
未找到明确声明;不据此推断已兼容或已测试
静态检查
88 / 100 · 启发式扫描,不代表运行安全
运行环境证据
未执行;当前没有隔离运行测试证据
作者 / 版本 / 许可证
@laurigates · 未声明许可证
上下文用量评级
较高消耗
接入复杂程度
需简单配置
是否需要外部接口密钥
不需要
兼容的系统
未声明(默认跨平台)
运行环境要求
未检出明确要求
检测到的文件与系统行为
  • 只读
  • 允许写入 / 修改
  • 命令执行
网络行为
仅限本地
安装命令数
无(仅作为资料)

需要注意: 未声明工具权限范围;实际权限由运行环境决定。

作者说明文件(原文) SKILL.md

# Agent Teams

> **Experimental**: Agent teams require the `--enable-teams` flag and may change between Claude Code versions.

## When to Use This Skill

| Use agent teams when... | Use subagents instead when... |
|------------------------|------------------------------|
| Multiple agents need to work in parallel | Tasks are sequential and interdependent |
| Ongoing communication between agents is needed | One focused task produces one result |
| Background tasks need progress reporting | Agent output feeds directly into next step |
| Complex workflows benefit from task coordination | Simple, bounded, isolated execution |
| Independent changes to the same codebase (with worktrees) | Context sharing is fine and efficient |

## Sub-Agent Caveat: Spawn Teams from the Main Thread

`TeamCreate`, `Agent`, and the related parallel-spawn tools may not be present in a **sub-agent's** tool surface, even if the parent conversation has them. A sub-agent designed to orchestrate its own team can silently degrade to sequential single-thread execution — same content, much longer wall-clock — without surfacing the failure until its post-completion summary.

**Authoring guidance:**

| Situation | Recommended pattern |
|-----------|---------------------|
| Fan-out from the main conversation | Spawn the team / parallel `Agent` calls directly — full tool surface available |
| Sub-agent orchestrating its own team | Avoid by design when possible: split the work so the main thread does the fan-out |
| Sub-agent must orchestrate a team | Detect tool availability up front; report sequential fallback as a first-class outcome |

**Detection contract for coordinating sub-agents:**

Brief the orchestrating sub-agent to verify before dispatching:

```
1. Confirm Agent / TeamCreate are callable. If unavailable (e.g. ToolSearch
   does not surface them, or invocation returns "tool not found"), do NOT
   silently fall back.
2. Report the constraint as the first line of the final summary:
   "Parallel fan-out unavailable in this sandbox; executed sequentially."
3. Continue sequentially with the same input contract — outputs should be
   identical in content, only longer in wall-clock.
```

The wall-clock cost is real: a 5-way fan-out that degrades to sequential takes ~5× longer. Plan top-level orchestration in the main conversation when you can; reserve sub-agent orchestrators for cases where the team's outputs do not need to feed back into the main thread.

> Evidence: a Phase 2 portability-audit dispatch instructed a coordinating sub-agent to spawn 5 parallel auditors via `Agent`; the `Agent` tool was not registered in the sub-agent's sandbox. Output was equivalent but wall-clock was much longer than designed, and the failure surfaced only in the post-completion note.

## Core Concepts

### Team Architecture

```
Lead Agent (orchestrator)
    ├── TeamCreate — creates team + shared task list
    ├── Agent tool — spawns teammate agents
    ├── SendMessage — communicates with teammates
    ├── TaskUpdate — assigns tasks to teammates
    └── Teammates (run in parallel)
            ├── Read team config from ~/.claude/teams/<name>/config.json
            ├── TaskList/TaskUpdate — claim and complete tasks
            └── SendMessage — report back to lead
```

### Native Team Tools

| Tool | Purpose |
|------|---------|
| `TeamCreate` | Create team and shared task list directory |
| `TeamDelete` | Clean up team when all work is complete |
| `SendMessage` | Send DMs, broadcasts, shutdown requests, plan approvals |
| `TaskOutput` | Get output from a background agent |
| `TaskStop` | Stop a running background agent |

## Team Setup Workflow

### 1. Create the Team

```
TeamCreate({
  team_name: "my-project",
  description: "Working on feature X"
})
```

This creates:
- `~/.claude/teams/<team-name>/` — team config directory
- `~/.claude/tasks/<team-name>/` — shared task list directory

### 2. Create Initial Tasks

```
TaskCreate({
  team_name: "my-project",
  title: "Implement security review",
  description: "Audit auth module for vulnerabilities",
  status: "pending"
})
```

### 3. Spawn Teammates

Use the Agent tool to spawn each teammate with the team context:

```
Agent tool with:
  subagent_type: "agents-plugin:security-audit"
  team_name: "my-project"
  name: "security-reviewer"
  prompt: "Join team my-project and work on security review task..."
```

### 4. Assign Tasks

```
TaskUpdate({
  team_name: "my-project",
  task_id: "task-1",
  owner: "security-reviewer",
  status: "in_progress"
})
```

### 5. Receive Results

Teammates send messages automatically — they are delivered to the lead's inbox between turns. No polling needed.

## Task Management

### Task States

| State | Meaning |
|-------|---------|
| `pending` | Not yet started |
| `in_progress` | Assigned and active (one at a time per teammate) |
| `completed` | Finished successfully |
| `blocked` | Waiting on another task |

### Task Priority

Teammates should claim tasks in **ID order** (lowest first) — earlier tasks often set up context for later ones.

### TaskList Usage

Teammates should check `TaskList` after completing each task to find available work:

```
TaskList({ team_name: "my-project" })
→ Returns all tasks with status, owner, and blocked-by info
```

Claim an unassigned task:
```
TaskUpdate({ team_name: "my-project", task_id: "N", owner: "my-name" })
```

## Communication (SendMessage)

### Message Types

| Type | Use When |
|------|----------|
| `message` | Direct message to a specific teammate |
| `broadcast` | Critical team-wide announcement (use sparingly — expensive) |
| `shutdown_request` | Ask a teammate to gracefully exit |
| `shutdown_response` | Approve or reject a shutdown request |
| `plan_approval_response` | Approve or reject a teammate's plan |

### DM Example

```
SendMessage({
  type: "message",
  recipient: "security-reviewer",  // Use NAME, not agent ID
  content: "Please also check the payment module",
  summary: "Adding payment module to scope"
})
```

### Broadcast (use sparingly)

```
SendMessage({
  type: "broadcast",
  content: "Stop all work — critical blocker found in auth module",
  summary: "Critical blocker: halt work"
})
```

Broadcasting sends a separate delivery to every teammate. With N teammates, that's N API round-trips. Reserve for genuine team-wide blockers.

## Teammate Behavior

### Discovering Team Members

Read the team config to find other members:

```
Read ~/.claude/teams/<team-name>/config.json
→ members array with name, agentId, agentType
```

Always use the **name** field (not agentId) for `recipient` in SendMessage.

### Idle State

Teammates go idle after every turn — this is normal. Idle ≠ unavailable. Sending a message to an idle teammate wakes them.

### Key Teammate Rules

- Mark exactly ONE task `in_progress` at a time
- Use `TaskUpdate` (not `SendMessage`) to report task completion
- System sends idle notifications automatically — no need for status JSON messages
- All communication requires `SendMessage` — plain text output is NOT visible to the team lead

## Shutdown Procedures

### Graceful Shutdown (Lead → Teammates)

```
SendMessage({
  type: "shutdown_request",
  recipient: "security-reviewer",
  content: "All tasks complete, wrapping up"
})
```

### Teammate Approves Shutdown

```
SendMessage({
  type: "shutdown_response",
  request_id: "<id from shutdown_request JSON>",
  approve: true
})
```

### Cleanup (Lead)

After all teammates shut down:

```
TeamDelete()
→ Removes ~/.claude/teams/<name>/ and ~/.claude/tasks/<name>/
```

TeamDelete fails if teammates are still active.

## Lead Preflight Checklist

Before drafting the PRP and launching agents, run these checks:

| Check | Command | Why |
|-------|---------|-----|
| Next ADR/PRD/PRP sequence number | `ls docs/blueprint/adrs/ \| sort -V \| tail -1` | Prevents numbering collisions when agents write docs in parallel |
| Filename conflicts | `git ls-files \| grep <filename>` | Agent scope tables can't guard against a stale mental model of the tree |
| Hardware pin budget (embedded) | Read `pin_config.h` or equivalent | Prevents pin assignments overlapping across Phase 1 agents |

A 30-second sweep prevents multi-edit renaming work after agents return.

## Out-of-Scope Discovery Protocol

Include this protocol in every agent's prompt when that agent has an exclusive write scope:

```markdown
### Out-of-scope discovery protocol

If you discover that a file outside your declared write scope needs to change
for your deliverables to work:

1. **STOP immediately.** Do not read, investigate, or edit the out-of-scope file.
2. In your final summary, include a section titled `Out-of-scope dependencies` that lists:
   - The file(s) that need changes
   - What changes are needed (one line each)
   - Which of your deliverables is blocked without those changes
3. Exit. The lead will triage and either expand your scope, reassign to another agent,
   or handle it directly.
```

This prevents the "investigate out of scope → exhaust budget → truncated summary" failure mode.
The lead can then address the dependency before the next phase or assign a follow-up issue.

## Worktree-Isolated Edit/Write Path Resolution

> **Known failure mode (worktree isolation):** Agents launched with
> `isolation: "worktree"` may have `Edit`/`Write` tool calls silently
> resolve relative paths against the **parent repo** rather than the
> agent's worktree, even though `Bash` commands and `git status`
> correctly operate inside the worktree. The agent gets no immediate
> signal that file writes are landing on the wrong branch — commits
> can land on a sibling agent's branch or on the parent repo's
> working tree. Cleanup requires cherry-pick + rebase
> drop-if-upstream after the fact.
>
> Tracking: laurigates/claude-plugins#1091

The bug lives in Claude Code's worktree path-resolution layer (upstream).
Until it is fixed, harden every worktree-isolated agent prompt with the
preamble below and run the post-flight check before merging.

### Recommended agent-prompt preamble

Paste this verbatim at the **top** of any worktree-isolated agent's
prompt — before any other instructions or task description:

```
**First action MUST be:**

  pwd
  git rev-parse --show-toplevel
  ls -la

**All file edits must use absolute paths rooted at your worktree.**
**If `Edit` or `Write` appears to target anything outside your worktree,
stop and report — do not retry.**
```

The three commands give the agent (and the transcript reader) an
unambiguous signal of where it actually is. Absolute paths bypass the
relative-resolution bug entirely. The "stop and report" clause prevents
the recovery-by-retry loop that compounds the damage.

### Lead post-flight check

After agents return, run from the **parent repo** before merging:

```bash
git diff origin/main..HEAD     # parent's intended branch should be clean
git status --porcelain         # no straggler edits in parent worktree
```

If either is non-empty, an agent's `Edit`/`Write` leaked into the parent.
Inspect the diff before any further git operations.

### Recovery pattern

If a stray commit lands on the wrong branch:

1. **Cherry-pick** the commit onto the intended branch:
   `git cherry-pick <stray-sha>`.
2. **Rewrite the wrong branch** to drop the duplicate. Rebase onto the
   correct base with drop-if-upstream so git removes the commit that
   already exists upstream:
   `git rebase --onto <new-base> <old-base> <wrong-branch>` (run with
   `git config rebase.dropOnUpstream true` or use `git rebase -i` and
   delete the duplicate line).
3. **Verify** with `git log --oneline <wrong-branch> ^<intended-branch>`
   that only the wrong-branch's own commits remain.

For the broader concurrency context (shared-clone vs. worktree
coordination), see `.claude/rules/agent-coworker-detection.md`.

## Common Patterns

### Parallel Code Review

```
TeamCreate: "code-review"
Tasks: security-audit, performance-review, correctness-check
Teammates: security-agent, performance-agent, correctness-agent (all parallel)
Lead: collects results, synthesizes findings
```

### Parallel Implementation with Worktrees

```
TeamCreate: "feature-impl"
Tasks: backend-api, frontend-ui, tests
Teammates: each spawned with isolation: "worktree"
Lead: delegates git push (sub-agents must not push independently in sandbox)
```

### Multi-Phase Architecture Refactor

```
Phase 1 (3 parallel):  Framework upgrade + new module scaffolding + ADR draft
Phase 2 (1 serialized): Reactive executor — depends on Phase 1 contracts
Phase 3 (1 serialized): Wire-up + legacy deletion — exclusive main.c owner
Phase 4 (2 parallel):  Host tests + documentation finalization

Key rules:
- One owner per file across ALL phases (exclusive write scope per agent)
- "Agent writes, lead commits" — keep branch coherent between phases
- Phase boundaries = commit points (clean checkpoint semantics)
- Phase 3 deletion runs AFTER Phases 1–2 finalize their contracts
```

Real-world outcome: +1850/−1826 lines, zero file-scope collisions across 6 agents,
tests exposed a bug on first build. See also: the Out-of-Scope Discovery Protocol above —
include it in every focused-scope agent prompt.

### Blocked Task Resolution

If a task is blocked on another, set the `blocked_by` field in TaskCreate. Teammates check TaskList and skip blocked tasks until the blocking task is completed.

## Team Roles

| Role | Behavior | When to Use |
|------|----------|-------------|
| **Lead** | Orchestrates, assigns tasks, receives results | Always — coordinates the team |
| **Teammate** | Parallel execution with messaging | Ongoing collaboration, progress reporting |
| **Subagent** | Focused, isolated, returns single result | Simple bounded tasks, no coordination needed |

## Sandbox Considerations

In web sessions (`CLAUDE_CODE_REMOTE=true`):
- Sub-agents (teammates) may encounter TLS errors on `git push` — delegate all push/PR operations to the lead
- Each teammate runs in its own process context
- Worktree isolation is recommended for independent filesystem changes

## Agentic Optimizations

| Context | Approach |
|---------|----------|
| Quick parallel review | Spawn 2–4 teammates, broadcast task assignments |
| Large codebase split | Assign directory subsets as separate tasks |
| Long-running work | Background teammates, poll via TaskList |
| Minimize API cost | Prefer `message` over `broadcast` |
| Fast shutdown | Send shutdown_request to each teammate, then TeamDelete |

## Quick Reference

### Workflow Checklist

- [ ] `TeamCreate` with team name and description
- [ ] `TaskCreate` for each work unit
- [ ] Spawn teammates via Agent tool with `team_name` and `name`
- [ ] `TaskUpdate` to assign tasks to teammates (or let teammates self-assign)
- [ ] Receive messages automatically; respond via `SendMessage`
- [ ] `SendMessage shutdown_request` to each teammate when done
- [ ] `TeamDelete` after all teammates shut down

### Key Paths

| Path | Contents |
|------|----------|
| `~/.claude/teams/<name>/config.json` | Team members (name, agentId, agentType) |
| `~/.claude/tasks/<name>/` | Shared task list directory |

### Common Mistakes

| Mistake | Correct Approach |
|---------|-----------------|
| Using agentId as recipient | Use `name` field from config.json |
| Sending broadcast for every update | Use `message` for single-recipient comms |
| Polling for messages | Messages delivered automatically — just wait |
| Sending JSON status messages | Use `TaskUpdate` for status, plain text for messages |
| Sub-agent pushes to remote | Delegate push to lead orchestrator |
| TeamDelete before shutdown | Shutdown all teammates first |

## Related Skills and Rules

- `parallel-agent-dispatch` — worktree preflight, scope budgets, and the Return Contract that every teammate must emit on exit. Team dispatches are a superset of plain parallel fan-out; follow both.
- `.claude/rules/agent-development.md` — agent file structure, model selection, worktree isolation
- `.claude/rules/agentic-permissions.md` — granular tool permission patterns
- `.claude/rules/sandbox-guidance.md` — web sandbox constraints and push delegation

讨论

基于 GitHub Discussions。登录 GitHub 即可参与讨论、点赞、订阅更新。