skillflow —— 将零散 Skill 串联为可执行工作流

> 单个 Skill 解决单个原子问题；当复杂任务需要多个 Skill 协作时，没有编排的协作等于各自为战。本技能在执行前完成编排：哪个 Skill 做什么、产出什么、下一个 Skill 接收什么、在哪里质检、最终如何交付——全部写成一份 Skill Flow 文档，用户确认后按 Flow 执行。

核心理念

复杂任务失败的首要原因不是单个 Skill 能力不足，而是Skill 之间缺少契约——前一步产出的格式后一步接不住、关键信息在交接时丢失、没有质检点导致错误级联传播。

本技能的核心原则：

1. 编排先于执行：先用 Skill Flow 文档把编排结构固定下来，用户确认后再执行——不让 AI 在多 Skill 协作中即兴发挥。
2. 原子化分解：每个 Skill 负责一个原子子任务，职责单一、边界清晰——一个 Skill 不做两件事。
3. 产物契约显式化：每两个相邻 Skill 之间定义明确的交接协议（产出物名称、格式、关键字段、质检标准）——不靠隐式理解传递信息。
4. 质检门保障：在关键交接点设置质量检查，防止前一步的错误向后传播。

与单 Skill 的关系：单个 Skill 是原子单元，本技能不替代任何 Skill 的内部逻辑，只负责 Skill 之间的编排和交接。

触发判定

与 awesome-graph-engineering 的边界：graph-engineering 设计抽象的执行图（节点、边、循环、质量门）。skillflow 工作于已安装的具体 Skill 层面——把真实 Skill 映射到子任务，定义产物交接。两者可协作：graph-engineering 设计执行图 → skillflow 把图中的节点映射到具体 Skill。

输入要求

• 必填：任务描述（用户要做什么）
• 强烈建议：用户期望的最终交付物（报告/文档/代码/演示文稿等）、质量标准
• 可选：已知的约束（时间/格式/受众）、偏好的 Skill 或需排除的 Skill、已有的素材或数据源

缺失信息时采用合理默认假设并在 Skill Flow 文档中标注，不逐项追问（除非关键到无法编排）。

工作流（四阶段）

Phase 1: 任务分解与 Skill 映射

将任务拆解为原子子任务，并为每个子任务匹配最合适的已安装 Skill。

分解方法：

1. 识别交付物链：从最终交付物倒推，确定需要哪些中间产物，每个中间产物对应一个子任务。
2. 原子化原则：每个子任务应能由单个 Skill 独立完成——如果一个子任务需要两个 Skill，说明分解不够细。
3. Skill 匹配：遍历已安装 Skill 列表，按职责匹配。匹配优先级：
   - 第一优先：职责完全匹配的专用 Skill（如周报任务匹配 weekly-report-writer）
   - 第二优先：领域相近的通用 Skill（如排版任务匹配 tencent-docx）
   - 第三优先：内置能力兜底（当无匹配 Skill 时标注"需新建 Skill"或"用内置能力"）
4. 顺序排列：按数据依赖关系排列子任务——上游产出是下游输入的必须串行；无数据依赖的可以并行。
5. 识别循环：如果某些步骤需要反复迭代（如"生成→审查→修正"），标记为循环节并定义终止条件。

输出：子任务清单 + 每个子任务匹配的 Skill + 依赖关系图（线性/并行/循环）。

Phase 2: 产物契约设计

为每对相邻 Skill 定义交接协议，确保信息在 Skill 之间无损传递。

每个交接点必须定义：

质检门设计原则：
- 在关键交接点设置质检（不是每个交接点都设，只在信息损耗风险高的节点设）。
- 质检标准必须可判定：要么是结构完整性检查（字段齐全），要么是内容质量检查（信息充分）。
- 质检失败的处理：退回上一步修正，不是跳过继续。

详细的产物契约设计方法和常见交接模式见 references/handoff-patterns.md。

Phase 3: Skill Flow 文档生成

将 Phase 1 和 Phase 2 的设计整合为一份结构化的 Skill Flow 文档，呈现给用户确认。

文档格式（严格遵守以下结构）：

# Skill Flow：<任务名称>

## 任务概述
- **目标**：[一句话]
- **最终交付物**：[具体交付物]
- **预计 Skill 数量**：N 个
- **流程类型**：线性 / 并行 / 循环 / 混合

## Skill 编排图
[用文字流程图或 show_widget 呈现可视化]

[Skill A] →(产物1)→ [质检门] →(产物1')→ [Skill B] →(产物2)→ [Skill C] →(最终交付物)

## 子任务明细

### 子任务 1：<名称>
- **负责 Skill**：<skill-name>
- **子任务描述**：[一句话]
- **输入**：[来自用户或上一个 Skill 的产物]
- **输出产物**：[名称 + 格式 + 关键字段]
- **质检标准**：[可判定的检查项]

### 子任务 2：...

## 交接协议
| # | 产出方 → 接收方 | 产物 | 格式 | 关键字段 | 质检标准 |
|---|---|---|---|---|---|
| 1 | Skill A → Skill B | ... | ... | ... | ... |

## 循环定义（如有）
- **循环节点**：[哪些子任务构成循环]
- **终止条件**：[达标条件 OR 最大轮数]
- **反馈入口**：[每轮反馈如何改变下一轮]

## 质检门
| 位置 | 检查项 | 失败处理 |
|---|---|---|
| 子任务1 → 子任务2 | [检查项] | 退回子任务1修正 |

## 最终交付
- **交付物**：[名称 + 格式]
- **交付方式**：[present_files / 写入文件 / 发送消息等]

## 确认请求
请确认以上 Skill Flow 设计：
1. 子任务分解和 Skill 匹配是否正确？
2. 交接协议是否完整？
3. 质检标准是否合理？
4. 最终交付物是否符合预期？

用 AskUserQuestion 确认（单轮，最多 4 题）。用户确认后才进入 Phase 4 执行。

Phase 4: 按 Flow 执行

1. 按编排顺序执行：遵循 Skill 间的依赖关系，可并行的并行调用。
2. 交接物传递：上游 Skill 产出后，按交接协议传递给下游 Skill。
3. 质检门检查：每个质检门判定通过/失败，失败则退回上游修正。
4. 循环节点执行：执行→质检→根据反馈调整→再执行，直到满足终止条件。
5. 最终交付：按 Skill Flow 文档定义的交付方式交付结果。
6. 执行记录：每个子任务记录执行状态、耗时、质检结果。

输出格式

Skill Flow 文档（Phase 3 输出）

完整的 Skill Flow 文档（如上文格式），通过 Markdown 呈现。如需可视化，可用 show_widget 生成流程图。

执行轨迹（Phase 4 输出）

## Skill Flow 执行轨迹

### 子任务 1：<名称> [<skill-name>]
- 状态：通过/失败/退回
- 产出：<产物名称>
- 质检：通过/失败（原因）

### 子任务 2：...

### 汇总
- 总子任务数 / 通过数 / 退回数
- 循环执行轮数（如有）
- 最终交付：<交付物>

示例

正面示例

用户："帮我做一份竞品分析报告，需要先搜索竞品信息，然后分析对比，最后排版成 Word 文档。"

Phase 1 输出：

子任务 1: 竞品信息搜集 → Skill: WebSearch / Explore Agent
子任务 2: 竞品对比分析 → Skill: 内置分析能力（无专用 Skill，标注"用内置能力"）
子任务 3: Word 排版生成 → Skill: tencent-docx
依赖关系: 1 → 2 → 3（线性）

Phase 2 输出：

交接 1: 搜集 → 分析
  产物: 竞品信息汇总
  格式: Markdown，每竞品一段含产品名/定位/核心功能/价格/用户量
  关键字段: 至少 3 个竞品、每竞品 ≥5 个信息维度
  质检: 竞品数量 ≥3 且每竞品信息维度 ≥5

交接 2: 分析 → 排版
  产物: 分析报告 Markdown
  格式: Markdown，含执行摘要/对比表格/SWOT/结论建议
  关键字段: 对比矩阵覆盖全部竞品、每个维度有结论
  质检: 四段齐全、对比矩阵完整

Phase 3 输出（Skill Flow 文档节选）：

# Skill Flow：竞品分析报告

## 任务概述
- **目标**：生成一份竞品分析 Word 报告
- **最终交付物**：竞品分析报告.docx
- **预计 Skill 数量**：3 个（含 1 个内置能力）
- **流程类型**：线性流水线

## 交接协议
| # | 产出方 → 接收方 | 产物 | 格式 | 关键字段 | 质检标准 |
|---|---|---|---|---|---|
| 1 | 搜集 → 分析 | 竞品信息汇总 | Markdown，每竞品一段 | ≥3 竞品，每竞品 ≥5 维度 | 竞品数 ≥3 且维度 ≥5 |
| 2 | 分析 → 排版 | 分析报告 Markdown | 四段式结构 | 对比矩阵+SWOT+结论 | 四段齐全，矩阵完整 |

## 最终交付
- **交付物**：竞品分析报告.docx
- **交付方式**：present_files

用户确认后 → 按 Flow 执行。

反面示例

> 反面 1：不设计 Skill Flow 直接执行——用户说"搜索+分析+排版"，直接开始搜索，没有定义搜索结果传给分析的格式 → 分析时发现信息不够用，返工搜索。

> 反面 2：交接协议模糊——定义"搜索结果传给分析"但不定义格式和关键字段 → 分析 Skill 收到的信息结构不一致，输出质量飘忽。

> 反面 3：不设质检门——从搜集直接到排版，中间没有检查竞品信息是否充分 → 排版出的报告内容空洞。

> 反面 4：Skill 匹配牵强——把写作任务硬塞给一个排版 Skill → Skill 承担了不擅长的职责，输出质量下降。

校验规则（红线）

设计阶段自检

1. 每个子任务必须匹配到明确的 Skill 或能力来源——不匹配 Skill 的子任务标注"用内置能力"或"需新建 Skill"。
2. 每对相邻 Skill 必须有产物契约——产物名称、格式、关键字段、质检标准四项缺一不可。
3. 复杂流程必须有至少一个质检门——纯线性无质检的流程标注风险提示。
4. 循环节点必须有终止条件和最大轮数——防止无限循环。

文档阶段自检

5. Skill Flow 文档必须先于执行呈现给用户——未经确认不开始执行。
6. 文档必须包含全部结构（任务概述/编排图/子任务明细/交接协议/质检门/最终交付/确认请求）。
7. 流程图（如有）必须忠实反映子任务依赖关系——串行/并行/循环标注一致。

执行阶段自检

8. 用户确认必须先于执行——Phase 3 确认通过后才进入 Phase 4。
9. 每个质检门必须实际执行检查——不能跳过。
10. 交接物必须按契约传递——不擅自改变格式或遗漏字段。
11. 执行轨迹必须记录每个子任务的状态和质检结果。

与其他技能的关系

本技能的独占领域：已安装 Skill 之间的编排——子任务到 Skill 的映射、Skill 间产物交接协议、Skill 协作流程文档化。不替代任何 Skill 的内部逻辑，不重复执行图/循环控制的设计（属 graph-engineering），不重复规约文档生成（属 awesome-spec）。

Resources

• references/handoff-patterns.md：产物契约设计方法、常见交接模式库（文档类/数据类/代码类/分析类的标准交接格式）、质检门设计指南、Skill 匹配决策树。Phase 2 设计交接协议时查阅。
• references/workflow-templates.md：三类标准 Skill Flow 模板——线性流水线模板、并行汇聚模板、迭代循环模板。每个模板含完整字段和填写示例。Phase 3 生成文档时参考。