agent-skills 多角色编排模式实战并行扇出、顺序流水线与 Agent Teams 的选型指南【免费下载链接】agent-skillsProduction-grade engineering skills for AI coding agents.项目地址: https://gitcode.com/GitHub_Trending/agentskill/agent-skills本文以 agent-skills 仓库的 references/orchestration-patterns.md 为骨架系统讲解 AI 编码 Agent 编排的 5 种被认可的协作模式、4 种反模式与一套决策流程并结合仓库中真实的角色定义agents/ 目录与斜杠命令commands/ship.toml 等剖析用户即编排者这一核心原则的落地方式。读完你可以掌握为一次多 Agent 协作选对模式直接调用、单角色命令、并行扇出、顺序流水线、研究隔离、在 Claude Code 中正确配置 Subagents 与实验性的 Agent Teams以及避免路由器角色、角色互相调用等常见设计错误。核心规则用户或斜杠命令是编排者该文档开宗明义给出全仓库的编排总纲the user (or a slash command) is the orchestrator. Personas do not invoke other personas.Skills are mandatory hops inside a personas workflow.即用户或斜杠命令才是编排层角色persona之间不允许互相调用技能skill是角色工作流内部必须经过的环节。这条规则在仓库多个入口文件中被反复强化AGENTS.md 的 Orchestration: Personas, Skills, and Commands 一节把仓库划分为三层——Skillsskills/name/SKILL.mdhow带步骤与退出条件的工作流、Personasagents/role.mdwho带视角与输出格式的角色、Slash commandswhen用户可见的入口并明确本仓库唯一认可的多角色编排模式是带合并步骤的并行扇出docs/agents.md 进一步给出三层职责表Skill / Persona / Command并在Rules for personas中规定每个角色文件必须以 Composition 块结尾声明自己的编排位置。可以对照仓库中一个真实角色来验证这条规则。agents/code-reviewer.md 末尾的 Composition 块写着- Invoke directly when: the user asks for a review of a specific change, file, or PR. - Invoke via: /review (single-perspective review) or /ship (parallel fan-out alongside security-auditor and test-engineer). - Do not invoke from another persona. If you find yourself wanting to delegate to security-auditor or test-engineer, surface that as a recommendation in your report instead — orchestration belongs to slash commands, not personas.也就是说角色发现自己想转调另一个角色时正确做法是在报告里建议后续审计把第二次调用的决定权交还给用户或斜杠命令。这正是反模式 B后文详述的第一道防线。五种被认可的编排模式模式 1直接调用无编排单个角色、单一视角、单一产物是默认选项也是最便宜的选项user → code-reviewer → report → user适用条件工作是对单一产物的一种视角审视且能用一句话描述清楚。典型示例Review this PR →code-reviewerFind security issues inauth.ts →security-auditorWhat tests are missing for the checkout flow? →test-engineer成本一次往返one round trip。这是所有编排模式必须对比的基线——任何更复杂的编排都要先回答比直接调用贵多少、换来什么。模式 2单角色斜杠命令用一个斜杠命令把单个角色 项目技能打包省掉用户每次重新解释流程的麻烦/review → code-reviewer (with code-review-and-quality skill) → report适用条件同一个单角色调用以相同的设置反复发生。本仓库中的实例包括/review、/test、/code-simplify以及面向 Web 应用性能审计的/webperf。从源码看这类命令确实只是保存好的提示词commands/review.toml 的正文只做了两件事——调用code-review-and-quality技能、要求按五个轴正确性、可读性、架构、安全、性能输出file:line级发现commands/code-simplify.toml 则是调用code-simplification技能 逐步简化 每步跑测试的固定流程。成本与直接调用相同因为斜杠命令本质上只是一段被保存的 prompt。文档给出一个反信号anti-signal如果斜杠命令的正文大部分内容是决定该调哪个角色删掉它让用户直接调角色。模式 3并行扇出 合并Parallel fan-out with merge多个角色并发处理同一份输入各自产出独立报告最后由主 Agent 的上下文完成一个合并步骤综合成单一决策┌─→ code-reviewer ─┐ /ship → fan out ───┼─→ security-auditor ─┤→ merge → go/no-go rollback └─→ test-engineer ─┘适用条件四条必须同时满足子任务真正独立无共享可变状态、无顺序依赖每个子 Agent 都能从自己独立的上下文窗口中受益合并步骤足够小能留在主上下文里完成墙钟延迟wall-clock latency敏感。仓库实例/ship。commands/ship.toml 是模式 3 的标准实现结构上分三个阶段Phase A — 并行扇出并发派生code-reviewer五轴审查、security-auditorOWASP Top 10、密钥处理、认证授权、依赖 CVE、test-engineer覆盖率与缺口分析三个子 Agent。命令中明确要求把三个子 Agent 工具调用放在同一个 assistant turn 里发出以保证并行执行——顺序调用会让这个命令失去意义Phase B — 主上下文合并由主 Agent而非任何子角色把三份报告综合为 Code Quality / Security / Performance / Accessibility / Infrastructure / Documentation 六个维度的结论Phase C — 决策与回滚输出Ship Decision: GO | NO-GO报告模板含 Blockers、Recommended fixes、Acknowledged risks、Rollback plan触发条件、回滚步骤、恢复时间目标以及三份完整专项报告。规则上/ship还约束三个角色必须并行、角色之间不得互调、任何 GO 决策前必须有回滚计划、任一角色报出 Critical 发现时默认 NO-GO并且给出了跳过扇出的判据——仅当改动不超过 2 个文件、diff 少于 50 行且不涉及 auth/payments/数据访问/配置时才可跳过否则默认扇出。这与文档合并步骤要留在主 Agent的设计完全一致。成本N 个并行子 Agent 上下文 1 轮合并。比直接调用贵但墙钟更快且由于每个子 Agent 只聚焦单一视角报告质量更高。采用前的验证清单原文档原样保留缺一不可所有子 Agent 能否同时运行而不产生顺序问题每个角色产出的是不同类型的发现而不是同一发现的不同角度合并步骤能否装进主 Agent 剩余的上下文用户等待时间是否长到并行真的能被感知任何一项回答否就回退到直接调用或单角色命令模式 2。模式 4顺序流水线 用户驱动的斜杠命令用户按既定顺序运行斜杠命令在命令之间携带上下文或提交历史。没有编排 Agent——用户本人就是编排者user runs: /spec → /plan → /build → /test → /review → /ship适用条件工作流存在依赖每一步需要上一步的产物且步骤之间的人工判断有增值。仓库实例就是整个 DEFINE → PLAN → BUILD → VERIFY → REVIEW → SHIP 生命周期对应命令分别是 commands/spec.toml、commands/planning.toml、commands/test.toml、commands/review.toml、commands/ship.toml。可以推断这条流水线各环节是产物驱动的例如spec.toml要求把规格保存为项目根的SPEC.md并经用户确认planning.toml则要求读取既有 SPEC.md、进入只读 plan 模式、按依赖图垂直切片任务产物落在tasks/plan.md与tasks/todo.md。正是这些落盘产物而非任何隐式记忆充当了步骤之间的上下文载体——这也是用户即编排者能成立的技术前提。成本每步一个子 Agent 上下文编排层零成本因为根本没有编排 Agent。为什么不用 LLM 自动编排整条生命周期文档给出了三条理由(a) LLM 生命周期编排者在步骤间交接时必须做摘要会丢失细微信息(b) 跳过人工检查点无法及早发现方向性错误(c) 每步都要编排者转述 子 Agent 执行两轮token 成本翻倍。模式 5研究隔离上下文保护当任务需要阅读大量不应污染主上下文的材料时派生一个研究型子 Agent只返回摘要main agent → research sub-agent (reads 50 files) → digest → main agent continues适用条件主会话需要保持在下游任务上调查结论远小于它消耗的材料体积主 Agent 在调查之后还需要留有余量来思考决策。典型例子在整个 monorepo 里找出这个废弃 API 的全部调用点、总结这 30 份 ADR 对缓存说了什么。成本一个隔离的子 Agent 上下文。只要替代方案是把几百个文件塞进主上下文它就划算。在 Claude Code 上的落地优先使用内置的Explore子 Agent 而不是自定义研究角色——它跑在 Haiku 上、被拒绝写/编辑工具正是为这个模式设计的。只有当Explore不适用例如需要模型无法自行推断的领域特定系统提示时才定义自定义研究子 Agent。Claude Code 兼容性映射该目录是编排无关harness-agnostic的但多数读者在 Claude Code 上运行。文档给出了各模式到 Claude Code 原语的映射以及平台替我们强制执行规则的位置。角色放在哪里插件的子 Agent 放在插件根目录的agents/下。本仓库是一个插件见 .claude-plugin/plugin.json其中声明commands指向./.claude/commands与./commandsskills指向./skills因此agents/code-reviewer.md、agents/security-auditor.md、agents/test-engineer.md在插件启用时会被自动发现无需任何路径配置。Subagents vs Agent TeamsClaude Code 有两种并行原语。模式 3并行扇出 合并映射到Subagents如果需要彼此通信的队友则使用Agent Teams| | Subagents | Agent Teams | |--|-----------|-------------| | 协调方式 | 主 Agent 扇出子 Agent 只回报结果 | 队友互相发消息、共享任务列表 | | 上下文 | 每个子 Agent 独立上下文窗口 | 每个队友独立上下文窗口 | | 适用场景 | 产出报告的独立任务 | 需要讨论的协作型工作 | | 状态 | 稳定Stable | 实验性Experimental——需要CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS1| | 成本 | 较低 | 较高——每个队友都是独立的 Claude 实例 |文档强调本仓库的角色两种模式都支持作为子 Agent 派生时如/ship它们向主会话汇报作为队友派生时Spawn a teammate using the security-auditor agent type…它们可以直接互相质疑对方的发现。角色定义完全相同变化的只是派生上下文。一个容易踩坑的细节角色 frontmatter 中的skills与mcpServers字段在角色作为子 Agent运行时生效但作为队友运行时被忽略——队友与常规会话一样从项目和用户设置加载技能与 MCP server。若某角色依赖某个特定技能或 MCP server应在会话级配置它保证两种模式下都可用。平台强制执行的规则目录里有两条规则不只是约定——Claude Code 直接强制Subagents cannot spawn other subagents官方文档原话。因此反模式 B角色调角色和反模式 D深层角色树在 Claude Code 上结构上不可能存在No nested teams——队友不能派生自己的 team同样的反模式在 team 层面也被阻断。这意味着你可以放心采用本目录的模式而不必担心贡献者误建反模式——它们会直接加载失败。内置子 Agent在定义自定义子 Agent 之前先确认内置角色是否已覆盖该职责内置角色用途Explore只读代码库搜索与分析。模式 5研究隔离用它。Planplan 模式下的只读研究。general-purpose需要探索 修改的多步骤任务。原则是不要重新定义这些内置角色而是在它们之上叠加专业角色如code-reviewer、security-auditor、test-engineer。插件 Agent 的 frontmatter 限制插件子 Agent不支持hooks、mcpServers、permissionMode三个 frontmatter 字段——它们会被静默忽略。若未来某个角色需要这些字段用户需要把该文件复制到.claude/agents/或~/.claude/agents/。插件 Agent 中确实生效的字段为name、description、tools、disallowedTools、model、maxTurns、skills、memory、background、effort、isolation、color、initialPrompt。可按角色设置model来优化成本例如test-engineer的覆盖率扫描用 Haiku、code-reviewer用 Sonnet、security-auditor用 Opus。并行派生多个子 Agent在 Claude Code 上模式 3 的并行扇出要求在同一个 assistant turn 中发出多个 Agent 工具调用分开在不同 turn 里发会退化为串行执行。commands/ship.toml 已对此显式说明文档要求任何新的编排命令都应写明这一点。实战案例用 Agent Teams 做竞争假设式调试这部分展示何时应该选Agent Teams而不是/ship的子 Agent 扇出。两种模式远看相似——都派生同样三个角色——但价值来源完全不同。场景结账流程偶尔在完成后卡顿约 30 秒大约每 50 次会话出现一次日志没有报错始于上周发布之后。若干互斥且都符合症状的根因假设新支付确认流程中的竞态条件某个认证检查偶发落入一次缓慢的同步网络调用一条随购物车规模扩展的查询缺少索引某个不稳定第三方 APISDK 在超时前静默重试。单个 Agent 会挑第一个看起来合理的理论然后停止深挖而/ship式扇出中每个角色独立汇报、报告互不相见没有任何机制能证伪错误的理论。这正是 Agent Teams 官方文档描述的用例多个独立调查者积极尝试互相证伪时存活下来的理论才更可能是真正的根因。为什么这不是/ship的活| |/ship子 Agent | Agent Teams | |--|--------------------|-------------| | 子 Agent 看到什么 | 同一份 diff不同镜片 | 共享任务列表 彼此的消息 | | 产出 | 三份独立报告 → 一次合并 | 对抗式辩论 → 共识根因 | | 何时选 | 对已知产物要一个结论verdict | 要在假设中找出那个产物artifact |一句话概括/ship是裁决Agent Teams 是调查。一次性配置Agent Teams 是实验特性在~/.claude/settings.json中开启{ env: { CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS: 1 } }要求 Claude Code v2.1.32 或更高版本。本仓库的角色会被自动拾取——无需手写任何 team 配置文件。触发提示词在 lead 会话中以自然语言输入Users report checkout hangs for ~30 seconds intermittently after last weeks release. No errors in logs. Create an agent team to debug this with competing hypotheses. Spawn three teammates using the existing agent types: - code-reviewer — investigate race conditions and blocking calls in the checkout code path - security-auditor — investigate auth checks, session handling, and any synchronous network calls added recently - test-engineer — propose tests that would distinguish between the hypotheses and check coverage gaps in checkout Have them message each other directly to challenge each others theories. Update findings as consensus emerges. Only converge when two teammates agree they can disprove the others.lead 通过引用既有角色名派生三个队友。角色正文会被追加append到每个队友的系统提示末尾叠加在 lead 安装好的 team 协调指令之上上面的触发提示词则成为他们的任务。docs/agents.md 的 Claude Code interop 一节对此有对应说明队友模式下 persona 文本不是替代系统提示而是叠加在 SendMessage、任务列表等协调指令之上的附加指令。运行过程中发生了什么每个队友在独立上下文窗口中从自己的视角探索代码库队友之间直接用message互发发现lead 无需中继共享任务列表随时可见——in-process 模式下按CtrlTsplit 模式下在 tmux 窗格中当code-reviewer发现一处本应顺序执行的Promise.all时它发消息让security-auditor确认认证调用不属于该竞态对方核查后回复——要么确认竞态是真凶要么给出反证test-engineer为占上风的那个理论设计一个聚焦的集成测试团队用它验证后再宣布共识lead 综合收敛后的结论呈现给你。期间你可以用ShiftDown循环切换、直接输入随时打断某个跑偏的调查者。何时清理调查落到根因后告诉 leadClean up the team务必通过 lead 清理而不是通过某个队友官方文档队友缺少清理所需的完整 team 上下文。成本预期三个 Sonnet 队友跑约 10–15 分钟的调查费用明显高于同样三个角色被/ship作为子 Agent 派生。其合理性在于结论质量——在生产环境排障、错误修复代价高昂的场景多花的 token 物有所值常规 PR 审查则仍用/ship。该场景下的反模式不要把这套流程改写成/debug斜杠命令去扇出子 Agent。子 Agent 之间不能发消息——你会丢掉让整个模式成立的对抗式辩论。如果这类工作流反复出现把上面的触发提示词沉淀为一条文档化的 snippet而不是包装成误用子 Agent 的斜杠命令。何时不用 Agent Teams对已知 diff 要一个生产级结论 → 用/ship子 Agent对单一产物要一种专业视角 → 直接调用角色顺序生命周期spec → plan → build→ 用户驱动的斜杠命令模式 4重读取、小摘要的研究 → 内置Explore子 Agent。只有当队友必须互相质疑才能得出正确答案时才动用 Agent Teams。反模式目录A. 路由器角色meta-orchestrator一个职责是决定该调哪个角色的角色/work → router-persona → this needs a review → code-reviewer → router (paraphrases) → user为什么失败纯路由层、零领域价值多出两次转述 → 信息损耗 约 2 倍 token 成本用户本来就知道自己要 review可以直接调/review它只是重复了斜杠命令与AGENTS.md意图映射已经在做的工作。正确做法新增或打磨斜杠命令并在AGENTS.md中记录意图 → 命令映射。B. 角色调用角色例如code-reviewer内部看到 auth 代码就自动调用security-auditor。为什么失败角色被设计为只产单一视角链式调用破坏了这一点调用方传递的摘要会丢掉被调方需要的上下文失败模式成倍增加输出格式听谁的规则听谁的成本对用户隐形。正确做法调用方角色在报告中建议做后续审计由用户或斜杠命令执行第二遍。这一点在 agents/code-reviewer.md 的 Composition 块中已作为硬性规则写出在 Claude Code 上该模式还会被平台直接阻断子 Agent 不能派生子 Agent。C. 替你转述的顺序编排者一个 Agent 代替用户依次调用/spec、/plan、/build。为什么失败丢失能捕捉方向性错误的人工检查点每次交接都在做上下文摘要长流水线累积漂移每步编排者轮次 子 Agent 轮次使 token 成本翻倍在最需要判断力的节点剥夺了用户的主导权。正确做法保持用户为编排者在README.md中记录推荐顺序由用户自己依次调用。D. 深层角色树/ship调pre-ship-coordinator后者调quality-coordinator后者再调code-reviewer。为什么失败每一层都增加延迟与 token 却不产生决策价值调试变成多层排查叶节点角色在多次摘要后丢失上下文。正确做法编排深度最多为 1斜杠命令 → 角色合并在主 Agent 中进行。决策流程为新编排工作流选型考虑任何新的编排工作流时走一遍下面这棵决策树原文档 Decision flow 原样保留Is the work one perspective on one artifact? ├── Yes → Direct invocation. Stop. └── No → Will the same composition repeat? ├── No → Direct invocation, ad hoc. Stop. └── Yes → Are sub-tasks independent? ├── No → Sequential slash commands run by user (Pattern 4). └── Yes → Parallel fan-out with merge (Pattern 3). Validate against the checklist above. If any check fails → fall back to single-persona command (Pattern 2).docs/agents.md 中另有一棵等价的决策矩阵把第三问细化为子任务是否独立无共享可变状态、无顺序依赖并直接映射到/ship并行扇出或/spec → /plan → /build → /test → /review顺序命令。两棵树可以互为交叉验证先问单一视角再问会重复吗最后问子任务独立吗。何时向该目录新增模式该文档对自身演进设了四道门槛——只有全部满足后才允许新增条目你在真实工作中至少用过两次该模式你能指出仓库中一个具体产物来演示它你能解释为什么现有模式不适用你能描述它的反模式影子人们会错误地建成什么样子。文档的理由一针见血过早进入目录的条目会变成没人遵循的愿景文档aspirational documentation。这条元规则本身值得任何想维护多 Agent 实践的团队借鉴——模式目录应当是经验沉淀而不是设计先行。小结三层职责 深度上限 1回到仓库源码层面这套编排体系的落地形态可以概括为Skill 层skills/*/SKILL.md带步骤与退出条件的工作流被角色或命令在内部强制调用Persona 层agents/*.md如 agents/code-reviewer.md、agents/security-auditor.md、agents/test-engineer.md、agents/web-performance-auditor.md单一视角 单一输出格式文件末尾必有 Composition 块Command 层commands/*.toml如 commands/ship.toml唯一的合法编排点其中只有/ship是多角色编排并行扇出 合并其余均为模式 2式单角色包装。配合 Claude Code 的平台约束子 Agent 不能派生子 Agent、team 不可嵌套该体系把深度最多 1 层、合并留在主上下文、用户保留全部检查点从约定变成了不可违背的结构。对于要在自己的项目中引入类似多 Agent 工作流或维护本仓库插件当前版本见 plugin.json0.6.8的开发者这份目录的价值正在于此它不仅告诉你有哪些模式可用更告诉你何时停下——单一视角就直接调用会重复才写命令独立才允许并行需要对抗才启动 Team。【免费下载链接】agent-skillsProduction-grade engineering skills for AI coding agents.项目地址: https://gitcode.com/GitHub_Trending/agentskill/agent-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考