AI Agent Skill 工程化 05：Skill 編排——從單體到組合的協作模式
整理版優先睇
從單體 Skill 到編排 Skill：學會編排，讓多個 Skill 像團隊一樣協作
呢篇文章係 AI Agent Skill 工程化系列嘅第五篇，專注講「Skill 編排」——即係點樣將多個原子 Skill 組合、協調，令佢哋好似一個團隊咁完成複雜任務。作者假設你已經識得寫原子 Skill、做 Eval、跑 baseline，但發現單一個 Skill 搞唔掂多步驟、多產出嘅情況，例如將 PM 需求文檔轉化為 OpenSpec 四文件，或者同時審稿、審配圖、審合規。
作者指出，編排唔係將所有功能堆埋一齊，而係拆出可重用嘅原子 Skill，再由一個「編排 Skill」負責分配任務、協調順序、彙總結果。核心口訣係：「先原子、再編排；顯式聲明；驗過程」。成篇文章圍繞四種編排模式（串行、並行、條件分支、子 Skill 調用）、SKILL.md 嘅顯式寫法、trajectory Eval 嘅設計、同埋常見陷阱（版本漂移、契約斷裂、過度編排）展開。
最終結論係：編排嘅本質唔係「全能」，而係「連接」。當你開始思考「呢個環節可唔可以抽出來重用？」、「呢幾步可唔可以並行？」嘅時候，你就已經從「寫提示詞嘅人」進化成「設計系統嘅人」。
- 編排嘅核心：先將任務拆成原子 Skill，再用編排 Skill 分配、協調、彙總，避免寫成巨型單體
- 四種編排模式：串行（有依賴）、並行（無依賴）、條件分支（動態路由）、子 Skill 調用（可重用）
- 關鍵做法：SKILL.md 必須顯式聲明 `Read 子 Skill <name>`，係 trajectory Eval 嘅驗證錨點
- Eval 分別：單體測輸出結果，編排測過程（trajectory），驗證調用順序同子 Skill 是否被正確執行
- 實戰三步遷移：①盤點 Workflow 抽原子 Skill → ②寫原子 Skill 嘅 Input/Output Contract → ③寫編排 Skill + trajectory Eval
pm-md-to-openspec-pipeline SKILL.md 骨架
一個編排 Skill 嘅完整範例，包括 purpose、layer、sub_skills、Workflow、Input Contract、Output Contract、Checkpoints
串行、並行、條件分支嘅 Workflows JavaScript 實現
三種編排模式對應嘅 Claude Code Dynamic Workflows 代碼，可直接整合到 Skill 包嘅 workflows/ 目錄
編排 Eval 範例：pipeline-002（trajectory）
一個驗證串行編排調用順序嘅 trajectory Eval JSON 範例，包含 expected、must_not、grader 字段
幾時需要編排？單體 Skill 嘅邊界信號
當你發現 SKILL.md 超過 150 行、一次任務要產出多份獨立交付、或者有子流程喺其他場景重用嘅時候，就係時候考慮編排。唔好死撐一個巨型 Skill，改唔鬱仲要硬改。
- SKILL.md > 150 行 → 職責堆疊，改唔動
- 多個獨立輸出 → 一次任務產出多份交付
- 可重用子流程 → 同一能力喺其他場景都會用到
- Eval 寫唔出 → 單體 Eval 測唔到多步驟調用順序
四種編排模式：串行、並行、條件分支、子 Skill 調用
編排模式取決於子 Skill 之間嘅依賴關係。有順序依賴就用 串行，無依賴就用 並行，要根據輸入決定路由就用 條件分支，原子 Skill 喺多個編排入面重用就用 子 Skill 調用。
- 1 串行編排：前一個輸出係後一個輸入，例如 pm-md-to-openspec-pipeline 先 Read spec-generator 再 Read reconciler
- 2 並行編排：無依賴嘅子 Skill 同時執行，例如公眾號審稿 + 審配圖用 Promise.all
- 3 條件分支：根據輸入狀態動態路由，例如文章 status=draft 行 article-reviewer，status=final 行 compliance-checker
- 4 子 Skill 調用：原子 Skill 被多個編排 Skill 調用，例如 spec-generator 喺多條 pipeline 重用
編排 Skill 嘅 SKILL.md 點寫？顯式聲明係關鍵
編排 Skill 嘅 Workflow 必須 顯式聲明 `Read 子 Skill <name>`，而唔係隱晦咁寫「分析需求文檔」。因為 trajectory Eval 要靠呢個聲明去驗證 Agent 有冇確實調用子 Skill。
---
name: pm-md-to-openspec-pipeline
purpose: PM需求文檔 → OpenSpec四文件編排
layer: L2
sub_skills:
- spec-generator
- reconciler
---
## When to Activate
- 用戶要求將 PM MD 轉化為 OpenSpec 四文件
- 用戶要求局部刷新四文件
## Input Contract
- 必填：PM MD 路徑
- 可選：現有四文件路徑（局部刷新）
## Workflow
1. Read 子 Skill `spec-generator`，輸入 PM MD，輸出 design.md + spec.md
2. Read 子 Skill `reconciler`，輸入 spec.md，輸出 field-matrix.md + tasks.md
3. 彙總四文件，檢查 Gate 閉合狀態
4. 輸出最終報告
## Output Contract
- 必須輸出四文件路徑清單 + Gate 狀態
- 不得宣稱 Gate 已閉合但四文件不完整
## Checkpoints
- 子 Skill 調用前：驗證輸入滿足子 Skill Contract
- 子 Skill 調用後：驗證輸出滿足子 Skill Contract
- 彙總階段：驗證四文件一致性另外仲要定義 Input Contract（編排 Skill 嘅輸入係子 Skill 輸入嘅集合）同 Output Contract（彙總後要輸出乜，唔可以漏）。Checkpoints 係驗證子 Skill 調用前後嘅關鍵位。
編排 Eval 點設計？trajectory 驗證過程，唔係結果
單體 Eval 測輸出結果，編排 Eval 用 trajectory Grader 測過程——驗證係咪 Read 咗應該 Read 嘅子 Skill、順序啱唔啱、有冇跳過閘門。數據來源包括 Agent trace、Skill 使用自報、編排輸出入面嘅子 Skill 調用記錄。
{
"id": "pipeline-002",
"name": "must-read-two-sub-skills",
"type": "regression",
"prompt": "將 pm-requests/feature-123.md 轉化為 OpenSpec 四文件。",
"expected": [
"必須 Read 子 Skill spec-generator",
"必須 Read 子 Skill reconciler",
"必須按順序：先 spec-generator 後 reconciler",
"必須輸出四文件路徑清單"
],
"must_not": [
"不得跳過 spec-generator 直接調用 reconciler",
"不得未 Read 子 Skill 就輸出四文件",
"不得靜默生成文件而不調用子 Skill"
],
"grader": "trajectory",
"risk": "high",
"source": "input_contract"
}baseline 跑法都要記錄 子 Skill 調用軌跡、四文件生成情況、Gate 狀態。results.tsv 可以擴充 sub_skill_1_read、order_correct 呢啲欄位。
編排陷阱同實戰三步遷移
常見陷阱有四個：版本漂移（子 Skill 更新後契約變咗，編排未同步）、契約斷裂（編排冇繼承子 Skill 嘅 must_not）、過度編排（編排 Skill 越來越大，變返新單體）、隱式調用（Workflow 冇顯式聲明 Read）。
- 版本漂移應對：編排 Skill 記低子 Skill 版本，更新時重 baseline，Eval 加 sub_skill_version 檢查
- 契約斷裂應對：編排 Output Contract 繼承子 Skill 嘅 must_not，Checkpoints 加契約繼承檢查
- 過度編排應對：編排 Skill SKILL.md ≤ 80 行，只做分配協調唔做具體事，發現膨脹就抽新原子 Skill
- 隱式調用應對：Workflow 必須用 `Read 子 Skill <name>` 顯式聲明，trajectory Eval 以此為錨點
實戰案例：將一個 80 行嘅審稿單體 Skill 拆成 article-reviewer（步驟1-3）、image-reviewer（步驟4-5），編排 Skill wechat-review-pipeline 只做彙總。Workflows 腳本（JavaScript）可以將靜態編排規則變成可執行代碼，防止 Goal drift，提升確定性。
一個 Skill 搞唔掂複雜任務？學識編排，等 Skill 組合協作
一句話：當一個 Skill 唔夠用嘅時候，點樣設計 Skill 之間嘅調用、編排、協同——令到多個 Skill 好似「團隊」咁一齊工作。
你平時整過 Skill 包、寫過 Eval、行過 baseline——但係遇到複雜任務嘅時候，會發現一個 Skill 搞唔掂。
典型場景：
•一個 PM 需求文檔要轉做 OpenSpec 四份文件，涉及規格生成、字段矩陣、任務分解——單一個 Skill 寫完 200 行，改唔鬱
•一篇公眾號文章要審稿、審配圖、審合規——三個功能塞曬喺一個 Workflow 入面，Eval 寫唔出
•編排型 Skill 調用兩個子 Skill，但係唔知點樣喺 SKILL.md 入面聲明、點樣驗證調用順序
呢篇文章淨係做一件事：由單體 Skill 到編排 Skill 嘅協作模式設計。
適合邊啲讀者：遇到需要多個 Skill 協作嘅情況
本文例子：pm-md-to-openspec-pipeline（編排兩個子 Skill）
事前睇過：[AI Agent Skill 工程化 01：寫 Skill 唔係寫 Prompt，建立可迭代嘅工程體系](AI Agent Skill 工程化 01：寫 Skill 唔係寫 Prompt，建立可迭代嘅工程體系)（L2 編排層概念）
先講人話：咩嘢係 Skill 編排？
可以把 Skill 編排 可以理解做：令到多個 Skill 組成「團隊」一齊完成任務。
Read 子Skill | |
編排 ≠ 堆疊功能：編排 Skill 唔會做具體工作，淨係負責分配任務、協調順序、滙總結果。
唔好搞亂兩層「編排」：
L0 標準層（01）：原子 Skill，只做一件事
L2 編排層（05）：編排 Skill，協調多個原子 Skill
重點係咩？
口訣：先原子、再編排；清楚聲明；驗證過程。
編排三要素：
Workflow顯式Read子Skill → trajectory Eval驗證調用順序 → 契約傳遞不斷裂
§0 開場：單體 Skill 嘅界限
0.1 幾時需要編排？
| SKILL.md > 150 行 | ||
| 多個獨立輸出 | ||
| 可以重用嘅子流程 | ||
| Eval 寫唔出 |
0.2 編排 vs 單體：本質分別
| 職責 | ||
| Workflow | Read 子Skill | |
| Eval | ||
| SKILL.md 行數 |
0.3 本文範圍
§1 編排模式四類
1.1 串行編排：前置依賴
適合場景：子 Skill 有順序依賴，前一個輸出係後一個輸入。
案例：pm-md-to-openspec-pipeline
PM需求文檔
↓ Read spec-generator Skill（生成 design.md + spec.md）
↓ Read reconciler Skill（生成 field-matrix.md + tasks.md）
↓ 彙總四文件，輸出 Gate 狀態
SKILL.md Workflow 例子：
## Workflow
1. Read 子 Skill `spec-generator`，輸入 PM MD，輸出 design.md + spec.md
2. Read 子 Skill `reconciler`，輸入 spec.md，輸出 field-matrix.md + tasks.md
3. 彙總四文件，檢查 Gate 閉合狀態
4. 輸出最終報告
1.2 並行編排：獨立分支
適合場景：子 Skill 冇依賴，可以同時執行。
案例：公眾號審稿 + 審配圖
文章正文
├─ Read article-reviewer Skill → 評分報告
└─ Read image-reviewer Skill → 配圖合規清單
↓ 彙總兩份報告
SKILL.md Workflow 例子：
## Workflow
1. 並行執行：
- Read 子 Skill `article-reviewer`，輸出評分報告
- Read 子 Skill `image-reviewer`，輸出配圖清單
2. 彙總兩份報告，輸出綜合評審結果
Eval 設計：並行編排需要驗證兩個子 Skill 都有被調用。
1.3 條件分支：動態路由
適合場景：根據輸入或者中間結果，揀選唔同嘅子 Skill。
案例：按文章狀態揀審稿流程
文章輸入
↓ 檢查狀態
├─ 狀態=初稿 → Read article-reviewer Skill
├─ 狀態=定稿 → Read compliance-checker Skill
└─ 狀態=已發 → Read update-optimizer Skill
SKILL.md Workflow 例子：
## Workflow
1. 讀取文章狀態（frontmatter.status）
2. 條件分支：
- 若 status=draft → Read `article-reviewer`
- 若 status=final → Read `compliance-checker`
- 若 status=published → Read `update-optimizer`
3. 彙總輸出
Eval 設計：條件編排需要驗證路由邏輯正確。
1.4 子 Skill 調用：可重用模塊
適合場景：原子 Skill 喺多個編排 Skill 入面重用。
案例：spec-generator 被多個編排 Skill 調用
pm-md-to-openspec-pipeline → 調用 spec-generator
feature-request-pipeline → 調用 spec-generator
bug-report-pipeline → 調用 spec-generator（生成修復規格）
子 Skill 契約要求：
| Input Contract | |
| Output Contract | |
| Side Effects |
1.5 編排模式決策樹
子 Skill 有順序依賴？
├─ 是 → 串行編排
└─ 否 → 可並行？
可並行？
├─ 是 → 並行編排
└─ 否 → 有條件分支？
有條件分支？
├─ 是 → 條件編排
└─ 否 → 單體 Skill（無需編排）
§2 編排 Skill 嘅 SKILL.md 寫法
2.1 一定要清楚聲明 Read 子 Skill
❌ 錯嘅寫法（隱式調用）：
## Workflow
1. 分析 PM 需求文檔
2. 生成 design.md 和 spec.md
3. 生成 field-matrix.md 和 tasks.md
4. 彙總四文件
問題：Eval 冇辦法驗證係咪調用咗子 Skill，冇得測 trajectory。
✅ 啱嘅寫法（清楚聲明）：
## Workflow
1. Read 子 Skill `spec-generator`，輸入 PM MD，輸出 design.md + spec.md
2. Read 子 Skill `reconciler`，輸入 spec.md，輸出 field-matrix.md + tasks.md
3. 彙總四文件，檢查 Gate 閉合狀態
4. 輸出最終報告
關鍵：Read 子 Skill <name> 係 trajectory Eval 嘅驗證錨點。
2.2 編排 Skill 嘅 Input Contract
編排 Skill 嘅輸入通常係子 Skill 輸入嘅集合：
## Input Contract
### 必填
- PM 需求文檔路徑（`pm-requests/<id>.md`）
### 可選
- 現有 design.md 路徑（局部刷新場景）
- 現有 spec.md 路徑（局部刷新場景）
### 缺失處理
- 缺 PM MD → BLOCKED，輸出待補充清單
2.3 編排 Skill 嘅 Output Contract
編排 Skill 嘅輸出通常係子 Skill 輸出嘅滙總：
## Output Contract
### 必須輸出
- 四文件路徑清單（design/spec/tasks/matrix）
- Gate 閉合狀態（OPEN/CLOSED）
- 漂移風險聲明（局部刷新場景）
### 不得輸出
- 不得宣稱 Gate 已閉合但四文件不完整
- 不得靜默修改子 Skill 未授權修改的文件
2.4 編排 Skill 嘅 Checkpoints
編排 Skill 需要額外留意子 Skill 協調嘅 Checkpoints：
## Checkpoints
### 子 Skill 調用前
- 驗證輸入滿足子 Skill Input Contract
### 子 Skill 調用後
- 驗證子 Skill 輸出滿足子 Skill Output Contract
- 驗證未出現子 Skill 未授權的副作用
### 彙總階段
- 驗證四文件一致性
- 驗證 Gate 狀態準確
2.5 編排 Skill 例子骨架
---
name: pm-md-to-openspec-pipeline
purpose: PM需求文檔 → OpenSpec四文件編排
layer: L2
sub_skills:
- spec-generator
- reconciler
---
## When to Activate
- 用戶要求將 PM MD 轉化為 OpenSpec 四文件
- 用戶要求局部刷新四文件
## When NOT to Use
- 只要單文件 → 轉子 Skill
- 無 PM MD 且不補充 → BLOCKED
## Input Contract
- 必填：PM MD 路徑
- 可選：現有四文件路徑（局部刷新）
## Workflow
1. Read 子 Skill `spec-generator`，輸入 PM MD，輸出 design.md + spec.md
2. Read 子 Skill `reconciler`，輸入 spec.md，輸出 field-matrix.md + tasks.md
3. 彙總四文件，檢查 Gate 閉合狀態
4. 輸出最終報告
## Output Contract
- 必須輸出四文件路徑清單 + Gate 狀態
- 不得宣稱 Gate 已閉合但四文件不完整
## Checkpoints
- 子 Skill 調用前：驗證輸入滿足子 Skill Contract
- 子 Skill 調用後：驗證輸出滿足子 Skill Contract
- 彙總階段：驗證四文件一致性
§3 編排嘅 Eval 設計
3.1 編排 Eval ≠ 單體 Eval
| 測什麼 | 過程 | |
| grader 類型 | trajectory | |
| expected 內容 | ||
| must_not 內容 |
3.2 trajectory Grader：測過程，唔係測結果
trajectory Grader 專門驗證編排 Skill 嘅調用軌跡：
| 有冇 Read 子 Skill | |
| 調用順序係咪正確 | |
| 有冇跳過閘門 |
數據來源：
•Agent trace（對話日誌）
•Skill 使用觀察（自報）
•編排 Skill 輸出入面子 Skill 調用記錄
3.3 編排 Eval 例子：pipeline-002
{
"id":"pipeline-002",
"name":"must-read-two-sub-skills",
"type":"regression",
"prompt":"將 pm-requests/feature-123.md 轉化為 OpenSpec 四文件。",
"expected":[
"必須 Read 子 Skill spec-generator",
"必須 Read 子 Skill reconciler",
"必須按順序：先 spec-generator 後 reconciler",
"必須輸出四文件路徑清單"
],
"must_not":[
"不得跳過 spec-generator 直接調用 reconciler",
"不得未 Read 子 Skill 就輸出四文件",
"不得靜默生成文件而不調用子 Skill"
],
"grader":"trajectory",
"risk":"high",
"source":"input_contract"
}
3.4 編排 Eval 例子：pipeline-003（閘門驗證）
{
"id":"pipeline-003",
"name":"gate-a-before-b",
"type":"regression",
"prompt":"局部刷新 field-matrix.md，但不提供現有 design/spec/tasks 路徑。",
"expected":[
"必須提示用戶提供現有四文件路徑",
"必須輸出漂移風險聲明",
"不得宣稱 Gate 已閉合"
],
"must_not":[
"不得靜默修改 design/spec/tasks",
"不得跳過漂移風險說明"
],
"grader":"structure+trajectory",
"risk":"high",
"source":"real_usage"
}
3.5 編排 Eval 嘅 baseline 點樣行
編排 Eval 嘅 baseline 需要額外記錄：
| 子 Skill 調用軌跡 | |
| 四份文件生成情況 | |
| Gate 狀態準確性 |
results.tsv 編排版：
eval_id grader pass sub_skill_1_read sub_skill_2_read order_correct gate_status
pipeline-002 trajectory ✅ ✅ ✅ ✅ -
pipeline-003 structure+trajectory ❌ ✅ ✅ ❌ OPEN誤判CLOSED
§4 編排陷阱
4.1 子 Skill 版本漂移
問題：編排 Skill 調用子 Skill，但子 Skill 更新咗之後契約變咗，編排 Skill 冇同步更新。
案例：
spec-generator v1.0 輸出：design.md + spec.md
spec-generator v2.0 輸出：design.md + spec.md + draft-tasks.md（新增）
編排 Skill pipeline 未更新，未處理 draft-tasks.md
應對：
•編排 Skill 嘅 SKILL.md 記低子 Skill 版本
•子 Skill 更新時，編排 Skill 要重新 baseline，並對正新標準
•Eval 增加 sub_skill_version 檢查項
4.2 契約傳遞斷裂
問題：編排 Skill 滙總時，冇傳遞子 Skill 嘅契約約束。
案例：
子 Skill spec-generator 輸出 must_not：不得宣稱規格已定稿
編排 Skill pipeline 彙總時，未繼承此約束，宣稱 Gate 已閉合
應對：
•編排 Skill 嘅 Output Contract 繼承子 Skill 嘅 must_not
•Checkpoints 加「子 Skill 契約繼承」檢查
•Eval 加「契約繼承一致性」檢查項
4.3 過度編排：編排層變咗新單體
問題：編排 Skill 職責膨脹，變成一個新嘅單體 Skill。
案例：
編排 Skill pipeline 最初只協調兩個子 Skill
後來增加：規格校驗、字段映射、任務拆分、風險評估
最終 SKILL.md > 200 行，改不動
應對：
•編排 Skill SKILL.md ≤ 80 行（唔計子 Skill 內容）
•編排 Skill 淨係負責分配、協調、滙總 （核心），唔做具體工作
•發現膨脹 → 抽新原子 Skill
4.4 陷阱速查表
| 版本漂移 | ||
| 契約斷裂 | ||
| 過度編排 | ||
| 隱式調用 |
§5 實戰：由單體到編排嘅三步遷移
5.1 Step 1：識別可以抽出嘅原子 Skill
信號識別：
| Workflow > 50 行 | ||
| 多個獨立輸出 | ||
| 可以重用嘅流程 |
案例：審稿 Skill 嘅 Workflow
## Workflow（原始單體，80行）
1. 讀取文章正文
2. 五維評分（結構/可讀性/CTA/合規/技術準確）
3. 輸出評分報告
4. 檢查配圖合規
5. 輸出配圖清單
6. 彙總評審結果
拆分：
•抽 article-reviewer：步驟 1–3
•抽 image-reviewer：步驟 4–5
•編排 wechat-review-pipeline：步驟 6（滙總）
5.2 Step 2：寫原子 Skill 嘅契約
原子 Skill 必須定義清楚嘅 Input/Output Contract（輸入同輸出）：
article-reviewer 契約：
## Input Contract
- 必填：文章正文路徑
- 缺失 → BLOCKED
## Output Contract
- 必須輸出：五維評分表 + P0/P1/P2 清單 + 複評目標
- 不得輸出：不得宣稱通過但評分 <9.0
image-reviewer 契約：
## Input Contract
- 必填：文章正文路徑（提取配圖）
- 缺失 → BLOCKED
## Output Contract
- 必須輸出：配圖清單 + 合規判定
- 不得輸出：不得漏審配圖
5.3 Step 3：寫編排 Skill + trajectory Eval
編排 Skill Workflow：
## Workflow
1. 並行執行：
- Read 子 Skill `article-reviewer`，輸出評分報告
- Read 子 Skill `image-reviewer`，輸出配圖清單
2. 彙總兩份報告，輸出綜合評審結果
trajectory Eval：
{
"id":"review-pipeline-001",
"name":"parallel-review-both-skills",
"type":"regression",
"prompt":"審稿 articles/demo.md，同時審配圖。",
"expected":[
"必須 Read 子 Skill article-reviewer",
"必須 Read 子 Skill image-reviewer",
"必須輸出彙總評審結果"
],
"must_not":[
"不得只審稿不審配圖",
"不得只審配圖不審稿"
],
"grader":"trajectory",
"risk":"high",
"source":"input_contract"
}
5.4 三步遷移檢查清單
| 1 識別 | ||
| 2 契約 | ||
| 3 編排 |
§6 編排模式嘅 Workflows 動態實現
Claude Code Dynamic Workflows 係編排模式嘅動態實現載體——將靜態編排規則變成可以執行嘅 JavaScript 腳本。
6.1 Workflows 同編排嘅關係
| 載體 | ||
| 執行 | ||
| 中間結果 | ||
| 可復現性 | ||
| 規模上限 | 數十到數百 agents |
核心價值：Workflows 將「計劃」由 Claude 嘅 context window 搬去腳本入面——防止 Goal drift（多次 compaction 之後目標漂移）。
6.2 串行編排嘅 Workflows 實現
// workflows/serial-pipeline.js
asyncfunctionserialPipeline(pmMdPath) {
// Phase 1: Read spec-generator 子 Skill
const specResult = awaitrunAgent({
name: "spec-generator",
prompt: `Read ${pmMdPath}，生成 design.md + spec.md`,
tools: ["Read", "Write"],
model: "sonnet"
});
// Phase 2: Read reconciler 子 Skill（依賴 Phase 1 輸出）
const matrixResult = awaitrunAgent({
name: "reconciler",
prompt: `Read ${specResult.specPath}，生成 field-matrix.md + tasks.md`,
tools: ["Read", "Write"],
model: "sonnet"
});
// Phase 3: 彙總
return {
files: [specResult.designPath, specResult.specPath,
matrixResult.matrixPath, matrixResult.tasksPath],
gateStatus: checkGateClosure([specResult, matrixResult])
};
}
// 傳入 args（用戶輸入）
module.exports = serialPipeline(args.pmMdPath);
關鍵：runAgent 跟次序執行，Phase 2 依賴 Phase 1 結果——實現串行編排。
6.3 並行編排嘅 Workflows 實現
// workflows/parallel-review.js
asyncfunctionparallelReview(articlePath) {
// 並行 spawn 兩個 agent
const [articleResult, imageResult] = awaitPromise.all([
runAgent({
name: "article-reviewer",
prompt: `Read ${articlePath}，輸出五維評分報告`,
tools: ["Read"],
model: "sonnet"
}),
runAgent({
name: "image-reviewer",
prompt: `Read ${articlePath}，提取配圖，輸出合規清單`,
tools: ["Read"],
model: "haiku"
})
]);
// 彙總兩份報告
returnsynthesizeResults([articleResult, imageResult]);
}
module.exports = parallelReview(args.articlePath);
關鍵：Promise.all 同時執行——實現並行編排。
6.4 條件分支嘅 Workflows 實現
// workflows/conditional-route.js
asyncfunctionconditionalRoute(articlePath, articleStatus) {
// Classify-and-act 模式
let result;
if (articleStatus === "draft") {
result = awaitrunAgent({
name: "article-reviewer",
prompt: `Read ${articlePath}，輸出評分報告`,
tools: ["Read"],
model: "sonnet"
});
} elseif (articleStatus === "final") {
result = awaitrunAgent({
name: "compliance-checker",
prompt: `Read ${articlePath}，檢查合規`,
tools: ["Read"],
model: "sonnet"
});
} elseif (articleStatus === "published") {
result = awaitrunAgent({
name: "update-optimizer",
prompt: `Read ${articlePath}，建議更新優化`,
tools: ["Read"],
model: "haiku"
});
}
return result;
}
module.exports = conditionalRoute(args.articlePath, args.status);
關鍵：JavaScript 條件分支做路由——實現條件編排。
6.5 Workflows 同 Skill 嘅配合
Workflows 可以保存到 Skill 包入面：
.claude/skills/wechat-review-pipeline/
├── SKILL.md # 靜態知識：觸發條件、契約
├── references/
│ ├── scoring-rubric.md
│ └── output-contract.md
├── evals/
│ └── evals.json # trajectory Eval
└── workflows/ # ← 新增目錄
├── parallel-review.js
└── conditional-route.js
SKILL.md 引用 Workflows：
## Dynamic Workflows
本 Skill 包含以下動態編排腳本：
-`workflows/parallel-review.js`：並行審稿+審配圖
-`workflows/conditional-route.js`：依狀態路由
調用方式：
- 用戶說「審稿」→ Claude 選擇合適 workflow 執行
- 用戶說「用並行 workflow 審稿」→ 執行 parallel-review.js
6.6 trajectory Eval 驗證 Workflows 執行
Workflows 執行過程可以被 trajectory Eval 驗證：
| 有冇 Read 子 Skill | runAgent({name: "子Skill名"}) |
| 執行順序 | |
| 係咪並行 |
pipeline-002 trajectory Eval 例子：
{
"id":"pipeline-002",
"name":"serial-workflow-order",
"type":"regression",
"prompt":"用 workflows/serial-pipeline.js 處理 pm-requests/feature-123.md",
"expected":[
"必須先 runAgent spec-generator",
"必須後 runAgent reconciler",
"必須彙總四文件"
],
"must_not":[
"不得跳過 spec-generator 直接執行 reconciler"
],
"grader":"trajectory",
"risk":"high",
"source":"workflow_contract"
}
6.7 Workflows 使用場景速查表
| 串行編排 | await runAgent() | |
| 並行編排 | Promise.all([]) | |
| 條件編排 | if/else 路由 | |
| 循環直到完成 | while (!condition) |
§7 FAQ + 靈魂四問
FAQ
| 編排 Skill 一定要清楚聲明 Read？ | |
| 子 Skill 版本點樣管理？ | |
| 編排 Eval 淨係測過程？ | |
| 並行編排點樣驗證？ | |
| 編排 Skill SKILL.md 行數上限？ | |
| Workflows 同 Skill 嘅關係？ | workflows/ 目錄 |
| Workflows 解決咩問題？ |
靈魂四問
1.拆得夠唔夠？ 你嘅 Workflow 入面，有冇可以重用、獨立驗證嘅原子子流程？
2.管線通唔通？ 子 Skill 嘅「紅線約束」有冇原封不動咁傳遞畀編排層？
3.界線清唔清？ 編排層有冇超過 80 行，搶咗子 Skill 嘅具體執行工作？
4.流程穩唔穩？ 當任務變複雜嘅時候，你有冇用 trajectory Eval 甚至 Workflows 腳本 嚟防止 AI「遺漏步驟」？
寫喺最後：編排嘅本質，唔係「全能」而係「連接」
好多開發者啱啱接觸編排嗰陣，會不自覺咁將編排 Skill 寫成另一個巨型單體——覺得既然要協調多個任務，咁就不如將所有邏輯都寫埋一齊，簡單啲。
但咁樣正正違背咗編排嘅原意。
編排嘅核心唔係「做更多嘢」，而係「更清楚咁分派工作」。
呢篇文章我哋傾咗四件事：
1.拆分邏輯：當一個 Skill 超過 150 行、開始難維護嗰陣，就係要拆嘅信號。將佢拆成各司其職嘅原子 Skill，等編排層回歸「指揮官」嘅角色。
2.清楚契約：喺 SKILL.md 入面一定要清楚聲明 Read 子 Skill。呢個唔係形式主義，而係為咗令之後嘅 trajectory Eval 有據可查，驗證 Agent 有冇跟流程「行直線」。
3.過程驗證：單體睇結果，編排睇過程。如果你淨係檢查最終輸出，往往會忽略 Agent 跳過關鍵步驟、或者調亂順序嘅問題。
4.動態執行：隨住任務複雜度上升，靜態嘅 Markdown 可能會遇到記憶瓶頸。引入 Claude Code 嘅 Dynamic Workflows，用 JavaScript 腳本將流程固定落嚟，係解決「目標漂移」嘅終極手段。
編排能力嘅強弱，好多時決定咗一個 AI 工程師嘅上限。
當你唔再試嚇用一個 Prompt 解決所有問題，而係開始諗：
「呢個環節可唔可以抽出來重用？」「呢幾步可唔可以並行？」「如果呢一步失敗咗，流程應該點樣回退？」
嗰陣時，你已經由「寫提示詞嘅人」，進化咗做「設計系統嘅人」。
一個 Skill 搞不定複雜任務？學會編排，讓 Skill 組合協作
一句話：當單個 Skill 不夠用時，如何設計 Skill 之間的調用、編排、協同——讓多個 Skill 像"團隊"一樣工作。
你在日常中建過 Skill 包、寫過 Eval、跑過 baseline——但遇到複雜任務時，發現一個 Skill 搞不定。
典型場景：
•一個 PM 需求文檔要轉化成 OpenSpec 四文件，涉及規格生成、字段矩陣、任務分解——單 Skill 寫完 200 行，改不動
•一篇公眾號文章要審稿、審配圖、審合規——三個功能堆在一個 Workflow 裏，Eval 寫不出
•編排型 Skill 調用兩個子 Skill，但不知道如何在 SKILL.md 裏聲明、如何驗證調用順序
這篇文章只做一件事：從單體 Skill 到編排 Skill 的協作模式設計。
適用讀者：遇到多 Skill 協作需求
本文案例：pm-md-to-openspec-pipeline（編排兩個子 Skill）
前置閲讀：[AI Agent Skill 工程化 01：寫 Skill 不是寫 Prompt，構建可迭代的工程體系](AI Agent Skill 工程化 01：寫 Skill 不是寫 Prompt，構建可迭代的工程體系)（L2 編排層概念）
先用人話：什麼是 Skill 編排？
可以把 Skill 編排 理解成：讓多個 Skill 組成"團隊"協作完成任務。
Read 子Skill | |
編排 ≠ 堆功能：編排 Skill 不做具體事，只負責分配任務、協調順序、彙總結果。
兩層"編排"別混：
L0 標準層（01）：原子 Skill，只做一件事
L2 編排層（05）：編排 Skill，協調多個原子 Skill
核心是什麼？
口訣：先原子、再編排；顯式聲明； 驗過程。
編排三要素：
Workflow顯式Read子Skill → trajectory Eval驗證調用順序 → 契約傳遞不斷裂
§0 開篇：單體 Skill 的邊界
0.1 什麼時候需要編排？
| SKILL.md > 150 行 | ||
| 多個獨立輸出 | ||
| 可複用子流程 | ||
| Eval 寫不出 |
0.2 編排 vs 單體：本質區別
| 職責 | ||
| Workflow | Read 子Skill | |
| Eval | ||
| SKILL.md 行數 |
0.3 本文邊界
§1 編排模式四類
1.1 串行編排：前置依賴
適用場景：子 Skill 有順序依賴，前一個輸出是後一個輸入。
案例：pm-md-to-openspec-pipeline
PM需求文檔
↓ Read spec-generator Skill（生成 design.md + spec.md）
↓ Read reconciler Skill（生成 field-matrix.md + tasks.md）
↓ 彙總四文件，輸出 Gate 狀態
SKILL.md Workflow 示例：
## Workflow
1. Read 子 Skill `spec-generator`，輸入 PM MD，輸出 design.md + spec.md
2. Read 子 Skill `reconciler`，輸入 spec.md，輸出 field-matrix.md + tasks.md
3. 彙總四文件，檢查 Gate 閉合狀態
4. 輸出最終報告
1.2 並行編排：獨立分支
適用場景：子 Skill 無依賴，可同時執行。
案例：公眾號審稿 + 審配圖
文章正文
├─ Read article-reviewer Skill → 評分報告
└─ Read image-reviewer Skill → 配圖合規清單
↓ 彙總兩份報告
SKILL.md Workflow 示例：
## Workflow
1. 並行執行：
- Read 子 Skill `article-reviewer`，輸出評分報告
- Read 子 Skill `image-reviewer`，輸出配圖清單
2. 彙總兩份報告，輸出綜合評審結果
Eval 設計：並行編排需驗證兩個子 Skill 都被調用。
1.3 條件分支：動態路由
適用場景：根據輸入或中間結果，選擇不同子 Skill。
案例：依文章狀態選擇審稿流程
文章輸入
↓ 檢查狀態
├─ 狀態=初稿 → Read article-reviewer Skill
├─ 狀態=定稿 → Read compliance-checker Skill
└─ 狀態=已發 → Read update-optimizer Skill
SKILL.md Workflow 示例：
## Workflow
1. 讀取文章狀態（frontmatter.status）
2. 條件分支：
- 若 status=draft → Read `article-reviewer`
- 若 status=final → Read `compliance-checker`
- 若 status=published → Read `update-optimizer`
3. 彙總輸出
Eval 設計：條件編排需驗證路由邏輯正確。
1.4 子 Skill 調用：可複用模塊
適用場景：原子 Skill 在多個編排 Skill 中複用。
案例：spec-generator 被多個編排 Skill 調用
pm-md-to-openspec-pipeline → 調用 spec-generator
feature-request-pipeline → 調用 spec-generator
bug-report-pipeline → 調用 spec-generator（生成修復規格）
子 Skill 契約要求：
| Input Contract | |
| Output Contract | |
| Side Effects |
1.5 編排模式決策樹
子 Skill 有順序依賴？
├─ 是 → 串行編排
└─ 否 → 可並行？
可並行？
├─ 是 → 並行編排
└─ 否 → 有條件分支？
有條件分支？
├─ 是 → 條件編排
└─ 否 → 單體 Skill（無需編排）
§2 編排 Skill 的 SKILL.md 寫法
2.1 必須顯式聲明 Read 子 Skill
❌ 錯誤寫法（隱式調用）：
## Workflow
1. 分析 PM 需求文檔
2. 生成 design.md 和 spec.md
3. 生成 field-matrix.md 和 tasks.md
4. 彙總四文件
問題：Eval 無法驗證是否調用了子 Skill，無法測 trajectory。
✅ 正確寫法（顯式聲明）：
## Workflow
1. Read 子 Skill `spec-generator`，輸入 PM MD，輸出 design.md + spec.md
2. Read 子 Skill `reconciler`，輸入 spec.md，輸出 field-matrix.md + tasks.md
3. 彙總四文件，檢查 Gate 閉合狀態
4. 輸出最終報告
關鍵：Read 子 Skill <name> 是 trajectory Eval 的驗證錨點。
2.2 編排 Skill 的 Input Contract
編排 Skill 的輸入通常是子 Skill 輸入的集合：
## Input Contract
### 必填
- PM 需求文檔路徑（`pm-requests/<id>.md`）
### 可選
- 現有 design.md 路徑（局部刷新場景）
- 現有 spec.md 路徑（局部刷新場景）
### 缺失處理
- 缺 PM MD → BLOCKED，輸出待補充清單
2.3 編排 Skill 的 Output Contract
編排 Skill 的輸出通常是子 Skill 輸出的彙總：
## Output Contract
### 必須輸出
- 四文件路徑清單（design/spec/tasks/matrix）
- Gate 閉合狀態（OPEN/CLOSED）
- 漂移風險聲明（局部刷新場景）
### 不得輸出
- 不得宣稱 Gate 已閉合但四文件不完整
- 不得靜默修改子 Skill 未授權修改的文件
2.4 編排 Skill 的 Checkpoints
編排 Skill 需要額外關注子 Skill 協調的 Checkpoints：
## Checkpoints
### 子 Skill 調用前
- 驗證輸入滿足子 Skill Input Contract
### 子 Skill 調用後
- 驗證子 Skill 輸出滿足子 Skill Output Contract
- 驗證未出現子 Skill 未授權的副作用
### 彙總階段
- 驗證四文件一致性
- 驗證 Gate 狀態準確
2.5 編排 Skill 示例骨架
---
name: pm-md-to-openspec-pipeline
purpose: PM需求文檔 → OpenSpec四文件編排
layer: L2
sub_skills:
- spec-generator
- reconciler
---
## When to Activate
- 用戶要求將 PM MD 轉化為 OpenSpec 四文件
- 用戶要求局部刷新四文件
## When NOT to Use
- 只要單文件 → 轉子 Skill
- 無 PM MD 且不補充 → BLOCKED
## Input Contract
- 必填：PM MD 路徑
- 可選：現有四文件路徑（局部刷新）
## Workflow
1. Read 子 Skill `spec-generator`，輸入 PM MD，輸出 design.md + spec.md
2. Read 子 Skill `reconciler`，輸入 spec.md，輸出 field-matrix.md + tasks.md
3. 彙總四文件，檢查 Gate 閉合狀態
4. 輸出最終報告
## Output Contract
- 必須輸出四文件路徑清單 + Gate 狀態
- 不得宣稱 Gate 已閉合但四文件不完整
## Checkpoints
- 子 Skill 調用前：驗證輸入滿足子 Skill Contract
- 子 Skill 調用後：驗證輸出滿足子 Skill Contract
- 彙總階段：驗證四文件一致性
§3 編排的 Eval 設計
3.1 編排 Eval ≠ 單體 Eval
| 測什麼 | 過程 | |
| grader 類型 | trajectory | |
| expected 內容 | ||
| must_not 內容 |
3.2 trajectory Grader：測過程，不是測結果
trajectory Grader 專門驗證編排 Skill 的調用軌跡：
| 是否 Read 子 Skill | |
| 調用順序是否正確 | |
| 是否跳過閘門 |
數據來源：
•Agent trace（對話日誌）
•Skill 使用觀察（自報）
•編排 Skill 輸出中的子 Skill 調用記錄
3.3 編排 Eval 示例：pipeline-002
{
"id":"pipeline-002",
"name":"must-read-two-sub-skills",
"type":"regression",
"prompt":"將 pm-requests/feature-123.md 轉化為 OpenSpec 四文件。",
"expected":[
"必須 Read 子 Skill spec-generator",
"必須 Read 子 Skill reconciler",
"必須按順序：先 spec-generator 後 reconciler",
"必須輸出四文件路徑清單"
],
"must_not":[
"不得跳過 spec-generator 直接調用 reconciler",
"不得未 Read 子 Skill 就輸出四文件",
"不得靜默生成文件而不調用子 Skill"
],
"grader":"trajectory",
"risk":"high",
"source":"input_contract"
}
3.4 編排 Eval 示例：pipeline-003（閘門驗證）
{
"id":"pipeline-003",
"name":"gate-a-before-b",
"type":"regression",
"prompt":"局部刷新 field-matrix.md，但不提供現有 design/spec/tasks 路徑。",
"expected":[
"必須提示用戶提供現有四文件路徑",
"必須輸出漂移風險聲明",
"不得宣稱 Gate 已閉合"
],
"must_not":[
"不得靜默修改 design/spec/tasks",
"不得跳過漂移風險說明"
],
"grader":"structure+trajectory",
"risk":"high",
"source":"real_usage"
}
3.5 編排 Eval 的 baseline 跑法
編排 Eval 的 baseline 需要額外記錄：
| 子 Skill 調用軌跡 | |
| 四文件生成情況 | |
| Gate 狀態準確性 |
results.tsv 編編排版：
eval_id grader pass sub_skill_1_read sub_skill_2_read order_correct gate_status
pipeline-002 trajectory ✅ ✅ ✅ ✅ -
pipeline-003 structure+trajectory ❌ ✅ ✅ ❌ OPEN誤判CLOSED
§4 編排陷阱
4.1 子 Skill 版本漂移
問題：編排 Skill 調用子 Skill，但子 Skill 更新後契約變化，編排 Skill 未同步更新。
案例：
spec-generator v1.0 輸出：design.md + spec.md
spec-generator v2.0 輸出：design.md + spec.md + draft-tasks.md（新增）
編排 Skill pipeline 未更新，未處理 draft-tasks.md
應對：
•編排 Skill 的 SKILL.md 記錄子 Skill 版本
•子 Skill 更新時，編排 Skill 需重新 baseline ，並對準新標準
•Eval 增加 sub_skill_version 檢查項
4.2 契約傳遞斷裂
問題：編排 Skill 彙總時，未傳遞子 Skill 的契約約束。
案例：
子 Skill spec-generator 輸出 must_not：不得宣稱規格已定稿
編排 Skill pipeline 彙總時，未繼承此約束，宣稱 Gate 已閉合
應對：
•編排 Skill 的 Output Contract 繼承子 Skill 的 must_not
•Checkpoints 增加"子 Skill 契約繼承"檢查
•Eval 增加"契約繼承一致性"檢查項
4.3 過度編排：編排層變成新單體
問題：編排 Skill 職責膨脹，變成新的單體 Skill。
案例：
編排 Skill pipeline 最初只協調兩個子 Skill
後來增加：規格校驗、字段映射、任務拆分、風險評估
最終 SKILL.md > 200 行，改不動
應對：
•編排 Skill SKILL.md ≤ 80 行（不含子 Skill 內容）
•編排 Skill 只負責分配、協調、彙總 （核心），不做具體事
•發現膨脹 → 抽新原子 Skill
4.4 陷阱速查表
| 版本漂移 | ||
| 契約斷裂 | ||
| 過度編排 | ||
| 隱式調用 |
§5 實戰：從單體到編排的三步遷移
5.1 Step 1：識別可抽原子 Skill
信號識別：
| Workflow > 50 行 | ||
| 多個獨立輸出 | ||
| 可複用流程 |
案例：審稿 Skill 的 Workflow
## Workflow（原始單體，80行）
1. 讀取文章正文
2. 五維評分（結構/可讀性/CTA/合規/技術準確）
3. 輸出評分報告
4. 檢查配圖合規
5. 輸出配圖清單
6. 彙總評審結果
拆分：
•抽 article-reviewer：步驟 1–3
•抽 image-reviewer：步驟 4–5
•編排 wechat-review-pipeline：步驟 6（彙總）
5.2 Step 2：寫原子 Skill 的契約
原子 Skill 必須定義清晰的 Input/Output Contract （輸入與輸出）：
article-reviewer 契約：
## Input Contract
- 必填：文章正文路徑
- 缺失 → BLOCKED
## Output Contract
- 必須輸出：五維評分表 + P0/P1/P2 清單 + 複評目標
- 不得輸出：不得宣稱通過但評分 <9.0
image-reviewer 契約：
## Input Contract
- 必填：文章正文路徑（提取配圖）
- 缺失 → BLOCKED
## Output Contract
- 必須輸出：配圖清單 + 合規判定
- 不得輸出：不得漏審配圖
5.3 Step 3：寫編排 Skill + trajectory Eval
編排 Skill Workflow：
## Workflow
1. 並行執行：
- Read 子 Skill `article-reviewer`，輸出評分報告
- Read 子 Skill `image-reviewer`，輸出配圖清單
2. 彙總兩份報告，輸出綜合評審結果
trajectory Eval：
{
"id":"review-pipeline-001",
"name":"parallel-review-both-skills",
"type":"regression",
"prompt":"審稿 articles/demo.md，同時審配圖。",
"expected":[
"必須 Read 子 Skill article-reviewer",
"必須 Read 子 Skill image-reviewer",
"必須輸出彙總評審結果"
],
"must_not":[
"不得只審稿不審配圖",
"不得只審配圖不審稿"
],
"grader":"trajectory",
"risk":"high",
"source":"input_contract"
}
5.4 三步遷移 Checklist
| 1 識別 | ||
| 2 契約 | ||
| 3 編排 |
§6 編排模式的 Workflows 動態實現
Claude Code Dynamic Workflows 是編排模式的動態實現載體——將靜態編排規則變成可執行的 JavaScript 腳本。
6.1 Workflows 與編排的關係
| 載體 | ||
| 執行 | ||
| 中間結果 | ||
| 可復現性 | ||
| 規模上限 | 數十到數百 agents |
核心價值：Workflows 將"計劃"從 Claude 的 context window 移到腳本中——防止 Goal drift（多次 compaction 後目標漂移）。
6.2 串行編排的 Workflows 實現
// workflows/serial-pipeline.js
asyncfunctionserialPipeline(pmMdPath) {
// Phase 1: Read spec-generator 子 Skill
const specResult = awaitrunAgent({
name: "spec-generator",
prompt: `Read ${pmMdPath}，生成 design.md + spec.md`,
tools: ["Read", "Write"],
model: "sonnet"
});
// Phase 2: Read reconciler 子 Skill（依賴 Phase 1 輸出）
const matrixResult = awaitrunAgent({
name: "reconciler",
prompt: `Read ${specResult.specPath}，生成 field-matrix.md + tasks.md`,
tools: ["Read", "Write"],
model: "sonnet"
});
// Phase 3: 彙總
return {
files: [specResult.designPath, specResult.specPath,
matrixResult.matrixPath, matrixResult.tasksPath],
gateStatus: checkGateClosure([specResult, matrixResult])
};
}
// 傳入 args（用戶輸入）
module.exports = serialPipeline(args.pmMdPath);
關鍵：runAgent 依次執行，Phase 2 依賴 Phase 1 結果——實現串行編排。
6.3 並行編排的 Workflows 實現
// workflows/parallel-review.js
asyncfunctionparallelReview(articlePath) {
// 並行 spawn 兩個 agent
const [articleResult, imageResult] = awaitPromise.all([
runAgent({
name: "article-reviewer",
prompt: `Read ${articlePath}，輸出五維評分報告`,
tools: ["Read"],
model: "sonnet"
}),
runAgent({
name: "image-reviewer",
prompt: `Read ${articlePath}，提取配圖，輸出合規清單`,
tools: ["Read"],
model: "haiku"
})
]);
// 彙總兩份報告
returnsynthesizeResults([articleResult, imageResult]);
}
module.exports = parallelReview(args.articlePath);
關鍵：Promise.all 並行執行——實現並行編排。
6.4 條件分支的 Workflows 實現
// workflows/conditional-route.js
asyncfunctionconditionalRoute(articlePath, articleStatus) {
// Classify-and-act 模式
let result;
if (articleStatus === "draft") {
result = awaitrunAgent({
name: "article-reviewer",
prompt: `Read ${articlePath}，輸出評分報告`,
tools: ["Read"],
model: "sonnet"
});
} elseif (articleStatus === "final") {
result = awaitrunAgent({
name: "compliance-checker",
prompt: `Read ${articlePath}，檢查合規`,
tools: ["Read"],
model: "sonnet"
});
} elseif (articleStatus === "published") {
result = awaitrunAgent({
name: "update-optimizer",
prompt: `Read ${articlePath}，建議更新優化`,
tools: ["Read"],
model: "haiku"
});
}
return result;
}
module.exports = conditionalRoute(args.articlePath, args.status);
關鍵：JavaScript 條件分支實現路由——實現條件編排。
6.5 Workflows 與 Skill 的配合
Workflows 可以保存到 Skill 包中：
.claude/skills/wechat-review-pipeline/
├── SKILL.md # 靜態知識：觸發條件、契約
├── references/
│ ├── scoring-rubric.md
│ └── output-contract.md
├── evals/
│ └── evals.json # trajectory Eval
└── workflows/ # ← 新增目錄
├── parallel-review.js
└── conditional-route.js
SKILL.md 引用 Workflows：
## Dynamic Workflows
本 Skill 包含以下動態編排腳本：
-`workflows/parallel-review.js`：並行審稿+審配圖
-`workflows/conditional-route.js`：依狀態路由
調用方式：
- 用戶說「審稿」→ Claude 選擇合適 workflow 執行
- 用戶說「用並行 workflow 審稿」→ 執行 parallel-review.js
6.6 trajectory Eval 驗證 Workflows 執行
Workflows 執行過程可被 trajectory Eval 驗證：
| 是否 Read 子 Skill | runAgent({name: "子Skill名"}) |
| 執行順序 | |
| 是否並行 |
pipeline-002 trajectory Eval 示例：
{
"id":"pipeline-002",
"name":"serial-workflow-order",
"type":"regression",
"prompt":"用 workflows/serial-pipeline.js 處理 pm-requests/feature-123.md",
"expected":[
"必須先 runAgent spec-generator",
"必須後 runAgent reconciler",
"必須彙總四文件"
],
"must_not":[
"不得跳過 spec-generator 直接執行 reconciler"
],
"grader":"trajectory",
"risk":"high",
"source":"workflow_contract"
}
6.7 Workflows 使用場景速查表
| 串行編排 | await runAgent() | |
| 並行編排 | Promise.all([]) | |
| 條件編排 | if/else 路由 | |
| 循環直到完成 | while (!condition) |
§7 FAQ + 靈魂四問
FAQ
| 編排 Skill 必須顯式聲明 Read？ | |
| 子 Skill 版本如何管理？ | |
| 編排 Eval 只測過程？ | |
| 並行編排如何驗證？ | |
| 編排 Skill SKILL.md 行數上限？ | |
| Workflows 與 Skill 的關係？ | workflows/ 目錄 |
| Workflows 解決什麼問題？ |
靈魂四問
1.拆得夠不夠？ 你的 Workflow 裏，是否有可以複用、獨立驗證的原子子流程？
2.管線通不通？ 子 Skill 的“紅線約束”有沒有原封不動地傳遞給編排層？
3.邊界清不清？ 編排層有沒有超過 80 行，搶了子 Skill 的具體執行工作？
4.流程穩不穩？ 當任務變複雜時，你有沒有用 trajectory Eval 甚至 Workflows 腳本 來防止 AI“遺忘步驟”？
寫在最後：編排的本質，不是「全能」而是「連接」
很多開發者剛接觸編排時，會下意識地把編排 Skill 寫成另一個巨型單體——覺得既然要協調多個任務，那乾脆把所有邏輯都寫在一起省事。
但這恰恰違背了編排的初衷。
編排的核心不在於“做更多事”，而在於“更清晰地分派事”。
這篇文章我們聊了四件事：
1.拆分邏輯：當一個 Skill 超過 150 行、開始難以維護時，就是拆分的信號。把它拆成各司其職的原子 Skill，讓編排層迴歸“指揮官”的角色。
2.顯式契約：在 SKILL.md 裏必須顯式聲明 Read 子 Skill。這不是形式主義，而是為了讓後續的 trajectory Eval 有據可查，驗證 Agent 有沒有按流程“走直線”。
3.過程驗證：單體看結果，編排看過程。如果你只檢查最終輸出，往往會忽略掉 Agent 跳過關鍵步驟、或者順序顛倒的隱患。
4.動態執行：隨着任務複雜度提升，靜態的 Markdown 可能會遇到記憶瓶頸。引入 Claude Code 的 Dynamic Workflows，用 JavaScript 腳本把流程固化下來，是解決“目標漂移”的終極手段。
編排能力的強弱，往往決定了一個 AI 工程師的上限。
當你不再試圖用一個 Prompt 解決所有問題，而是開始思考：
“這個環節能不能抽出來複用？”“這幾個步驟能不能並行？”“如果這一步失敗，流程該怎麼回退？”
這個時候，你就已經從“寫提示詞的人”，進化成了“設計系統的人”。