@xgent-ai/skills 0.1.0 → 0.4.0

package/skills/swarm/SKILL.md

@@ -0,0 +1,263 @@
+---
+name: swarm
+description: '组建并指挥一队并行工作的 agent 完成一个任务：选机制（后台 subagent / 动态 workflow / agent team）、选团队模式、设计角色与提示词、确认后编排执行与收尾。凡用户说「创建团队 / 组建团队 / 开个团队做这个 / 团队作战 / 蜂群 / swarm / 多 agent 协作 / parallel agents / spawn teammates / 并行跑几个 agent / 产品团队 / 需求评审团队 / 审计团队 / 一起 review 这个 PR」，或执行 `/swarm`，或交来一个明显需要多人分工的任务（跨层新功能、全库审计、难查的 bug、技术选型辩论、大规模重构迁移、需求设计与澄清评审）时，务必使用本 skill——即使用户没说「团队」两个字。也用于判断「这个任务到底要不要开团队」：很多时候后台 subagent 或动态 workflow 更便宜更快，本 skill 会先做这个判断。'
+---
+
+# 蜂群 Swarm
+
+把一个任务拆给一队并行工作的 agent，由你（lead）负责选人、派活、协调、把关、合成。
+
+> **路径约定**：`references/` 相对于本 `SKILL.md` 所在目录。团队模式文件按需只读命中的那一个，不要全读。
+
+## 核心流程
+
+```
+选机制 → 环境预检 → 分析任务 → 选团队模式（只读一个文件）→ 设计角色与提示词
+      → 用户确认 → 派发执行 → 监控协调 → 收尾汇报
+```
+
+---
+
+## 第 0 步：先选机制，别默认开团队
+
+开团队是最贵的一种做法：每个 teammate 都是独立会话，各自烧 token，还要你逐轮协调。先问三个问题：
+
+1. **worker 之间需要互相说话吗？**（交换发现、互相质疑、协商接口）
+2. **需要一份共享任务清单来传递依赖吗？**
+3. **需要多轮往返吗？**（草稿 → 评审 → 修订 → 再评审）
+
+三个都是「否」→ 不要开团队，用下面更轻的机制。
+
+| 机制 | 什么时候用 | 代价 |
+|------|-----------|------|
+| **自己干** | 一两步能完成、改动集中在少数文件 | 最低 |
+| **后台 subagent**（`Agent` 工具，默认后台运行） | 侧任务会用搜索结果/日志/文件内容淹掉主对话，且 worker 之间不需要沟通 | 低 |
+| **动态 workflow**（提示词里写 `ultracode`，或 `/workflow-authoring` 存成 `.claude/workflows/*.js` 后用 `/<名字>` 跑） | 同一套动作要跑几十到几百次：全库审计、500 文件迁移、多来源交叉验证、从多个角度起草同一份方案 | 中，但脚本一次写好可复用 |
+| **`/batch` skill** | 一个大改动要拆成 5–30 份、各自在独立 worktree 里做完并各开一个 PR | 中 |
+| **agent team**（本 skill 主场景） | 多个较长任务、worker 之间要交换发现、要共享任务清单、要多轮往返 | 高 |
+| **agent view**（`claude agents`）/ 手动 worktree | 你自己想分别盯着几个独立会话 | 你的注意力 |
+
+机制的能力边界、脚本原语、字段清单见 `references/agent-types.md` §1。
+
+---
+
+## 第 1 步：环境预检（只在决定开团队时做）
+
+开团队前把这四件事核实清楚，否则后面每一步都会踩空：
+
+1. **agent teams 是实验特性，默认关闭。** 需要 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`（写进 `settings.json` 的 `env`，或 shell 导出）。没开就如实告诉用户怎么开，不要假装团队已经起来了。
+2. **共享任务清单不一定存在。** `TaskCreate` / `TaskGet` / `TaskList` / `TaskUpdate` 是按模型注入的：Claude 3.x、Opus 4–4.7、Sonnet 4–4.6、Haiku 4.5 默认有；在 Opus 4.8 / Sonnet 5 / Fable 5 这类较新模型上，即使设了 `CLAUDE_CODE_ENABLE_TASKS=1` 也可能拿不到。**没有清单时流程要能降级**：由你（lead）自己维护一张任务表，依赖关系写进每条派发消息里，用 `SendMessage` 指名推进。
+3. **展示模式。** in-process（默认，teammate 显示在输入框下方的 agent 面板，↑↓ 选中 + Enter 查看）或 split panes（需要 tmux 或 iTerm2，`teammateMode` 设置 / `--teammate-mode`）。VS Code 集成终端、Windows Terminal、Ghostty 不支持 split panes。
+4. **没有 `TeamCreate` / `TeamDelete`**（Claude Code 2.1.178 起移除）。一个会话只有一个隐式团队，名字形如 `session-xxxxxxxx`，资源自动清理。同理：一个会话不能开第二个团队，teammate 也不能再开自己的团队。
+
+---
+
+## 第 2 步：分析任务
+
+| 维度 | 评估内容 |
+|------|---------|
+| 任务类型 | 功能开发 / 需求设计 / 代码审计 / Bug 调试 / 技术选型 / 重构迁移 |
+| 产出物 | 代码 / 文档 / 结论决议 —— 决定文件范围怎么切、谁能写 |
+| 可并行度 | 哪些子任务能同时进行，哪些必须串行 |
+| 文件冲突 | 不同角色是否会写同一个文件（团队不会自动给 teammate 开 worktree） |
+| 依赖关系 | 谁必须等谁；契约类产物要不要先冻结 |
+| 用户介入点 | 哪些决定必须用户拍板（teammate 问不到用户，只能回传给你） |
+| 复杂度 | 决定团队规模（2–8 人） |
+
+---
+
+## 第 3 步：选团队模式 —— 只读命中的那一个文件
+
+| 团队 | 什么时候选 | 参考文件 |
+|------|-----------|---------|
+| **功能开发** | 新功能、跨层变更（前端+后端+测试） | `references/teams/feature-dev.md` |
+| **产品团队** | 需求设计、需求澄清、需求评审、验收标准体检、需求拆分 | `references/teams/product.md` |
+| **代码审计** | PR review、安全/性能/正确性审计、上线前体检 | `references/teams/code-audit.md` |
+| **调试竞争** | 难查的 bug、根因分析、多个假设要同时验证 | `references/teams/debug-race.md` |
+| **研究辩论** | 技术选型、架构决策、方案评估、要不要自研 | `references/teams/research-debate.md` |
+| **重构迁移** | 大规模重构、框架/版本迁移、模块拆分 | `references/teams/refactor-migration.md` |
+
+- **只读命中的那一个文件。** 六个文件全读会把无关的角色表和规则塞进上下文，干扰判断。
+- **混合场景**：以主模式为骨架，需要时再去另一个文件借一两个角色，仍然只读用到的那一个。
+- **都不像**：按 `references/agent-types.md` §9 的原则自行设计，不要硬套。
+
+---
+
+## 第 4 步：设计角色与提示词
+
+每个 teammate 定六件事：
+
+| 要素 | 说明 |
+|------|------|
+| 角色名 | 短、可被 `SendMessage` 指名，如 `product-designer`、`security-reviewer` |
+| 载体 | 内置 subagent 类型（`general-purpose` / `Explore` / `Plan`），或 `.claude/agents/<name>.md` 自定义定义 |
+| 模型 + effort | 按任务难度选；`Explore` 的模型有特殊上限，见 `references/agent-types.md` §5 |
+| 权限模式 | 只读分析用 `default`/`plan`，写代码用 `acceptEdits`；**spawn 时不能给单个 teammate 指定**，spawn 后可改 |
+| 文件范围 | 明确可写目录 + 明确禁区；同一文件只能有一个写手 |
+| 输出契约 | 结构化报告的字段、判定档位、引用格式（文件:行号） |
+
+**提示词模板**：
+
+```
+角色：{role}
+职责：{responsibilities}
+
+上下文：
+- 你的上下文里没有主对话历史，下面是你需要的全部背景：{background}
+- 任务来源：{task_description}
+
+工作范围：
+- 只修改：{allowed_dirs}
+- 不要触碰：{excluded_dirs}（另有 teammate 负责）
+
+输出要求：
+- {output_format}
+- 结论要有判定档位，不要只写感想
+
+协作规则：
+- 你拿不到 AskUserQuestion，需要用户拍板的问题回传给 lead，不要替用户决定
+- 发现跨模块影响时，用 SendMessage 通知 {related_teammate}
+- 完成任务后把结论作为最后一条消息发出（lead 会通过 idle 通知收到它）
+
+完成标准：
+- {completion_criteria}
+```
+
+写法要点、字段清单、subagent 拿不到哪些工具（以及这对提示词意味着什么）见 `references/agent-types.md` §3、§7、§9。
+
+---
+
+## 第 5 步：展示计划并确认
+
+```markdown
+## 团队计划
+
+**任务**：{task_description}
+**机制**：agent team / 后台 subagent / 动态 workflow（说明为什么选它）
+**模式**：{pattern_name}
+**团队规模**：{count} 人
+
+### 角色分配
+
+| # | 角色 | 载体 | 模型/effort | 职责概要 |
+|---|------|------|------------|---------|
+| 1 | {name} | {type} | {model} | {summary} |
+
+### 任务与依赖
+
+| ID | 任务 | 负责人 | 依赖 |
+|----|------|--------|------|
+| 1 | {task} | {owner} | - |
+| 2 | {task} | {owner} | 等 1 |
+
+### 文件分工（避免冲突）
+
+| 角色 | 可写范围 | 禁区 |
+|------|---------|------|
+| {name} | {dirs} | {excluded} |
+
+### 需要你拍板的点
+- {open_questions}
+
+确认此计划？(Y / 修改建议)
+```
+
+用 `AskUserQuestion` 让用户确认或提修改意见。**不要跳过这一步**：团队一旦跑起来，纠错成本远高于事前改计划。
+
+### 计划就在对话里给，别额外落一堆文件
+
+角色提示词作为计划的一部分写出来就行。只有用户明确说要复用某个角色（「把这个审查者存下来」）时，才写 `.claude/agents/<name>.md`。
+
+原因不是磁盘，是轮次：每多写一个文件就多一轮工具调用，而每一轮都会把已有上下文重新读一遍。实测一次团队规划里，缓存重读占总 token 的 85% 以上，而读 skill 本身只占约 1%。把七份产物合成一份，比精简任何参考文档都省。
+
+---
+
+## 第 6 步：派发执行
+
+### 6.1 启动 teammate
+
+用 `Agent` 工具，带上 `name` 参数（这就是 teammate 的名字，后续 `SendMessage` 用它指名）：
+
+```
+Agent → subagent_type: "{agent_type}"     # 内置类型，或 .claude/agents 里的自定义名
+        name: "{role_name}"
+        prompt: "{designed_prompt}"
+        model: "{model}"                  # 可选；不填则按 subagent 模型顺序解析
+```
+
+注意：
+- 没有 `team_name` 参数（团队是隐式的），也不能在 spawn 时传权限模式。
+- agent teams 打开时，**任何被你指名的 subagent 都会以 teammate 形式启动**，包括你在别的场景里习惯性指名的那些。
+- 想用 `.claude/agents/*.md` 的定义当 teammate：`tools`、`model` 和正文会生效，`skills` **不会**应用到 teammate，`mcpServers` 只在 split-pane 模式生效。需要 teammate 用某个 skill 时，在提示词里把要点写进去。
+
+### 6.2 建任务清单（如果有 Task 工具）
+
+`TaskCreate` 建全部任务 → `TaskUpdate` 设依赖与 owner。没有 Task 工具就走降级路径（第 1 步第 2 条）。
+
+### 6.3 派活
+
+有清单：`TaskUpdate` 设 owner。没清单：`SendMessage` 指名派发，消息里写清任务、依赖、产出要求。
+
+---
+
+## 第 7 步：监控与协调
+
+1. **不要轮询。** teammate 空闲时，它的最终答复会通过 idle 通知自动送到你这里。
+2. **面板里消失的 idle 行是被隐藏，不是被停止**（整块面板空闲 30 秒后隐藏；超过 3 个空闲会折叠成 `N idle agents`）。按名字发一条消息就能唤回。
+3. **teammate 遇错可能直接停下**而不是自己恢复。进它的输出看一眼（in-process：面板选中 + Enter；split：点对应 pane），然后追加指令，或换一个 teammate 接手。
+4. **你自己也可能提前收工**——任务没全完就宣布结束。用户说「继续」时接着推进。
+5. **任务状态会滞后**：teammate 有时忘记标 completed，卡住下游。核实工作实际已完成就手动改状态，或提醒它。
+6. **解决文件冲突**：多个 teammate 要写同一文件时，排定顺序或重新切分范围；共享文件（配置、类型定义、路由表）由你统一改。
+7. **质量把关**：审查产出，不合格就退回要求修改，别把半成品合进结果。
+
+---
+
+## 第 8 步：收尾
+
+1. 按名字向每个 teammate 发 shutdown 请求。它会先做完当前的请求或工具调用，也可能拒绝关闭（比如认为活没干完）——等它确认，别硬来。
+2. 团队资源自动清理，**不要去找 `TeamDelete`**。
+3. 提醒用户：`/resume` 和 `/rewind` 不会恢复 in-process teammate。恢复会话后如果 lead 去给已经不存在的 teammate 发消息，需要重新 spawn。
+4. 向用户汇报：最终成果、每个角色的关键结论、未决问题、以及需要用户拍板的事项。
+
+---
+
+## 关键规则
+
+### 避免文件冲突（最重要）
+
+不同 teammate 不能同时改同一文件。agent team **不会**自动给 teammate 开 worktree。
+
+- 按目录/模块切分文件范围，写进每个提示词
+- 共享文件由 lead 统一修改
+- 确实需要隔离时用 `isolation: worktree`（自定义 subagent 定义）或手动 worktree
+- 跨模块变更走消息协调，不要各改各的
+
+### 控制团队规模
+
+宁少勿多。每加一个 teammate 都加一份 token 消耗和协调成本。官方建议 3–5 人起步。
+
+| 任务复杂度 | 建议人数 |
+|-----------|---------|
+| 简单（单模块） | 2–3 |
+| 中等（跨模块） | 3–4 |
+| 复杂（跨层） | 4–6 |
+| 大型（架构级） | 5–8 |
+
+### lead 只协调，不实现
+
+发现自己在写代码/写文档时停下来，把它派给 teammate。你的上下文要留给协调、把关和合成。
+
+### 提示词要具体
+
+teammate 的上下文里没有主对话历史，模糊的提示词等于让它自己猜。必须包含：具体文件路径、明确输出格式、清晰完成标准、以及「不确定就回传 lead」。
+
+### 用户是唯一信息源
+
+teammate 拿不到 `AskUserQuestion`。需要用户拍板的问题一律回传给你，由你**批量、一次性**问完，再把答复广播给相关 teammate。
+
+---
+
+## 参考资源
+
+- **`references/agent-types.md`** — 并行机制对照、内置 subagent 类型、自定义 subagent 字段、teammate 运行事实、模型与 effort、权限模式、工具限制、隔离方案、提示词写法
+- **`references/teams/*.md`** — 六种团队模式，各一个文件，按需只读命中的那一个

package/skills/swarm/evals/evals.json

@@ -0,0 +1,55 @@
+{
+  "skill_name": "swarm",
+  "evals": [
+    {
+      "id": 0,
+      "prompt": "我们门户要加一个「需求变更审批」的功能，现在只有一句话想法：产品提的变更要走审批才能进开发。帮我组个团队把这条需求梳理清楚——要能拿去评审会的那种，别写成一堆没法验收的空话。仓库在 ~/code/portal，需求文档放 docs/prd/ 下面。",
+      "expected_output": "识别为产品团队模式，只加载 references/teams/product.md；给出两段式机制建议（并行只读评审 + 需要多轮往返时用 team）；PRD 单一写手；澄清问题批量汇聚到 lead 一次问用户；评审输出带判定档位；与 prd/test-plan 等 skill 的联动写进提示词；团队规模 3-5 人；停在用户确认这一步",
+      "files": [],
+      "expectations": [
+        "选择「产品团队」模式（需求设计/澄清/评审），而不是套用功能开发或代码审计模式",
+        "只加载命中的团队文件 references/teams/product.md，没有把其余 5 个 teams/*.md 全读一遍",
+        "明确 PRD 只有一个写手，评审者不得直接修改 PRD（改由 designer 或 lead 合入）",
+        "澄清问题汇聚到 lead 后批量、一次性问用户，而不是各角色各自提问",
+        "评审输出要求判定档位（通过/有条件通过/打回）+ 引用原文 + 建议改法，而非只给感想",
+        "含技术可行性评审角色，且要求引用真实文件路径/接口名（代码事实优先于产品想象）",
+        "团队规模在 3-7 人之间",
+        "停在等待用户确认这一步，没有假装团队已经执行完毕",
+        "不把已废弃的 TeamCreate / TeamDelete / team_name 当作执行步骤使用（作为「已移除」的说明出现是正确行为）"
+      ]
+    },
+    {
+      "id": 1,
+      "prompt": "帮我审计一下这个仓库的安全问题，src 下面三百多个文件都要过一遍，重点看鉴权和注入。组个团队并行搞快点。",
+      "expected_output": "识别出「同一套检查 × 300 文件」是动态 workflow / batch 的主场，而不是 agent team；对用户「组个团队」的说法给出有理由的反建议；审查者只读；统一严重度口径；每条问题带 文件:行号；报告含「未覆盖范围」；审计与修复分阶段",
+      "files": [],
+      "expectations": [
+        "指出「同一套检查 × 300 文件」更适合动态 workflow（ultracode）或 /batch，而不是 agent team",
+        "对用户「组个团队」的要求给出有理由的反建议，而不是直接照办开团队",
+        "审查角色为只读（Explore，或显式禁掉 Write/Edit/Bash）",
+        "统一严重度口径（如 P0-P3）并在派发时定死",
+        "要求每条问题带 文件:行号 + 为什么是问题 + 建议改法",
+        "要求报告包含「未覆盖范围」一栏",
+        "审计与修复分成两个阶段，不让审查者顺手改代码",
+        "不把已废弃的 TeamCreate / TeamDelete / team_name 当作执行步骤使用（作为「已移除」的说明出现是正确行为）"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "创建一个团队做这个跨层功能：前端加一个设备列表页，后端加 /api/devices 接口和分页，再补上测试。前端在 src/pages、src/components，后端在 src/api、src/services，测试在 tests/。",
+      "expected_output": "功能开发团队；使用当前的 Agent 工具 + name 启动 teammate（不出现 TeamCreate / TeamDelete / team_name）；提示预检 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS 与任务清单可能不可用的降级；契约先冻结再并行；共享文件归 lead；测试工程师提前进场；lead 不写代码",
+      "files": [],
+      "expectations": [
+        "用 Agent 工具 + name 参数启动 teammate，而不是旧的 Task → subagent_type/team_name 形式",
+        "不把已废弃的 TeamCreate / TeamDelete / team_name 当作执行步骤使用（作为「已移除」的说明出现是正确行为）",
+        "预检 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS 是否已开启（agent teams 默认关闭）",
+        "提到共享任务清单（TaskCreate 等）可能不可用，并给出降级路径",
+        "接口契约先冻结，然后前后端才并行实现",
+        "文件分工使用用户给出的真实目录，且共享文件（类型/路由/配置）归 lead 统一改",
+        "测试角色提前进场（契约冻结后就写用例骨架），不等实现全部完成",
+        "不在 spawn 参数里传权限模式（mode），因为 teammate 的权限模式不能在 spawn 时按人指定",
+        "停在等待用户确认这一步，没有假装团队已经执行完毕"
+      ]
+    }
+  ]
+}

package/skills/swarm/references/agent-types.md

@@ -0,0 +1,260 @@
+# Agent 能力与角色选型
+
+> 本文件描述的是 Claude Code 当前（2.1.x 系列）的多 agent 能力。带版本号的条目表示该行为是某个版本引入或改变的，升级后请复核。
+>
+> **目录**
+> - §1 五种并行机制怎么选
+> - §2 内置 subagent 类型
+> - §3 自定义 subagent（`.claude/agents/*.md`）
+> - §4 teammate 的运行事实
+> - §5 模型与 effort
+> - §6 权限模式与继承规则
+> - §7 subagent 拿不到的工具，以及它对提示词的影响
+> - §8 隔离：worktree 与文件冲突
+> - §9 角色提示词写法
+> - §10 成本与缓存
+> - §11 来源
+
+---
+
+## §1 五种并行机制怎么选
+
+| 机制 | 谁在协调 | worker 之间能说话吗 | 适合 |
+|------|---------|------------------|------|
+| **subagent**（`Agent` 工具） | 你（主对话），派完收结果 | 不能，只把结果交回派出它的对话 | 侧任务、一次性调研、并行评审 |
+| **agent view**（`claude agents`） | 你自己，一个个看 | 不能（可用跨会话消息传递发现） | 你手上有几个独立任务想分别托管 |
+| **agent team** | lead（主会话）规划、派活、监督 | 能，`SendMessage` 直连；有 Task 工具时还共享任务清单 | 多个较长任务、需要来回协商 |
+| **动态 workflow** | 一段 JS 脚本 | 不能直接说话，但脚本能把 A 的结论喂给 B | 同一套动作跑几十上百次、要交叉验证 |
+| **projects**（claude.ai/code） | 云端 | 各自独立 thread | 跨天跨周的长期工作，机器关机也要跑 |
+
+两个打包好的用法，不用自己搭：
+
+- **`/batch` skill** — 把一个大改动拆成 5–30 个 worktree 隔离的 subagent，每个各开一个 PR。
+- **`/workflow-authoring` skill** — 帮你把一段编排写成脚本存到 `.claude/workflows/<name>.js`，之后用 `/<name>` 直接跑。
+
+### 动态 workflow 的原语与硬限制
+
+脚本体是纯 JavaScript，不能 `import()`，也不能自己读写文件或跑命令——**文件操作和命令都由 agent 做，脚本只负责编排**。
+
+| 原语 | 作用 |
+|------|------|
+| `agent(prompt, opts)` | 跑一个 subagent，返回它的结果 |
+| `parallel([...])` / `pipeline([...])` | 扇出并行 / 串成流水线 |
+| `phase(name, fn)` | 分阶段，`/workflows` 里能看到进度 |
+| `log(msg)` | 打进度 |
+| `args` | 调用时传入的参数 |
+
+限制：默认最多 16 个 agent 并发（环境变量可调到 256）；单次运行最多 1000 个 agent；单个 `parallel()`/`pipeline()` 最多 4096 项。运行中**不能问用户**——只有权限提示和用量等待会让它暂停。需要中途签字确认的，把每一段拆成独立的 workflow。
+
+触发方式：提示词里写 `ultracode`，或 `/effort ultracode`，或直接说「用 workflow 做」。`/workflows` 查看运行中的和已完成的。
+
+**判断口诀**：worker 之间要说话、要共享任务清单、要多轮往返 → agent team；同一套动作重复很多次、结果要互相校验 → workflow；只是不想让侧任务污染主对话 → 后台 subagent。
+
+---
+
+## §2 内置 subagent 类型
+
+通过 `Agent` 工具的 `subagent_type` 指定。省略 `subagent_type` 时，如果会话里没有 `general-purpose` 可回退，会报 `subagent_type is required`。
+
+| 类型 | 工具 | 模型 | 特点与坑 |
+|------|------|------|---------|
+| **`general-purpose`** | subagent 可用的全部工具 | `CLAUDE_CODE_SUBAGENT_MODEL`，否则跟随主对话 | 需要既探索又改动的多步任务。实现类角色的默认载体 |
+| **`Explore`** | 只读；`Write`/`Edit` 被拒 | 跟随主对话，但在 Claude API 上**封顶到 Opus** | 搜索/理解代码库。调用时要指定彻底程度：**quick**（定点查找）/ **medium**（均衡）/ **very thorough**（全面） |
+| **`Plan`** | 只读 | 跟随主对话 | plan mode 下收集上下文、出方案的研究 agent。做架构分析可以，但它不是为「常驻架构师」设计的 |
+| **`claude`** | subagent 可用的全部工具 | 按模型顺序解析 | 兜底类型，任务不匹配任何专门 agent 时用 |
+| `statusline-setup` / `claude-code-guide` | — | Sonnet / Haiku | Claude Code 自用，别拿来当团队角色 |
+
+> **`Explore` 和 `Plan` 都不加载 CLAUDE.md，也不看父会话的 git status**（为了让研究快而便宜）。其他内置类型和自定义 subagent 两者都加载，除非定义里写了 `omitClaudeMd`。所以：凡是依赖仓库约定的角色（架构师、需要遵守目录规范的实现者），别用 `Explore`/`Plan`，或者把必要的约定直接抄进提示词。
+
+两点实用推论：
+
+1. **想让探索跑在便宜模型上**：在项目或用户目录定义一个同名 `Explore` 的自定义 subagent，它会覆盖内置版本并保留自己的 `model` 字段（例如 `model: haiku`）。
+2. **想禁掉某个内置类型**：加 deny 规则；`CLAUDE_CODE_DISABLE_BUILTIN_AGENTS=1` 则全部禁用，只留你自己的。
+
+---
+
+## §3 自定义 subagent（`.claude/agents/*.md`）
+
+项目级放 `.claude/agents/`，用户级放 `~/.claude/agents/`，插件也可以带。文件是「YAML frontmatter + Markdown 正文（系统提示词）」。
+
+**什么时候值得落盘成文件**，而不是每次在提示词里现写：
+
+- 这个角色会被反复用（例如每次审计都要的 `security-reviewer`）
+- 需要限制工具集（只读审查者不给 `Write`/`Edit`/`Bash`）
+- 需要固定模型、effort 或权限模式
+- 需要 worktree 隔离
+
+frontmatter 字段（按需选用，不必写全）：
+
+| 字段 | 作用 |
+|------|------|
+| `name` | 调用名，`subagent_type` 用它 |
+| `description` | 什么时候该派它——写清楚才会被自动选中 |
+| `tools` / `disallowedTools` | 白名单 / 黑名单。带参数的条目如 `Bash(git push *)` 会**移除整个工具**，不是只移除该参数形式 |
+| `model` | `sonnet` / `opus` / `haiku` / `fable` / 完整 ID（如 `claude-opus-5`）/ `inherit` |
+| `permissionMode` | 见 §6。`manual` 是 `default` 的别名（需 v2.1.200+）。插件 subagent 忽略此字段 |
+| `maxTurns` | 到上限就停，输出会标注被截断 |
+| `effort` | 推理强度，见 §5 |
+| `skills` | 预加载的 skill。**注意：对 teammate 不生效**（见 §4） |
+| `mcpServers` | 只给它连的 MCP server。**只在 split-pane teammate 下生效** |
+| `hooks` | 这个 subagent 专属的 hook |
+| `memory` | 跨调用记忆 |
+| `background` | 是否后台跑。**in-process teammate 派出的 subagent 不能后台**，会报错 |
+| `isolation` | `worktree` → 给它单独的 git worktree |
+| `omitClaudeMd` | 不注入 CLAUDE.md |
+| `color` / `initialPrompt` / `experimental.cacheTtl` | 外观与缓存微调 |
+
+校验：`claude plugin validate .claude/agents`（v2.1.233+）能查出 frontmatter 解析不了的文件。
+
+`/agents` 自 v2.1.198 起**不再打开交互式创建面板**，只会提示文件位置。要建就直接让 Claude 写文件，或自己写。
+
+---
+
+## §4 teammate 的运行事实
+
+这些是 agent team 与「一次性 subagent」的关键差别，设计角色时必须知道：
+
+| 事实 | 影响 |
+|------|------|
+| 团队是**隐式**的，一个会话一个，名字形如 `session-xxxxxxxx` | 没有 `team_name` 参数可传，也没有 `TeamCreate` / `TeamDelete`（2.1.178 起移除），资源自动清理 |
+| teammate 用 `Agent` 工具 + `name` 参数启动 | `name` 就是后续 `SendMessage` 的收件地址 |
+| **lead 固定**，主会话终生是 lead | 不能把某个 teammate 提升为 lead，也不能移交 |
+| **不能嵌套**：teammate 不能再开 teammate | 需要两层分工时，第二层只能是它自己派的一次性 subagent |
+| 权限模式在 spawn 时**不能按人指定** | teammate 继承 lead 的模式（`dontAsk` 除外）；spawn 之后可以单独改某个人的 |
+| 用 `.claude/agents/*.md` 当 teammate 时：`tools`、`model`、正文生效；**`skills` 不生效**；`mcpServers` 只在 split-pane 生效 | 需要 teammate 遵循某个 skill 的做法时，把要点直接写进提示词 |
+| **idle 通知**会把 teammate 的最终答复自动送给 lead | 不要轮询；等通知 |
+| in-process 面板里空闲的行会在整块面板空闲 30 秒后隐藏；超过 3 个空闲折叠成 `N idle agents` | 消失 ≠ 停止。按名字发消息即可唤回 |
+| shutdown 是**请求**，teammate 可以拒绝 | 它会先做完当前请求或工具调用；别指望立刻消失 |
+| `/resume`、`/rewind` **不恢复** in-process teammate | 恢复会话后 lead 可能去给已不存在的 teammate 发消息——重新 spawn |
+| 任务状态会滞后，teammate 也可能遇错就停 | lead 要主动核实、手动改状态、追加指令或换人 |
+| split panes 需要 tmux 或 iTerm2（`it2` CLI + Python API） | VS Code 集成终端、Windows Terminal、Ghostty 不支持；`teammateMode` 设置或 `--teammate-mode` 切换 |
+| 打开 agent teams 后，**任何被 lead 指名的 subagent 都会变成 teammate** | 想恢复成普通 subagent：把 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` 设为 `0`（用户级 settings 的 `0` 会覆盖 shell 导出；项目/本地/`--settings`/托管设置的优先级更高）。改完不用重启会话 |
+| teammate 的权限请求会冒泡到 lead | spawn 前先在 permission 设置里预批常用操作，否则会被打断很多次 |
+| 相关 hook：`TeammateIdle`、`TaskCreated`、`TaskCompleted` | `TaskCompleted` 退出码 2 可以拦下完成并把反馈送回 teammate |
+
+**共享任务清单不一定有**：`TaskCreate` / `TaskGet` / `TaskList` / `TaskUpdate` 按模型注入——Claude 3.x、Opus 4–4.7、Sonnet 4–4.6、Haiku 4.5 默认有；其他模型（含 Opus 4.8、Sonnet 5、Fable 5）默认没有，且实测即使设 `CLAUDE_CODE_ENABLE_TASKS=1` 也可能仍被模型门控掉（见 anthropics/claude-code#76076）。**设计流程时按「可能没有清单」来做**：lead 自己记一张任务表，依赖写进派发消息，用 `SendMessage` 推进。`TodoWrite` 在有 Task 工具的会话里默认被禁用，设 `CLAUDE_CODE_ENABLE_TASKS=0` 可换回它。
+
+---
+
+## §5 模型与 effort
+
+### 模型别名
+
+| 别名 | 解析为 |
+|------|-------|
+| `default` | 特殊值：清除覆盖，回到账号的运行时默认模型。它本身不是别名 |
+| `best` | Fable 可用时用 Fable，否则等同 `opus` |
+| `fable` | 当前 provider 的 Fable 模型，用于最难、最长时任务 |
+| `opus` | 最新 Opus，复杂推理 |
+| `sonnet` | 最新 Sonnet，日常编码 |
+| `haiku` | 最快的 Haiku，简单检索与格式化 |
+| `inherit` | 与主对话同模型（仅自定义 subagent 的 `model` 字段支持） |
+
+也可以写完整 ID，如 `claude-opus-5`、`claude-sonnet-5`；第三方部署（Bedrock / Vertex / Foundry）写各自的 ARN、部署名或版本名。
+
+### subagent / teammate 的模型解析顺序
+
+1. 定义里的 `model` 字段，或 `Agent` 调用时传的 `model`
+2. `CLAUDE_CODE_SUBAGENT_MODEL`（`_FORCE` 变体会压过第 1 条；只设 `_FORCE` 时内置 `Explore` 仍保留自己的 Opus 封顶）
+3. 主对话的模型
+
+### effort（推理强度）
+
+`low` / `medium` / `high` / `xhigh` / `max`，可用档位随模型而变：Fable 5.1 与 5、Opus 5、Sonnet 5、Opus 4.8、Opus 4.7 支持到 `max`；Opus 4.6 与 Sonnet 4.6 只到 `high` + `max`。设了模型不支持的档位会回落到它支持的最高档。`/effort` 命令改当前会话，自定义 subagent 用 `effort` 字段。
+
+### 给角色配模型的经验
+
+| 角色性质 | 模型 | 理由 |
+|---------|------|------|
+| lead、架构师、裁决者、需求设计 | `opus` 或 `fable` + `high` | 判断错了整队白跑 |
+| 实现者、写文档者 | `sonnet` | 性价比 |
+| 只读审查、检索、格式化 | `haiku`，或自定义 `Explore` 覆盖成 `haiku` | 便宜；内置 `Explore` 会被封顶到 Opus，想省钱必须自己定义 |
+| 交叉验证里的「第二意见」 | 与被验证者**不同**的模型 | 同模型同偏差，验不出东西 |
+
+---
+
+## §6 权限模式与继承规则
+
+| 模式 | 行为 |
+|------|------|
+| `default`（别名 `manual`） | 手动模式，逐个提示 |
+| `acceptEdits` | 自动接受文件编辑与常见文件操作 |
+| `auto` | 由分类器判断工具调用是否放行；Pro/Max/Team 计划上主对话的默认起点 |
+| `dontAsk` | 不提示（teammate 不继承这个模式） |
+| `bypassPermissions` | 跳过权限确认 |
+| `plan` | 只读规划，方案批准后才动手 |
+
+继承规则（**很容易踩**）：
+
+- 主对话处于 `bypassPermissions`、`acceptEdits` 或 `auto` 时，subagent **强制跟随主对话的模式**，你在 `permissionMode` 里写的值被忽略。`auto` 模式下分类器还会在 subagent 交付前复审它的工作和最终报告。
+- 主对话处于 `default`、`dontAsk` 或 `plan` 时，subagent 用你写的 `permissionMode`——**但 `bypassPermissions` 除外**，声明了也会保持主对话的模式（该例外需 v2.1.267+）。
+- teammate 继承 lead 的模式，`dontAsk` 除外；不能在 spawn 时按人指定，spawn 后可以单独改。
+
+**实践建议**：想给只读审查者真正上锁，别只靠 `permissionMode`——用 `tools` / `disallowedTools` 把 `Write`、`Edit`、`Bash` 拿掉，或在 permission 设置里加 deny 规则。工具集是硬的，模式会被主对话覆盖。
+
+---
+
+## §7 subagent 拿不到的工具，以及它对提示词的影响
+
+每个 subagent 都会被摘掉这些工具：
+
+`AskUserQuestion`、`EnterPlanMode`、`ExitPlanMode`（除非它的 `permissionMode` 就是 `plan`）、`Workflow`、`TaskOutput`、`ScheduleWakeup`、`WaitForMcpServers`、`EndConversation`，以及在深度上限处的 `Agent`。后台运行的 subagent 还会再被裁掉一批内置工具。fork（`/subtask`）跳过这两层过滤，拿到主对话的完整工具集。
+
+另外：主对话在 macOS / Linux / WSL 上默认没有 `Glob` 和 `Grep`，但 subagent 可以被单独授予它们。
+
+**这些主会话状态永远不会传给非 fork 的 subagent**：output style（它跑自己的系统提示词）、auto memory、内置 agent 的预加载 skill。CLAUDE.md 里的规则默认会到（`Explore`/`Plan` 除外），但如果某条规则对这个角色至关重要——比如「忽略 `vendor/` 目录」「所有接口必须过 `xxx` 中间件」——**在派发提示词里重述一遍**，别赌它读到了。
+
+**这四条推论直接决定提示词怎么写**：
+
+1. **teammate 问不到用户。** 任何需要用户拍板的事，它只能回传给 lead。提示词里要明说：「不确定就回传 lead，不要替用户决定」——否则它会自己脑补一个答案继续跑，这是团队里最难发现的错误来源。
+2. **teammate 不能开自己的 workflow，也不能在 in-process 下派后台 subagent。** 需要扇出的活儿由 lead 或脚本来扇。
+3. **它看不到主对话历史。** 背景、约束、验收口径都得写进提示词，别指望它「知道我们刚才说的」。
+4. **结果通过最后一条消息交付。** 让它把结论、证据、未决问题写成结构化的收尾消息，而不是散在中途的碎碎念里。
+
+---
+
+## §8 隔离：worktree 与文件冲突
+
+- **agent team 不会自动给 teammate 开 worktree。** 这是团队里最常见的翻车点：两个人同时改一个文件，后写的覆盖前写的。
+- 三种解法，按代价从低到高：
+  1. **切分文件范围**——每个角色有明确的可写目录和禁区，写进提示词。共享文件（配置、类型定义、路由表、锁文件）由 lead 统一改。
+  2. **`isolation: worktree`**——自定义 subagent 定义里加这个字段，它就在自己的 git worktree 里干活。
+  3. **手动 worktree / `/batch`**——你自己开多个 checkout，或用 `/batch` 让 5–30 个 subagent 各自在 worktree 里做完并各开一个 PR。
+- 契约类产物（接口定义、数据模型、事件格式）要**先冻结再并行**：由一个角色定稿，其他人只读引用，要改走 lead。
+
+---
+
+## §9 角色提示词写法
+
+teammate 的上下文是空的，提示词就是它的全部世界。五条要点，每条都对应一种典型翻车：
+
+1. **开头定角色与立场。** 「你是安全审查者，只报安全问题，不做风格评价」——不写立场，它会什么都管一点、什么都不深。
+2. **给足背景。** 任务来源、相关模块、已有约束、验收口径。它读不到主对话，也（`Explore`）读不到 CLAUDE.md。
+3. **划死文件范围。** 可写目录 + 禁区 + 谁负责禁区。这是防冲突的唯一有效手段。
+4. **规定输出契约。** 固定字段、判定档位、引用格式（`文件:行号`）。要「结论 + 证据 + 建议改法」，不要「感觉这里可以再考虑一下」——无法执行的评审意见等于没有。
+5. **写清协作与收尾。** 什么时候 `SendMessage` 通知谁；不确定就回传 lead；完成后把结构化结论作为最后一条消息发出。
+
+模板见 `SKILL.md` 第 4 步。
+
+**一个反复出现的反模式**：把「审查者」也给了写权限，理由是「顺手改一下更高效」。结果是几个审查者同时改同一批文件，冲突掩盖了真正的问题。审查者就该只读——发现问题、报告、由实现者统一改。
+
+---
+
+## §10 成本与缓存
+
+- 每个 teammate 是独立会话，**各自烧 token**。官方建议 3–5 人起步；本 skill 的规模表按任务复杂度给到 2–8 人。
+- in-process teammate 的请求落在主对话的缓存 TTL 桶之外，默认只缓存 5 分钟（订阅计划也一样）；把设置项 `subagentPromptCacheTtl` 设为 `1h` 可延长。注意 API 对 1 小时缓存写入按更高费率计费。
+- 动态 workflow 的成本随 agent 数线性涨（上限 1000 个/次）；先用小样本（比如 10 个文件）验证脚本逻辑，再全量跑。
+- 便宜的活儿别用贵模型：检索、格式化、定点查找给 `haiku`；判断、裁决、设计给 `opus`/`fable`。
+
+---
+
+## §11 来源
+
+- Claude Code 文档 · Orchestrate teams of Claude Code sessions — `https://code.claude.com/docs/en/agent-teams`
+- Claude Code 文档 · Create custom subagents — `https://code.claude.com/docs/en/sub-agents`
+- Claude Code 文档 · Orchestrate subagents at scale with dynamic workflows — `https://code.claude.com/docs/en/workflows`
+- Claude Code 文档 · Agents and parallel work — `https://code.claude.com/docs/en/agents`
+- Claude Code 文档 · Tools reference（含 Task tool availability） — `https://code.claude.com/docs/en/tools-reference`
+- Claude Code 文档 · Model configuration（模型别名与 effort 档位） — `https://code.claude.com/docs/en/model-config`
+- anthropics/claude-code#76076 — 较新模型上 Task 工具被门控的实测报告