<!-- title: 多Agent编排Skill四路线横评拆解 -->

# 把SKILL.md当编译产物：多Agent编排Skill四路线横评

## 概述

本期是工作流自动化系列的第五轮，聚焦所有Agent框架都在讲、但Skills生态里反而最稀缺的方向：**多Agent协作编排**。在 SkillsMP 收录的 2,806,826 份 SKILL.md 里，DevOps 分类有 216,041 个、Debugging 分类有 337,389 个——单文件提示词Skill早已红海；但 GitHub 全站以 "claude skills multi-agent SKILL.md" 检索仓库，按星标排序只有 **11 个结果**。原因不难理解：编排类Skill要写的不是提示词，而是循环、并行、分支、断点——这恰是 Markdown 最不擅长的东西。本期拆解生态里出现的四条答案：把 YAML **编译**成 SKILL.md 的 agent-runbook（深度拆解对象）、用纯协议**约定**波次编排的 coordinator-mode、按模型特长**路由**任务的 ai-research-skills 多AI委派家族，以及作为参照系的 superpowers 编排层。

## 评测对比表

| Skill | 功能完整度 (25%) | 设计质量 (25%) | 实战效果 (20%) | 上手难度 (15%) | 社区活跃度 (15%) | 加权总分 |
|---|---|---|---|---|---|---|
| superpowers 编排层 | ★★★★★ | ★★★★★ | ★★★★☆ (4.5) | ★★★★ | ★★★★★ | **4.8** |
| ai-research-skills 多AI委派家族 | ★★★★ | ★★★★ | ★★★★ | ★★★☆ (3.5) | ★★★★ | **3.9** |
| agent-runbook | ★★★★ | ★★★★★ | ★★★☆ (3.5) | ★★★ | ★★ | **3.7** |
| claude-power-skills 之 coordinator-mode | ★★★☆ (3.5) | ★★★★ | ★★★☆ (3.5) | ★★★★☆ (4.5) | ★★ | **3.6** |

> 评分依据各仓库 README 与 SKILL.md 原文（抓取日 2026-08-30），实战效果主要依据作者文档自述与机制完整度推断，未经独立实测。

## 一个数字反差：280万 vs 11

先把赛道全景铺开。GitHub 上 "claude skills multi-agent SKILL.md" 的仓库检索共 11 个结果，按星标排列依次是：ai-research-skills（230★，科研流程）、MoneyAtlas（54★，金融分析）、agent-runbook（17★，YAML 编译器）、Genesis-Mind（16★，自述“认知操作系统”）、Tlamatini（16★，自托管助手）、claude-power-skills（4★）、dotnet-48-master-architect-skill（3★，为 .NET 4.8 定义的 6 子Agent编排器）、cc-harness-skills（1★）、scarab（0★，自述 "SKILL.md-native, tool-agnostic" 的通用编排框架）、health-research-council（0★）。

这个名单本身就是一篇生态观察：**多数项目把“多Agent”当作卖点前缀，真正给出可验证控制流机制的只有少数**。scarab 和 Genesis-Mind 这类“框架感”很强的项目连一个可查的实战案例都还没长出来；而 agent-runbook 选择了最不性感的路——先做一个编译器。

```mermaid
mindmap
  root((多Agent编排<br/>四条技术路线))
    编译器路线
      agent-runbook
      YAML 编译为 SKILL.md
      契约闭环 + 断点续跑
    协议路线
      coordinator-mode
      纯 SKILL.md 协议文本
      波次分解 + 冲突检测
    路由路线
      research-hub-multi-ai
      机械活给Codex 长文给Gemini
      协调文件交接
    方法论路线
      superpowers 编排层
      每任务新鲜子Agent
      双阶段评审 + 进度台账
```

## 深度拆解：agent-runbook，让 SKILL.md 变成编译产物

**仓库**：[KnoxOps/agent-runbook](https://github.com/KnoxOps/agent-runbook)，Python 3.10+，Apache 2.0，17 星，7 月 15 日仍有提交。一句话定位（取自仓库自述）："Contract-based multi-agent skill framework — compile YAML runbooks into Claude Code / Codex SKILL.md with loop, parallel, and checkpoint support"。

### 核心理念：Loop Engineering

README 开篇这段定义值得逐字读：

> "Loop engineering is replacing yourself as the one who prompts the agent. You design a system that finds work, dispatches agents, checks results, and decides what comes next — then you let that system run."

翻译成工程语言：你不再扮演“给Agent派提示词的人”，而是设计一个自己会找活、派活、验活、决定下一步的系统。每份 runbook 定义一个循环，编译器产出 SKILL.md，Agent 负责执行——**作者身份从提示词写手变成了编译器用户**。

### 逐段拆解：一份 runbook 的三个关键设计

官方示例 `examples/restart-nginx/runbook.yaml` 的骨架：

```yaml
name: restart-nginx
description: SSH into a server, restart Nginx, and verify it's back up

input_params:
  - name: host
    type: string
    required: true

steps:
  - id: restart
    type: agent
    prompt: SSH into {host} and run systemctl restart nginx
    output:
      - file: restart_result.json
        schema: schemas/restart.schema.json

  - id: verify
    type: agent
    prompt: curl http://{host}/health and check the status code
    input:
      - schema: schemas/restart.schema.json
        from_step: restart
        file: restart_result.json
    output:
      - file: verify_result.json
        schema: schemas/verify.schema.json
    depends_on: [restart]
```

**第一，类型化输入（input_params）**。`host` 声明为 required string。对比传统 SKILL.md 把参数埋进自然语言（“用户会提供一台主机名”），YAML 声明让参数缺失在编译期就暴露。

**第二，输出契约（output + JSON Schema）**。每步产出不是“Agent 觉得该返回什么”，而是必须过 Schema 校验的文件。`restart` 步骤必须写出符合 `restart.schema.json` 的 `restart_result.json`。

**第三，显式数据流（from_step）**。`verify` 的输入不从对话上下文里“猜”，而是声明读 `restart` 步骤写的那个文件——LLM 上下文污染的传播链在这里被物理切断。

### 编译期契约闭环：错误死在 build time

`python3 -m agent_runbook generate <runbook.yaml> -o <dir>` 执行 Parse → Validate → Compose 三段流水线，其中 Validate 阶段的**契约闭环检查**是整个框架的灵魂：每个 `input.from_step` 引用的步骤必须存在、每个 Schema 引用必须可解析、整个依赖 DAG 必须无环。这意味着多Agent编排里最常见的三类错误（引用不存在的上游、格式错乱的交接、循环依赖）在烧掉 token 之前就被拦截——这是所有纯提示词编排方案做不到的。

```mermaid
flowchart TB
    A["runbook.yaml"] --> B["Parse 解析"]
    B --> C["Validate 校验"]
    C --> D["Compose 组装"]
    D --> E["SKILL.md + checkpoint 脚本"]
    C -. 契约闭环检查 .-> C1["from_step 引用存在"]
    C -.-> C2["Schema 引用可解析"]
    C -.-> C3["DAG 无环"]
    E --> F{"Step 类型路由"}
    F -->|inline| G["当前Agent执行"]
    F -->|agent| H["独立子Agent"]
    F -->|parallel| I["并发多实例"]
    F -->|loop| J["迭代至目标达成"]
    F -->|branch| K["条件分支"]
    F -->|script| L["Shell / Python"]
    J --> M["checkpoint 断点"]
    M -. 崩溃恢复 .-> N["读断点 跳过已完成步骤"]
```

### 八种 Step 类型：控制流全集

| 类型 | 作用 | 关键配置 |
|---|---|---|
| `inline` | 当前Agent直接执行，用于编排步骤 | — |
| `agent` | 派发独立子Agent，可指定提示词文件 | `prompt_file: prompts/xxx.agent.md` |
| `script` | 执行 Shell/Python，可兼作断点 | `command` / `checkpoint: scripts/xxx.py` |
| `parallel` | 并发运行多个 agent 步骤 | `parallel.enabled`、`max_instances`、`item_key` |
| `branch` | 按步骤输出条件分支 | `condition` 字段 |
| `loop` | 迭代执行 body 直到目标达成或达上限 | `goal`、`max_iterations`、`body` |
| `checkpoint` | 写进度断点文件，支持暂停续跑 | — |
| `quality_check` | 自动生成质量门，派发 @supervisor | `blocking: true`、`rules: [...]` |

两处细节最能体现设计功力。其一是 `quality_check`：规则在 YAML 里声明（如 "output.json schema compliance"、"result count > 0"），框架自动生成一个派发 @supervisor 的质量门步骤，且可设为阻塞式——**质量门成了编译产物的一部分，而不是提示词里的一句叮嘱**。其二是 `examples/fix-loop/` 这个官方演示：迭代跑 pytest → 识别失败用例 → 逐文件修源码 → 循环直到测试全绿，全部由 `loop` 步骤类型加级联依赖解析驱动，是“循环工程”的最小闭环。

### "Files Over Context"：一张对垒表

README 里这张表是全文最有传播力的段落，它把两条技术路线的分歧钉在了墙上：

| | LLM 上下文 | agent-runbook（文件） |
|---|---|---|
| 上下文窗口 | 有限、会被污染 | 无限、每步干净 |
| 崩溃恢复 | 从头再来 | 读断点、跳过已完成项 |
| 并行Agent | 无法共享状态 | 读同一份输入文件 |
| 调试 | 会话结束即丢失 | 文件持久化、可检查 |

值得注意的是，这个立场与 superpowers 的文件交接机制（下文）完全一致——**“状态放文件、不放上下文”正在成为头部编排类Skill的公理**。

### 短板

17 星、个人维护、"Active development — API may change" 的自述说明它非常早期；YAML + JSON Schema 的学习成本对提示词一代的 SKILL.md 作者不友好；编译产物是“死”的，改控制流必须回 YAML 重编，失去了 Markdown 直接可编辑的轻便。适合愿意用工程方法对待 Agent 工作流的团队，不适合想五分钟上手的新手。生态上它已长出第一个下游：同作者体系内的 open-devops-skills（僵尸资源扫描、成本优化、K8s 排障等 DevOps Skill），用同一套 runbook 机制构建。

## 横评：另外三条路线

### claude-power-skills 之 coordinator-mode：协议路线

[irfad7/claude-power-skills](https://github.com/irfad7/claude-power-skills)，20 个 Skill 的套装，MIT，作者 Irfad Imtiaz（My Legal Academy 技术总监、Ranql 联合创始人兼 CTO），7 月 24 日有更新。coordinator-mode 的官方描述是："Decomposes complex tasks, plans execution waves with dependency ordering, dispatches parallel subagents, merges results with conflict detection, runs quality gates"——关键词是 **waves（波次）**：任务先分解，按依赖排成可并行的波次逐波派发，合并时做冲突检测，最后过质量门。同套装的 batch-mode 补充了批量操作的“强制 dry-run + skip/retry/abort 异常处理 + 结构化报告”。整套哲学自述非常精准："They're protocols, not prompts"——每个 Skill 是带决策点和质量门的多步骤协议。弱点同样清晰：协议靠模型自觉遵守，没有类型系统或编译器兜底；4 星的社区规模意味着实战反馈有限。亮点是上手成本全场最低，装完即用。

### ai-research-skills 多AI委派家族：路由路线

[WenyuChiou/ai-research-skills](https://github.com/WenyuChiou/ai-research-skills)，230 星，是本次检索中该赛道星标最高的项目，检索日前 27 天仍在更新，MIT，15 个 Skill、5 个插件、一次 marketplace 安装。它的编排思路完全不同：**不编排子Agent，而是编排不同的AI**。三大设计原则之三 "Character-driven routing" 原文：

> "Mechanical bulk → Codex. Long-context / CJK → Gemini. Judgment / governance → Claude. The router (`research-hub-multi-ai`) writes a coordination file so each delegate reads its own brief, not the parent context."

机械批量活给 Codex，长上下文与中文给 Gemini，判断与治理留给 Claude——路由器写一份协调文件，每个受委派者只读自己的任务书。配套 `codex-delegate`、`gemini-delegate` 两个插件分别处理跨 CLI 交接。另一个值得抄的细节是 **anti-leakage schema**：论文论点文件 `claims.yml` 中，任何 `evidence_artifacts` 为空的论点被**强制**标记 `status: gap` 并附 `gap_reason`，下游 Skill 拒绝输出过度自信的结论——用数据格式倒逼诚实，比提示词里写“不要编造”可靠得多。短板：作者自述“由一名研究生单独组装测试”，领域偏水资源与基于Agent的建模，且 `zotero-skills` 存在双插件同名嵌拷贝、裸名调用会静默解析到旧副本的已知问题（README Limitations 一节明确记录）。

### superpowers 编排层：方法论路线（参照系）

superpowers 此前已从“治AI瞎改代码”的角度拆过，本期只看编排层。`subagent-driven-development` 的 SKILL.md 是编排类提示词工程的教科书，四个可直接抄的设计：**每任务新鲜子Agent + 双阶段评审**（implementer 干活 → task reviewer 给“规格合规 + 代码质量”两个独立判定 → 全部完成后整分支终审，SKILL.md 内嵌完整 dot 决策图）；**文件交接三件套**（`scripts/task-brief` 抽取任务书、`scripts/review-package` 打包 diff、报告文件按 brief 命名回写，并点名真实教训——某次派发提示词 42k 字符里 99% 是粘贴的历史）；**防重派台账**（`.superpowers/sdd/progress.md`，原文直言“丢失进度的控制器把已完成的任务序列全部重派一遍，是观察到过的最昂贵失败”）；**模型分级经济学**（"Turn count beats token price"——最便宜的模型做多步工作常多花 2-3 倍轮次反而更贵，评审者与从散文任务书干活的实现者应以中档模型为下限）。姊妹篇 `dispatching-parallel-agents` 给出最精炼的并行口诀："Multiple dispatch calls in one response = parallel execution"，并用 dot 决策树钉死边界：失败相关则串行、共享状态则禁并行。分发能力也是四者最强——README 列出 Claude Code、Codex、Cursor、Gemini CLI、Copilot CLI 等 15+ 宿主的安装路径。

## 横向对比：四条路线怎么选

| 维度 | agent-runbook | coordinator-mode | 多AI委派家族 | superpowers 编排层 |
|---|---|---|---|---|
| 控制流表达 | YAML 编译，机械可验证 | 协议文本，靠模型自觉 | 路由决策 + 协调文件 | 决策树 + 台账 |
| 状态载体 | 文件 + JSON Schema | 会话内 | manifests + 协调文件 | 台账 + git |
| 断点续跑 | ✅ 一等公民 | ❌ | 部分（manifest 可重入） | ✅ ledger 机制 |
| 异构模型支持 | ❌ 同一宿主 | ❌ | ✅ 核心特性 | ❌ 同一宿主 |
| 编译期校验 | ✅ 契约闭环 | ❌ | schema 反泄漏 | ❌ |
| 上手成本 | 高（YAML+Schema） | 低（装插件即用） | 中（多插件按需装） | 低（官方市场一行） |
| 适合谁 | DevOps/长流程自动化 | 想轻量上手的个人开发者 | 多AI工具链团队/科研 | 全流程严肃开发 |

## 推荐排行榜

- **综合实力**：superpowers 编排层 > ai-research 多AI委派 > agent-runbook > coordinator-mode
- **设计创新**：agent-runbook（编译期契约闭环在全生态几乎无对标）> 多AI委派 > superpowers > coordinator-mode
- **新手友好**：coordinator-mode ≈ superpowers > 多AI委派 > agent-runbook
- **生产可靠性**：superpowers > agent-runbook > 多AI委派 > coordinator-mode
- **值得关注度**：agent-runbook——“循环工程”这个词若在 2026 下半年流行，大概率从这里出发

## 安装命令速查

```bash
# agent-runbook（编译器路线）
pip install git+https://github.com/KnoxOps/agent-runbook.git
python3 -m agent_runbook generate examples/restart-nginx/runbook.yaml -o examples/restart-nginx/

# claude-power-skills（协议路线，含 coordinator-mode）
/plugin install irfad7/claude-power-skills

# ai-research-skills 多AI委派（路由路线）
claude plugin marketplace add WenyuChiou/ai-research-skills
claude plugin install research-workspace@ai-research-skills
claude plugin install codex-delegate@ai-research-skills
claude plugin install gemini-delegate@ai-research-skills

# superpowers（方法论路线，官方市场）
/plugin install superpowers@claude-plugins-official
```

## 结语：工作流应该住在哪里

四条路线其实回答了同一个问题：**当一篇文章装不下一个工作流时，工作流应该住在哪里？** agent-runbook 说住在 YAML 里、让 SKILL.md 当编译产物；coordinator-mode 说住在协议文本里；ai-research-skills 说住在路由决策和 manifests 里；superpowers 说住在决策树和台账里。四家的交汇点惊人一致：**让状态走文件，不让上下文背锅**。如果你只打算从这个赛道带走一条经验去写自己的编排类Skill，就是这一条。

## 参考来源

1. [KnoxOps/agent-runbook](https://github.com/KnoxOps/agent-runbook) — 编译器路线主拆解对象，Loop Engineering、runbook 语法、契约闭环与 Step 类型均取自仓库原文
2. [irfad7/claude-power-skills](https://github.com/irfad7/claude-power-skills) — coordinator-mode、batch-mode 及"protocols, not prompts"设计哲学来源
3. [WenyuChiou/ai-research-skills](https://github.com/WenyuChiou/ai-research-skills) — Character-driven routing、anti-leakage schema 与 Limitations 记录来源
4. [obra/superpowers](https://github.com/obra/superpowers) 及其 [subagent-driven-development](https://github.com/obra/superpowers/blob/main/skills/subagent-driven-development/SKILL.md)、[dispatching-parallel-agents](https://github.com/obra/superpowers/blob/main/skills/dispatching-parallel-agents/SKILL.md) SKILL.md 原文 — 台账、文件交接、Turn count beats token price 与并行口诀来源
5. [SkillsMP](https://skillsmp.com/) — 2,806,826 收录量、63 分类、247,452 创作者及 DevOps/Debugging 分类数据来源
6. [GitHub 仓库检索：claude skills multi-agent SKILL.md](https://github.com/search?q=claude+skills+multi-agent+SKILL.md&type=repositories&s=stars&o=desc) — 11 个结果及各项目星标数来源（检索日 2026-08-30）

> [!tip] 51学通信知识星球
> **星主：爱卫生**（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。
> **星球定位**：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。
> **当前规模**：5200 篇主题 / 990 个回答，198 元/年。
> **加入福利**：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。
> **AI 加持**：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。

![51学通信知识星球海报-扫码加入](https://wiki.500nian.com/images/zhixingqiu_qrcode.png)