agent-Specialization/agentskills/workflow-authoring/SKILL.md

name	description
workflow-authoring	编写、创建或修改工作流（workflow）定义文件 WORKFLOW.md 时使用。工作流把一套既定流程（阶段、审核、分支、结束方式）存为可复用文档，激活后智能体按流程逐步推进。当用户要求「新建一个工作流」「写一个 xx 流程」「调整工作流结构（增删阶段/审核/分支）」，或需要排查工作流格式与校验问题时使用。附带初始化与校验脚本。

工作流（Workflow）文档编写指南

工作流 = 一份 WORKFLOW.md：YAML frontmatter 描述节点拓扑，markdown 正文写流程约定。核心理念：结构在边上，自主在阶段内——拓扑只约束阶段间流转，每个执行阶段内智能体自由工作，阶段完成后汇报推进。

标准创建流程

1. 初始化模板：

   python3 scripts/init_workflow.py <name> [--path <目录>] [--template linear|review|branch]
   

   生成 <目录>/<name>/WORKFLOW.md（已存在不覆盖）。三种模板：linear 线性 / review 带审核 / branch 带分支。
2. 填写内容：替换模板中所有 [方括号] 占位，按需增删节点。
3. 保存前自检：

   python3 scripts/validate_workflow.py <name>
   

   有 error 级问题必须全部修掉，否则保存会被拒绝。
4. 校验通过后交由保存流程（工作流名即 <name>，合法字符：小写字母/数字/连字符，首字符为字母或数字）。

WORKFLOW.md 格式骨架

---
name: my-pipeline
description: 一句话说明这个流程干什么
review_mode: active
max_stage_rounds: 20
end_conditions: 什么算完成
nodes:
  - id: start-1
    kind: start
    name: 开始
    next: explore
  - id: explore
    kind: stage
    name: 代码探索
    goal: 理解改动范围，产出影响面清单
    instructions: 先读 git diff 总览，再按模块深入；禁止通读整文件。
    next: verify-gate
  - id: verify-gate
    kind: review
    name: 验证审核
    prompt: 验证证据是否真实可复现
    next: end-1
    reject_to: explore
    max_rejects: 3
  - id: end-1
    kind: end
    name: 结束
---

## 工作方式
先理解再动手，禁止跳过验证。

## 验证方式
构建通过 + 相关测试通过。

## 结束方式
更新文档并汇报。

--- 之后的正文会在激活时原文呈现给执行者——写各阶段通用的整体约定，别写节点级细节。

frontmatter 字段

字段	必填	默认	说明
name	✓	—	小写字母/数字/连字符
description	推荐	''	一句话用途，出现在流程选择菜单
review_mode		active	active：审核时可查证证据；readonly：审核只看汇报与记录
max_stage_rounds		20	单阶段轮数上限；撞限不停流程，只会让执行者停下来向用户确认是否继续
end_conditions		''	完成标准的声明性描述（展示用）
nodes	✓	—	节点数组，五种节点见 references/nodes.md

节点速查

kind	语义	关键字段
start	入口，恰好 1 个	next
end	终点，至少 1 个	—
stage	执行阶段（阶段内完全自主）	goal + instructions + next
review	审核把关（汇报时同步审完立即走，不停留）	prompt + next + reject_to + max_rejects
branch	单出线=并线器自动穿过；多出线=AI 决策点（condition 必填为决策依据）	next[]（target/condition）

字段详解与语义：见 references/nodes.md 完整示例（线性 / 带审核 / 分支+并线）：见 references/examples.md

校验规则（违反即保存失败，validate 脚本同款）

1. name 非空且合法；节点 id 全局唯一
2. 恰好 1 个 start；至少 1 个 end
3. start/stage/review 的 next、review 的 reject_to、branch 每条出线的 target 都必须显式连接、指向存在的节点、且不指向 start
4. max_rejects ≥ 1；多出线 branch 的每条 condition 必填

写作建议

• 阶段 3~7 个为宜；goal 一句话、instructions 三五条关键约束（这两者在每次推进时会全文呈现给执行者）
• 需要把关就显式放 review 节点——终点前不会自动审核
• reject_to 指回真正能整改问题的阶段，不要指回紧邻前一站走过场
• 分支 condition 写给 AI 的决策依据：互斥、可判断、覆盖常见情形
• 修改已激活的工作流文档不影响正在运行的实例——运行中的实例按激活时的版本执行，需退出后重新激活才用新版本