AI Agent Skill 工程化 07：靜態 Skill + 動態 Workflows——讓 Skill「能跑、能試、能迭代」

作者：前端AI行走

日期：2026年6月24日上午10:00

來源：WeChat 原文

✦整理版優先睇

速讀 5 個重點高亮

靜態 SKILL.md 管知識，動態 Workflows 管執行，配合 trajectory Eval 確保過程正確

整理版摘要

呢篇文章係 AI Agent Skill 工程化系列嘅第七篇，作者想解決靜態 Skill 嘅執行不確定、目標漂移同並行限制等問題。多數 Skill 淨係得靜態知識（SKILL.md），執行時靠 Agent 逐輪決策，容易跳步或遺失步驟。整體結論係通過引入 workflows/ 目錄同 trajectory Eval，將編排模式變成可執行腳本，實現確定性執行同過程驗證。

具體做法係擴展 Skill 目錄結構，加咗 workflows/ 同 evals/trajectory-evals.json，並提供四種編排模式嘅腳本示例（串行、並行、條件路由、循環直到完成）。SKILL.md 負責觸發條件、契約同知識；workflows/ 入面嘅 JavaScript 腳本負責具體執行邏輯；trajectory Eval 驗證執行過程。

作者用 wechat-review-pipeline 做案例，展示咗由建立 Skill 包、寫 SKILL.md、寫 Workflows、寫 trajectory Eval 到驗證嘅完整流程。同時指出常見反模式，例如用 Workflows 取代 SKILL.md 或者淨係寫 output Eval 唔寫 trajectory Eval。總括嚟講，呢篇文章提供咗一套實戰框架，令 Skill 可以「能跑、能試、能迭代」。

分工明確：SKILL.md 管靜態知識（觸發、契約、步驟描述），Workflows 管動態執行（具體編排邏輯），兩者配合唔互補替代。
四種編排模式：串行（await）、並行（Promise.all）、條件路由（if/else）、循環直到完成（while），每種都有對應 JavaScript 腳本模板。
雙重驗證：output Eval 驗證輸出結果，trajectory Eval 驗證執行過程（check runAgent 順序、並行完整、路由正確）。
實戰落地：new-skill.sh 腳手架自動生成 workflows/ 目錄同 trajectory-evals.json，配合 validate-skill.py 同 run_evals.py 可以 CI 集成。
反模式提醒：唔好將執行邏輯放入 SKILL.md，唔好唔寫 trajectory Eval，Workflows 要保存到 Skill 包便於複用。

值得記低

流程

四種 Workflows 腳本模板

包含串行、並行、條件路由、循環直到完成嘅 JavaScript 腳本示例，可直接用嚟建立動態層 Skill。

工具

new-skill.sh 腳手架

自動建立 Skill 目錄結構，預設包含 workflows/ 模板同 evals/trajectory-evals.json，減少手動設定。

Skill

wechat-review-pipeline 案例 Skill

一個完整嘅 L2 動態層 Skill，示範點樣用 SKILL.md + Workflows + trajectory Eval 實現公眾號審稿編排。

整理重點

靜態 Skill 嘅邊界同 Workflows 嘅突破

靜態 Skill 嘅組件包括 SKILL.md、references/、evals/，佢哋可以定義觸發條件同步驟，但執行時靠 Agent 逐輪決策，出現三大侷限。

執行不確定：Claude 可能跳步驟，Workflow 寫咗4步只執行3步就停
Goal drift：多次 compaction 後步驟細節丟失，「不得靜默修改」約束被遺忘
規模受限：單 context window 無法協調大量 Agent，想跑50個並行審稿但 context 唔夠

執行不確定

Goal drift

規模受限

整理重點

Skill 結構擴展：workflows/ 目錄同 SKILL.md 引用

為咗加入動態執行層，需要擴展 Skill 目錄結構，增加 workflows/ 目錄同 evals/trajectory-evals.json。以下係 wechat-review-pipeline 嘅目錄結構，可直接對照閲讀。

擴展後嘅 Skill 目錄結構 text

plugins/frontend-team-toolkit/skills/wechat-review-pipeline/
├── SKILL.md                    # 靜態知識：觸發條件、契約、Workflow 文本
├── .skill-meta.json            # workflows.enabled + trajectory_evals 路徑
├── references/
│   └── output-contract.md
├── evals/
│   ├── evals.json              # 輸出 Eval
│   └── trajectory-evals.json   # 過程 Eval
├── workflows/                  # ← 動態編排腳本
│   ├── README.md
│   ├── parallel-review.js
│   ├── conditional-route.js
│   └── weekly-regression.js
└── scripts/validate-output.sh

workflows/ 目錄入面每個文件對應一種編排模式，例如 parallel-review.js 實現並行編排，conditional-route.js 實現條件路由。

workflows/

trajectory-evals.json

Dynamic Workflows 小節

parallel-review.js — 並行執行兩個子 Skill（Promise.all）
conditional-route.js — 依狀態路由到不同子 Skill（if/else）
weekly-regression.js — 循環跑 Eval 直到條件滿足（while loop）

SKILL.md 需要喺 Dynamic Workflows 小節引用每個 workflow，寫明用途、觸發關鍵詞同輸入輸出，等 Claude 可以自動選擇或用戶顯式指定。

整理重點

四種 Workflows 腳本模式

Workflows 腳本採用 JavaScript，使用 runAgent()、Promise.all、await 等關鍵函數。四種模式覆蓋常見編排需求。

1 串行編排：用 await runAgent() 依次執行有依賴嘅多步驟，確保順序。
2 並行編排：用 Promise.all([]) 同時 spawn 多個 Agent，適合無依賴嘅分支任務。
3 條件路由：用 if/else 分類後執行對應 Agent，適合動態選擇子 Skill。
4 循環直到完成：用 while (!condition) 唔確定工作量嘅任務，例如反覆跑 Eval 直到全綠。

runAgent()

Promise.all

await

if/else

while

並行編排腳本示例 (parallel-review.js) javascript

async function parallelReview(articlePath) {
  const [reviewResult, imageResult] = await Promise.all([
    runAgent({
      name: "article-reviewer",
      prompt: `Read ${articlePath}，輸出五維評分報告`,
      tools: ["Read"],
      model: "sonnet",
      worktree: true
    }),
    runAgent({
      name: "image-reviewer",
      prompt: `Read ${articlePath}，輸出配圖合規清單`,
      tools: ["Read"],
      model: "haiku",
      worktree: true
    })
  ]);
  return synthesizeResults([reviewResult, imageResult]);
}

整理重點

trajectory Eval 驗證同實戰配合

淨係有 Workflows 腳本唔夠，仲要驗證執行過程。trajectory Eval 透過檢查 Agent trace（Claude Code 嘅對話日誌）嚟確認 runAgent 調用順序同完整性。

Agent trace

串行順序

並行完整

條件路由

實戰配合可以跟住以下 check list 進行：

1. 創建目錄：用 new-skill.sh 生成 Skill + workflows/ + trajectory-evals
2. 寫 SKILL.md：定義靜態知識同 Workflows 引用
3. 寫 Workflows：按四種模式寫編排腳本
4. 寫 trajectory Eval：驗證 Workflows 執行過程
5. 驗證配合：跑 Workflows + 檢查 Agent trace，確保執行符合預期

常見反模式包括用 Workflows 取代 SKILL.md、喺 SKILL.md 寫執行邏輯、唔寫 trajectory Eval，呢啲都要避免。

前言

一句話：SKILL.md 講「應該點做」，Workflows 講「點樣執行」。
兩者分工，Skill 先至由說明書變成可以編排嘅程序。

讀完 01–06，你大概已經建立過 Skill 包、寫過 Eval、配過 CI。但大多數 Skill 仍然停留喺靜態層面：SKILL.md 描述步驟，執行時靠 Agent 逐輪估，跳步、漂移、並行上限，都係常見情況。

呢篇文章淨係解決一個問題：點樣幫 Skill 加上動態執行層。

你而家嘅痛點	Workflows 補啲乜
寫咗 Workflow 步驟，執行仍然唔穩定	JavaScript 腳本按順序/並行執行，唔靠即時決策
05 篇講咗串行/並行，落地欠腳本	`workflows/*.js` 將編排模式變成可以執行嘅代碼
得 output Eval，改完唔知過程啱唔啱	trajectory Eval 驗證 `runAgent` 順序同完整性

系列索引：[【系列索引】AI Agent Skill 工程化]

Skill + Workflows 點樣分工？

Skill + Workflows = 說明書 + 可執行腳本。

類比	Skill + Workflows 裏面對應啲乜
說明書	SKILL.md：幾時用、點樣做、契約
可執行腳本	Workflows JavaScript：具體執行邏輯
驗證程序	trajectory Eval：驗證執行過程係咪正確
安裝包	Skill 目錄：`SKILL.md` + `workflows/` + `evals/`

配合 ≠ 替代：Workflows 唔係取代 SKILL.md，而係增強 Skill 嘅動態執行能力。

同 01–06 系列嘅關係（90 秒）

篇	解決啲乜	呢篇文點樣用
01 Blueprint	Skill 目錄結構	呢篇文擴展結構（增加 `workflows/`）
05 編排	編排模式定義	呢篇文實現編排模式（動態腳本）
06 CI 門禁	自動化迴歸	呢篇文補充 Workflows 自動化循環
07 呢篇文	Skill + Workflows 配合體系	配合主線

三層「Skill」唔好混淆：

L0 標準層（01）：原子 Skill，只有 SKILL.md + references/
L1 編排層（05）：編排 Skill，SKILL.md + 子 Skill 契約
L2 動態層（07）：Skill + Workflows，SKILL.md + workflows/ + trajectory Eval

核心內容

口訣：

靜態知識喺 SKILL.md，動態編排喺 Workflows，過程驗證用 trajectory Eval。

配合三要素：

SKILL.md定義觸發+契約 → Workflows腳本執行編排邏輯 → trajectory Eval驗證執行過程

§0 開篇：靜態 Skill 嘅邊界

0.1 靜態 Skill 做到啲乜？

靜態 Skill 組件	做到啲乜
SKILL.md	定義觸發條件、Workflow 步驟、契約
references/	評分 rubric、輸出契約模板
evals/	測試用例（測輸出）

靜態 Skill 嘅能力邊界：

•✅ 可以話畀 Claude「幾時應該用」

•✅ 可以話畀 Claude「跟住乜嘢步驟做」

•❌ 唔可以確定性執行（Claude 逐輪決定）

•❌ 唔可以防止 Goal drift（compaction 之後步驟可能會丟失）

•❌ 唔可以大規模並行（幾個 subagent 上限）

0.2 靜態 Skill 嘅三大侷限

侷限	說明	案例
執行唔確定	Claude 逐輪決定，可能會跳步驟	Workflow 寫咗 4 步，Claude 只執行 3 步就停
Goal drift	多次 compaction 之後，步驟細節丟失	「唔可以靜默修改」約束喺 compaction 之後被遺忘
規模受限	單個 context window 冇辦法協調大量 agent	想行 50 個並行審稿，但 context 唔夠

0.3 Workflows 點樣突破侷限

Workflows 做到啲乜	解決啲乜侷限
確定性執行	JavaScript 腳本按代碼順序執行，唔跳步驟
防止 Goal drift	計劃喺腳本裏面，唔受 compaction 影響
大規模並行	可以協調數十到數百 agents（上限 16 併發，1000 總量）

0.4 呢篇文嘅邊界

本文講	其他篇講
Skill + Workflows 配合體系	01：Skill 目錄結構（基礎）
Workflows 腳本點樣寫	05：編排模式定義（靜態）
trajectory Eval 驗證 Workflows	06：CI 門禁自動化
Workflows 保存到 Skill	08：Darwin 自動優化（後續）

§1 Skill 結構擴展：增加 workflows/ 目錄

1.1 擴展之後嘅 Skill 目錄結構

倉庫落地：以下結構已經喺plugins/frontend-team-toolkit/skills/wechat-review-pipeline/ 實現，可以直接對照閲讀。

plugins/frontend-team-toolkit/skills/wechat-review-pipeline/
  ├── SKILL.md                    # 靜態知識：觸發條件、契約、Workflow 文本
  ├── .skill-meta.json            # workflows.enabled + trajectory_evals 路徑
  ├── references/
  │   └── output-contract.md
  ├── evals/
  │   ├── evals.json              # 輸出 Eval（驗證彙總結果）
  │   └── trajectory-evals.json   # 過程 Eval（驗證 runAgent 順序）
  ├── workflows/                  # ← 動態編排腳本
  │   ├── README.md
  │   ├── parallel-review.js      # 並行審稿 + 審配圖
  │   ├── conditional-route.js    # 依狀態路由
  │   └── weekly-regression.js    # 定期迴歸
  └── scripts/validate-output.sh

腳手架說明：

skill-engineering/bin/new-skill.sh 而家已經默認複製 workflows/ 模板與evals/trajectory-evals.json，唔需要手動 mkdir workflows。

1.2 workflows/ 目錄嘅作用

workflows/ 文件	作用	對應編排模式
`parallel-review.js`	並行執行兩個子 Skill	並行編排（05 §1.2）
`conditional-route.js`	根據條件路由到唔同子 Skill	條件編排（05 §1.3）
`weekly-regression.js`	循環行 Eval 直到條件滿足	Loop until done（06 §7）

1.3 SKILL.md 點樣引用 Workflows

喺 SKILL.md 裏面聲明 Workflows：

## Dynamic Workflows

本 Skill 包含以下動態編排腳本：

### workflows/parallel-review.js
-**用途**：並行審稿 + 審配圖
-**觸發**：用戶說「並行審稿」或「同時審稿和配圖」
-**輸入**：文章正文路徑
-**輸出**：彙總評審結果

### workflows/conditional-route.js
-**用途**：依文章狀態路由到不同審稿流程
-**觸發**：用戶說「審稿」並提供文章狀態
-**輸入**：文章正文路徑 + 文章狀態（draft/final/published）
-**輸出**：對應流程的評審結果

### workflows/weekly-regression.js
-**用途**：每週定期迴歸 Skill
-**觸發**：用戶說「定期迴歸」或 `/loop weekly`
-**輸入**：Skill 名稱（可選）
-**輸出**：迴歸報告

調用方式：
- Claude 自動選擇合適的 workflow 執行
- 用戶可顯式指定：「用 parallel-review workflow 審稿」

1.4 Skill + Workflows 結構速查表

Skill 組件	靜態定係動態	作用
SKILL.md	靜態	知識、規則、觸發條件、契約
references/	靜態	評分 rubric、輸出契約模板
evals/evals.json	靜態	輸出 Eval 定義
evals/trajectory-evals.json	靜態	過程 Eval 定義（CI 同 evals.json 合併加載）
workflows/	動態	編排腳本、執行邏輯
trajectory Eval	驗證	驗證 Workflows 執行過程

§2 Workflows 腳本點樣寫

2.1 Workflows 腳本嘅基本結構

// workflows/example.js

async function mainWorkflow(args) {
// Phase 1: 準備輸入
const input = validateInput(args);

// Phase 2: 執行編排邏輯
const result = awaitorchestrate(input);

// Phase 3: 輸出結果
returnformatOutput(result);
}

// Claude Code runtime 會傳入 args（用戶輸入）
module.exports = mainWorkflow(args);

關鍵函數：

函數	說明
`runAgent()`	spawn 一個 subagent
`Promise.all()`	並行執行多個 agent
`await`	串行等待 agent 完成
`args`	用戶傳入嘅參數

2.2 串行編排腳本示例

// workflows/serial-review.js

async function serialReview(articlePath) {
// Phase 1: 審稿
const reviewResult = awaitrunAgent({
name: "article-reviewer",
prompt: `Read ${articlePath}，輸出五維評分報告`,
tools: ["Read"],
model: "sonnet",
worktree: false// 不隔離，共享主 session
  });

// Phase 2: 審配圖（依賴 Phase 1）
const imageResult = await runAgent({
name: "image-reviewer",
prompt: `Read ${articlePath}，輸出配圖合規清單`,
tools: ["Read"],
model: "haiku",
worktree: true// 隔離執行
  });

// Phase 3: 彙總
return {
review: reviewResult,
images: imageResult,
summary: `審稿評分: ${reviewResult.score}, 配圖合規: ${imageResult.status}`
  };
}

module.exports = serialReview(args.articlePath);

關鍵：

•await 確保串行順序

•Phase 2 依賴 Phase 1 完成

•worktree: true 可以隔離執行

2.3 並行編排腳本示例

// workflows/parallel-review.js

async function parallelReview(articlePath) {
// 同時 spawn 兩個 agent
const [reviewResult, imageResult] = awaitPromise.all([
runAgent({
name: "article-reviewer",
prompt: `Read ${articlePath}，輸出五維評分報告`,
tools: ["Read"],
model: "sonnet",
worktree: true// 隔離，避免衝突
    }),
runAgent({
name: "image-reviewer",
prompt: `Read ${articlePath}，輸出配圖合規清單`,
tools: ["Read"],
model: "haiku",
worktree: true
    })
  ]);

// 彙總（Barrier：等待全部完成）
return synthesizeResults([reviewResult, imageResult]);
}

function synthesizeResults(results) {
return {
reviewScore: results[0].score,
imageStatus: results[1].status,
combinedStatus: results[0].score >= 9.0 && results[1].status === "pass"
                   ? "PASS" : "FAIL"
  };
}

module.exports = parallelReview(args.articlePath);

關鍵：

•Promise.all 實現並行

•worktree: true 避免並行衝突

•彙總步驟係 Barrier（等待全部完成）

2.4 條件路由腳本示例

// workflows/conditional-route.js

async function conditionalRoute(articlePath, articleStatus) {
// Classify-and-act 模式
let agentConfig;

// 分類：根據狀態選擇 agent
if (articleStatus === "draft") {
    agentConfig = {
name: "article-reviewer",
model: "sonnet"
    };
  } elseif (articleStatus === "final") {
    agentConfig = {
name: "compliance-checker",
model: "sonnet"
    };
  } elseif (articleStatus === "published") {
    agentConfig = {
name: "update-optimizer",
model: "haiku"
    };
  } else {
// 默認路由
    agentConfig = {
name: "article-reviewer",
model: "sonnet"
    };
  }

// 執行選定的 agent
const result = await runAgent({
    ...agentConfig,
prompt: `Read ${articlePath}，執行相應評審`,
tools: ["Read"],
worktree: false
  });

return result;
}

module.exports = conditionalRoute(args.articlePath, args.status);

關鍵：

•JavaScript if/else 實現路由

•先分類，再執行揀好嘅 agent

•默認路由處理邊界情況

2.5 循環直到完成腳本示例

// workflows/loop-regression.js

async function loopRegression(skill, maxIterations = 10) {
let iteration = 0;
let allPassed = false;

while (iteration < maxIterations && !allPassed) {
// 跑 Eval
const results = await runAgent({
name: "eval-runner",
prompt: `跑 ${skill} 的全量 Eval`,
tools: ["Read", "Bash"],
model: "sonnet"
    });

// 檢查是否全綠
    allPassed = results.every(r => r.pass === true);

if (!allPassed) {
// 未全綠 → 記錄失敗項
console.log(`Iteration ${iteration}: 發現 ${results.filter(r => !r.pass).length} 個失敗`);
    }

    iteration++;

// 等待（可選）
if (!allPassed && iteration < maxIterations) {
awaitsleep(60000);  // 等待 1 分鐘
    }
  }

return {
iterations: iteration,
finalStatus: allPassed ? "ALL_PASS" : "STILL_HAS_FAILURES"
  };
}

module.exports = loopRegression(args.skill || "wechat-article-review");

關鍵：

•while 循環直到條件滿足

•maxIterations 防止無限循環

•每次循環之後檢查狀態

2.6 Workflows 腳本速查表

模式	JavaScript 實現	適用場景
串行編排	`await runAgent()` 依次	有依賴嘅多步驟
並行編排	`Promise.all([])`	冇依賴嘅多分支
條件路由	`if/else` 分類之後執行	動態選擇子 Skill
循環直到完成	`while (!condition)`	唔確定工作量嘅任務
對抗驗證	spawn 兩個 agent（執行+驗證）	驗證輸出質素

§3 trajectory Eval 驗證 Workflows 執行

3.1 點解需要 trajectory Eval 驗證 Workflows

問題	說明	trajectory Eval 解決
跳步驟	Workflows 腳本可能會被 Claude 概括執行	驗證每個 `runAgent` 係咪真正執行
順序錯誤	串行編排入面順序可能會倒轉	驗證 `await` 順序係咪正確
並行未同步	並行編排入面可能有 agent 未被 spawn	驗證 `Promise.all` 入面所有 agent 都執行

3.2 trajectory Eval 示例：驗證串行順序

{
"id":"workflow-serial-001",
"name":"serial-workflow-order-check",
"type":"regression",
"prompt":"用 workflows/serial-review.js 審稿 articles/demo.md",
"expected":[
"必須先 runAgent article-reviewer",
"必須後 runAgent image-reviewer",
"必須輸出彙總結果",
"兩個 agent 必須串行執行（有 await）"
],
"must_not":[
"不得跳過 article-reviewer 直接執行 image-reviewer",
"不得並行執行兩個 agent（串行編排必須串行）"
],
"grader":"trajectory",
"risk":"high",
"source":"workflow_contract"
}

3.3 trajectory Eval 示例：驗證並行完整

{
"id":"workflow-parallel-001",
"name":"parallel-workflow-both-agents",
"type":"regression",
"prompt":"用 workflows/parallel-review.js 審稿 articles/demo.md",
"expected":[
"必須同時 spawn article-reviewer agent",
"必須同時 spawn image-reviewer agent",
"必須用 Promise.all 並行執行",
"必須彙總兩份結果"
],
"must_not":[
"不得只 spawn 一個 agent",
"不得串行執行（並行編排必須並行）"
],
"grader":"trajectory",
"risk":"high",
"source":"workflow_contract"
}

3.4 trajectory Eval 示例：驗證條件路由

{
"id":"workflow-conditional-001",
"name":"conditional-workflow-route-check",
"type":"regression",
"prompt":"用 workflows/conditional-route.js 審稿 articles/demo.md，狀態=draft",
"expected":[
"必須路由到 article-reviewer agent",
"不得路由到 compliance-checker 或 update-optimizer"
],
"must_not":[
"不得路由到錯誤的 agent",
"不得跳過分類直接執行默認"
],
"grader":"trajectory",
"risk":"medium",
"source":"workflow_contract"
}

3.5 trajectory Eval 嘅數據來源

數據來源	說明
Agent trace	Claude Code 嘅對話日誌，記錄每個 `runAgent` 調用
Workflows 輸出	Workflows 腳本返回嘅結果結構
Skill 使用觀察	Skill 自報嘅執行記錄

3.6 trajectory Eval 驗證速查表

驗證項	trajectory Eval 檢查
串行順序	Agent trace 入面 `runAgent` 順序係咪正確
並行完整	Agent trace 入面係咪同時存在多個 `runAgent`
條件路由	Agent trace 入面係咪得揀咗嘅 agent
循環次數	Agent trace 入面循環次數係咪符合預期

§4 Skill + Workflows 配合實戰

4.1 實戰：建立帶 Workflows 嘅 Skill 包

Step 1：建立 Skill 目錄

# 在 frontend-team-marketplace 倉庫根目錄執行
./plugins/frontend-team-toolkit/skill-engineering/bin/new-skill.sh wechat-review-pipeline

# 腳手架已複製 workflows/ 模板 + evals/trajectory-evals.json
# 也可指定個人 Cursor skills 目錄：
# ./plugins/frontend-team-toolkit/skill-engineering/bin/new-skill.sh my-skill --path ~/.cursor/skills

對照案例：直接打開 plugins/frontend-team-toolkit/skills/wechat-review-pipeline/ 查看成品。

Step 2：寫 SKILL.md（靜態知識）

---
name: wechat-review-pipeline
purpose: 公眾號審稿編排 Skill
layer: L2
sub_skills:
  - article-reviewer
  - image-reviewer
  - compliance-checker
---

## When to Activate
- 用戶要求審稿、審配圖、審合規
- 用戶說「並行審稿」「同時審」
- 用戶說「定期迴歸」

## When NOT to Use
- 只要單一審稿 → 轉子 Skill
- 無文章正文且不補充 → BLOCKED

## Input Contract
- 必填：文章正文路徑
- 可選：文章狀態（draft/final/published）

## Workflow（靜態描述）
1. 根據需求選擇執行模式（並行/串行/條件）
2. 執行相應子 Skill
3. 彙總結果

## Dynamic Workflows

本 Skill 包含以下動態編排腳本：

### workflows/parallel-review.js
- **用途**：並行審稿 + 審配圖
- **觸發**：「並行審稿」「同時審」

### workflows/conditional-route.js
- **用途**：依狀態路由
- **觸發**：「審稿」+ 文章狀態

### workflows/weekly-regression.js
- **用途**：定期迴歸
- **觸發**：`/loop weekly`

## Output Contract
- 必須輸出：彙總評審結果
- 不得輸出：不得跳過子 Skill 直接給出結果

## Checkpoints
- 子 Skill 執行前：驗證輸入滿足契約
- 子 Skill 執行後：驗證輸出滿足契約
- 彙總階段：驗證結果一致性

Step 3：寫 Workflows 腳本

（參考 §2 嘅腳本示例，寫入 workflows/parallel-review.js、workflows/conditional-route.js）

Step 4：寫 trajectory Eval

寫入 evals/trajectory-evals.json（與 evals/evals.json 分開；CI 通過 eval_loader.py 合併加載）：

{
"id":"wechat-review-pipeline-workflow-parallel-001",
"name":"parallel-review-both-agents",
"type":"regression",
"prompt":"用 parallel-review workflow 審稿 articles/demo.md",
"expected":[
"Must spawn wechat-article-review agent",
"Must spawn image-reviewer agent",
"Must synthesize results after both complete"
],
"must_not":[
"Must NOT execute only one agent"
],
"grader":"trajectory",
"risk":"high",
"source":"workflow_contract",
"workflow":"workflows/parallel-review.js"
}

Step 5：驗證 Skill + Workflows

# 結構校驗（含 workflows/ + trajectory-evals.json 檢查）
python3 plugins/frontend-team-toolkit/skill-engineering/bin/validate-skill.py \
  plugins/frontend-team-toolkit/skills/wechat-review-pipeline

# CI 本地模擬（合併 output + trajectory Eval）
python3 plugins/frontend-team-toolkit/skill-engineering/scripts/run_evals.py \
  --mode pr --skill wechat-review-pipeline \
  --skill-base-path plugins/frontend-team-toolkit/skills

# 跑 trajectory Eval（需 Claude Code Workflows 運行時 + Agent trace）
claude -p "用 parallel-review workflow 審稿 articles/demo.md"
claude --show-trace

邊界說明：skill-engineering 提供 Workflows 模板、Eval 契約同 CI 加載；JS 腳本嘅 runAgent() 執行依賴 Claude Code Dynamic Workflows 運行時，唔喺腳手架入面內嵌執行引擎。
本地 CI 模擬：默認 SKILL_EXECUTION_MODE=local 下，wechat-review-pipeline 嘅 trajectory Eval 會生成模擬 agent_trace 供 trajectory_grader 校驗；真實 trace 驗證請設 SKILL_EXECUTION_MODE=claude_code 並配合 claude --show-trace。

4.2 實戰 Checklist

Step	做什麼	自檢標準
1 建立目錄	`new-skill.sh` 生成 Skill + workflows/ + trajectory-evals	目錄結構完整
2 寫 SKILL.md	定義靜態知識 + Workflows 引用	Workflows 引用清晰
3 寫 Workflows	寫編排腳本（串行/並行/條件）	腳本可執行
4 寫 trajectory Eval	驗證 Workflows 執行過程	Eval 可以檢查 runAgent 順序
5 驗證配合	行 Workflows + 檢查 Agent trace	執行過程符合預期

§5 Workflows 同 Skill 嘅分工

5.1 分工原則

組件	負責啲乜	唔負責啲乜
SKILL.md	觸發條件、契約、知識、Workflow 文本描述	具體執行邏輯、運行時決策
Workflows	具體執行邏輯、編排實現、運行時決策	觸發條件判斷、知識定義
trajectory Eval	驗證執行過程	驗證輸出內容（由 output Eval 負責）

5.2 啲乜放 SKILL.md，啲乜放 Workflows

內容	放喺邊度	原因
When to Activate	SKILL.md	觸發判斷係靜態規則
Input/Output Contract	SKILL.md	契約係靜態定義
Workflow 步驟描述	SKILL.md	知識層，話畀 Claude「點樣做」
runAgent 調用邏輯	Workflows	執行層，具體點樣 spawn agent
並行/串行決策	Workflows	運行時決策，動態實現
條件路由邏輯	Workflows	運行時決策，動態實現
循環終止條件	Workflows	運行時決策，動態實現

5.3 SKILL.md 同 Workflows 嘅映射

SKILL.md 內容	Workflows 對應
Workflow 步驟描述	JavaScript 函數實現
子 Skill 契約	`runAgent` 參數驗證
Checkpoints	腳本入面嘅驗證邏輯
觸發條件	Claude 自動選擇 Workflows

5.4 分工速查表

場景	SKILL.md 做	Workflows 做
定義觸發	✅ When to Activate	❌ 唔負責
定義契約	✅ Input/Output Contract	❌ 唔負責
描述步驟	✅ Workflow 文本	❌ 唔負責
執行編排	❌ 唔負責	✅ runAgent + Promise.all
驗證過程	❌ 唔負責	✅ 腳本內驗證邏輯
驗證輸出	✅ output Eval	❌ 唔負責

§6 Skill + Workflows 配合反模式

6.1 反模式一：Workflows 取代 SKILL.md

錯誤做法：只寫 Workflows 腳本，唔寫 SKILL.md。

問題：

•Claude 唔知道幾時應該用呢個 Skill

•契約唔清晰，Eval 冇辦法驗證

•冇辦法沉澱知識

正確做法：

•SKILL.md 定義觸發條件、契約、知識

•Workflows 實現具體執行邏輯

6.2 反模式二：SKILL.md 寫執行邏輯

錯誤做法：喺 SKILL.md 嘅 Workflow 裏面寫具體 JavaScript 代碼。

問題：

•SKILL.md 變成代碼檔案，失去知識層作用

•冇辦法動態執行（SKILL.md 係靜態文本）

•Claude 逐輪決定，唔確定執行

正確做法：

•SKILL.md 寫步驟描述（「點樣做」）

•Workflows 寫具體代碼（「點樣執行」）

6.3 反模式三：Workflows 冇被 trajectory Eval 驗證

錯誤做法：只寫 output Eval，唔寫 trajectory Eval。

問題：

•冇辦法驗證 Workflows 係咪真正執行

•Claude 可能會概括執行，跳過步驟

•並行/串行邏輯冇辦法驗證

正確做法：

•trajectory Eval 驗證 Workflows 執行過程

•output Eval 驗證輸出內容

6.4 反模式速查表

反模式	問題	正確做法
Workflows 取代 SKILL.md	冇觸發判斷、冇契約	SKILL.md + Workflows 配合
SKILL.md 寫執行邏輯	冇辦法動態執行	SKILL.md 描述 + Workflows 實現
唔寫 trajectory Eval	冇辦法驗證執行過程	trajectory + output Eval 配合
Workflows 唔保存到 Skill	冇辦法重用、冇辦法分發	保存到 workflows/ 目錄

§7 FAQ + 疑問

FAQ

問題	答
Workflows 一定要保存到 Skill？	建議保存，方便重用同分發
SKILL.md 同 Workflows 點樣分工？	SKILL.md 定義知識，Workflows 實現執行
Workflows 需要幾多個 Eval？	每個 Workflows 至少 1 條 trajectory Eval
並行 Workflows 點樣驗證？	trajectory 驗證所有 agent 都被 spawn
Workflows 同 CI 嘅關係？	CI 行 Workflows，Workflows 可以觸發 CI
Workflows 可以調用其他 Workflows？	可以，通過 `runAgent` 嵌套調用

疑問

1.你嘅 Skill 目錄入面有冇 workflows/？

2.SKILL.md 入面有冇聲明同引用呢啲 Workflows？

3.每個 Workflow 有冇對應嘅 trajectory Eval？

總結

你應該記住嘅三件事

#	要點	落地檢查
1	分工：SKILL.md 管觸發同契約，Workflows 管執行，兩者配合唔係取代	`SKILL.md` 有 Dynamic Workflows 小節同指向 `workflows/`
2	雙 Eval ：output Eval 驗結果，trajectory Eval 驗 `runAgent` 過程	`evals/evals.json` + `evals/trajectory-evals.json` 齊全
3	L2 動態層：喺 01 骨架上增加 `workflows/`，將 05 編排模式變成可以行嘅腳本	對照 `wechat-review-pipeline` 案例目錄

口訣記多次：靜態知識喺 SKILL.md，動態編排喺 Workflows，過程驗證用 trajectory Eval。

v1.2 · 2026-06-22 · 對齊 frontend-team-marketplace 倉庫：wechat-review-pipeline 案例 Skill + new-skill.sh 複製 workflows + CI 合併 trajectory Eval

前言

一句話：SKILL.md 寫「該怎麼做」，Workflows 寫「怎麼執行」。
兩者分工，Skill 才從說明書變成可編排程序。

讀完 01–06，你大概已經建過 Skill 包、寫過 Eval、配過 CI。但多數 Skill 仍停在靜態層：SKILL.md 描述步驟，執行時靠 Agent 逐輪猜，跳步、漂移、並行上限，都是常態。

本文只解決一個問題：怎麼給 Skill 補上動態執行層。

你現在的痛點	Workflows 補什麼
寫了 Workflow 步驟，執行仍不穩定	JavaScript 腳本按順序/並行跑，不靠臨場決策
05 篇講了串行/並行，落地缺腳本	`workflows/*.js` 把編排模式變成可運行代碼
只有 output Eval，改完不知道過程對不對	trajectory Eval 驗證 `runAgent` 順序與完整性

系列索引：[【系列索引】AI Agent Skill 工程化]

Skill + Workflows 怎麼分工？

Skill + Workflows = 說明書 + 可執行腳本。

類比	Skill + Workflows 裏對應什麼
說明書	SKILL.md：什麼時候用、怎麼做、契約
可執行腳本	Workflows JavaScript：具體執行邏輯
驗證程序	trajectory Eval：驗證執行過程是否正確
安裝包	Skill 目錄：`SKILL.md` + `workflows/` + `evals/`

配合 ≠ 替代：Workflows 不替代 SKILL.md，而是增強 Skill 的動態執行能力。

和 01–06 系列的關係（90 秒）

篇	解決什麼	本文怎麼用
01 Blueprint	Skill 目錄結構	本文擴展結構（增加 `workflows/`）
05 編排	編排模式定義	本文實現編排模式（動態腳本）
06 CI 門禁	自動化迴歸	本文補充 Workflows 自動化循環
07 本文	Skill + Workflows 配合體系	配合主線

三層「Skill」別混：

L0 標準層（01）：原子 Skill，只有 SKILL.md + references/
L1 編排層（05）：編排 Skill，SKILL.md + 子 Skill 契約
L2 動態層（07）：Skill + Workflows，SKILL.md + workflows/ + trajectory Eval

核心內容

口訣：

靜態知識在 SKILL.md，動態編排在 Workflows，過程驗證用 trajectory Eval。

配合三要素：

SKILL.md定義觸發+契約 → Workflows腳本執行編排邏輯 → trajectory Eval驗證執行過程

§0 開篇：靜態 Skill 的邊界

0.1 靜態 Skill 能做什麼？

靜態 Skill 組件	能做什麼
SKILL.md	定義觸發條件、Workflow 步驟、契約
references/	評分 rubric、輸出契約模板
evals/	測試用例（測輸出）

靜態 Skill 的能力邊界：

•✅ 能告訴 Claude「什麼時候該用」

•✅ 能告訴 Claude「按什麼步驟做」

•❌ 不能確定性執行（Claude 逐輪決策）

•❌ 不能防止 Goal drift（compaction 後步驟可能丟失）

•❌ 不能大規模並行（幾個 subagent 上限）

0.2 靜態 Skill 的三大侷限

侷限	說明	案例
執行不確定	Claude 逐輪決策，可能跳步驟	Workflow 寫了 4 步，Claude 只執行 3 步就停
Goal drift	多次 compaction 後，步驟細節丟失	「不得靜默修改」約束在 compaction 後被遺忘
規模受限	單 context window 無法協調大量 agent	想跑 50 個並行審稿，但 context 不夠

0.3 Workflows 如何突破侷限

Workflows 能做什麼	解決什麼侷限
確定性執行	JavaScript 腳本按代碼順序執行，不跳步驟
防止 Goal drift	計劃在腳本中，不受 compaction 影響
大規模並行	可協調數十到數百 agents（上限 16 併發，1000 總量）

0.4 本文邊界

本文講	別的篇講
Skill + Workflows 配合體系	01：Skill 目錄結構（基礎）
Workflows 腳本如何寫	05：編排模式定義（靜態）
trajectory Eval 驗證 Workflows	06：CI 門禁自動化
Workflows 保存到 Skill	08：Darwin 自動優化（後續）

§1 Skill 結構擴展：增加 workflows/ 目錄

1.1 擴展後的 Skill 目錄結構

倉庫落地：以下結構已在plugins/frontend-team-toolkit/skills/wechat-review-pipeline/ 實現，可直接對照閲讀。

plugins/frontend-team-toolkit/skills/wechat-review-pipeline/
  ├── SKILL.md                    # 靜態知識：觸發條件、契約、Workflow 文本
  ├── .skill-meta.json            # workflows.enabled + trajectory_evals 路徑
  ├── references/
  │   └── output-contract.md
  ├── evals/
  │   ├── evals.json              # 輸出 Eval（驗證彙總結果）
  │   └── trajectory-evals.json   # 過程 Eval（驗證 runAgent 順序）
  ├── workflows/                  # ← 動態編排腳本
  │   ├── README.md
  │   ├── parallel-review.js      # 並行審稿 + 審配圖
  │   ├── conditional-route.js    # 依狀態路由
  │   └── weekly-regression.js    # 定期迴歸
  └── scripts/validate-output.sh

腳手架說明：

skill-engineering/bin/new-skill.sh 現已默認複製 workflows/ 模板與evals/trajectory-evals.json，無需手動 mkdir workflows。

1.2 workflows/ 目錄的作用

workflows/ 文件	作用	對應編排模式
`parallel-review.js`	並行執行兩個子 Skill	並行編排（05 §1.2）
`conditional-route.js`	依條件路由到不同子 Skill	條件編排（05 §1.3）
`weekly-regression.js`	循環跑 Eval 直到條件滿足	Loop until done（06 §7）

1.3 SKILL.md 如何引用 Workflows

在 SKILL.md 中聲明 Workflows：

## Dynamic Workflows

本 Skill 包含以下動態編排腳本：

### workflows/parallel-review.js
-**用途**：並行審稿 + 審配圖
-**觸發**：用戶說「並行審稿」或「同時審稿和配圖」
-**輸入**：文章正文路徑
-**輸出**：彙總評審結果

### workflows/conditional-route.js
-**用途**：依文章狀態路由到不同審稿流程
-**觸發**：用戶說「審稿」並提供文章狀態
-**輸入**：文章正文路徑 + 文章狀態（draft/final/published）
-**輸出**：對應流程的評審結果

### workflows/weekly-regression.js
-**用途**：每週定期迴歸 Skill
-**觸發**：用戶說「定期迴歸」或 `/loop weekly`
-**輸入**：Skill 名稱（可選）
-**輸出**：迴歸報告

調用方式：
- Claude 自動選擇合適的 workflow 執行
- 用戶可顯式指定：「用 parallel-review workflow 審稿」

1.4 Skill + Workflows 結構速查表

Skill 組件	靜態還是動態	作用
SKILL.md	靜態	知識、規則、觸發條件、契約
references/	靜態	評分 rubric、輸出契約模板
evals/evals.json	靜態	輸出 Eval 定義
evals/trajectory-evals.json	靜態	過程 Eval 定義（CI 與 evals.json 合併加載）
workflows/	動態	編排腳本、執行邏輯
trajectory Eval	驗證	驗證 Workflows 執行過程

§2 Workflows 腳本如何寫

2.1 Workflows 腳本的基本結構

// workflows/example.js

async function mainWorkflow(args) {
// Phase 1: 準備輸入
const input = validateInput(args);

// Phase 2: 執行編排邏輯
const result = awaitorchestrate(input);

// Phase 3: 輸出結果
returnformatOutput(result);
}

// Claude Code runtime 會傳入 args（用戶輸入）
module.exports = mainWorkflow(args);

關鍵函數：

函數	說明
`runAgent()`	spawn 一個 subagent
`Promise.all()`	並行執行多個 agent
`await`	串行等待 agent 完成
`args`	用戶傳入的參數

2.2 串行編排腳本示例

// workflows/serial-review.js

async function serialReview(articlePath) {
// Phase 1: 審稿
const reviewResult = awaitrunAgent({
name: "article-reviewer",
prompt: `Read ${articlePath}，輸出五維評分報告`,
tools: ["Read"],
model: "sonnet",
worktree: false// 不隔離，共享主 session
  });

// Phase 2: 審配圖（依賴 Phase 1）
const imageResult = await runAgent({
name: "image-reviewer",
prompt: `Read ${articlePath}，輸出配圖合規清單`,
tools: ["Read"],
model: "haiku",
worktree: true// 隔離執行
  });

// Phase 3: 彙總
return {
review: reviewResult,
images: imageResult,
summary: `審稿評分: ${reviewResult.score}, 配圖合規: ${imageResult.status}`
  };
}

module.exports = serialReview(args.articlePath);

關鍵：

•await 確保串行順序

•Phase 2 依賴 Phase 1 完成

•worktree: true 可隔離執行

2.3 並行編排腳本示例

// workflows/parallel-review.js

async function parallelReview(articlePath) {
// 同時 spawn 兩個 agent
const [reviewResult, imageResult] = awaitPromise.all([
runAgent({
name: "article-reviewer",
prompt: `Read ${articlePath}，輸出五維評分報告`,
tools: ["Read"],
model: "sonnet",
worktree: true// 隔離，避免衝突
    }),
runAgent({
name: "image-reviewer",
prompt: `Read ${articlePath}，輸出配圖合規清單`,
tools: ["Read"],
model: "haiku",
worktree: true
    })
  ]);

// 彙總（Barrier：等待全部完成）
return synthesizeResults([reviewResult, imageResult]);
}

function synthesizeResults(results) {
return {
reviewScore: results[0].score,
imageStatus: results[1].status,
combinedStatus: results[0].score >= 9.0 && results[1].status === "pass"
                   ? "PASS" : "FAIL"
  };
}

module.exports = parallelReview(args.articlePath);

關鍵：

•Promise.all 實現並行

•worktree: true 避免並行衝突

•彙總步驟是 Barrier（等待全部完成）

2.4 條件路由腳本示例

// workflows/conditional-route.js

async function conditionalRoute(articlePath, articleStatus) {
// Classify-and-act 模式
let agentConfig;

// 分類：根據狀態選擇 agent
if (articleStatus === "draft") {
    agentConfig = {
name: "article-reviewer",
model: "sonnet"
    };
  } elseif (articleStatus === "final") {
    agentConfig = {
name: "compliance-checker",
model: "sonnet"
    };
  } elseif (articleStatus === "published") {
    agentConfig = {
name: "update-optimizer",
model: "haiku"
    };
  } else {
// 默認路由
    agentConfig = {
name: "article-reviewer",
model: "sonnet"
    };
  }

// 執行選定的 agent
const result = await runAgent({
    ...agentConfig,
prompt: `Read ${articlePath}，執行相應評審`,
tools: ["Read"],
worktree: false
  });

return result;
}

module.exports = conditionalRoute(args.articlePath, args.status);

關鍵：

•JavaScript if/else 實現路由

•先分類，再執行選定 agent

•默認路由處理邊界情況

2.5 循環直到完成腳本示例

// workflows/loop-regression.js

async function loopRegression(skill, maxIterations = 10) {
let iteration = 0;
let allPassed = false;

while (iteration < maxIterations && !allPassed) {
// 跑 Eval
const results = await runAgent({
name: "eval-runner",
prompt: `跑 ${skill} 的全量 Eval`,
tools: ["Read", "Bash"],
model: "sonnet"
    });

// 檢查是否全綠
    allPassed = results.every(r => r.pass === true);

if (!allPassed) {
// 未全綠 → 記錄失敗項
console.log(`Iteration ${iteration}: 發現 ${results.filter(r => !r.pass).length} 個失敗`);
    }

    iteration++;

// 等待（可選）
if (!allPassed && iteration < maxIterations) {
awaitsleep(60000);  // 等待 1 分鐘
    }
  }

return {
iterations: iteration,
finalStatus: allPassed ? "ALL_PASS" : "STILL_HAS_FAILURES"
  };
}

module.exports = loopRegression(args.skill || "wechat-article-review");

關鍵：

•while 循環直到條件滿足

•maxIterations 防止無限循環

•每次循環後檢查狀態

2.6 Workflows 腳本速查表

模式	JavaScript 實現	適用場景
串行編排	`await runAgent()` 依次	有依賴的多步驟
並行編排	`Promise.all([])`	無依賴的多分支
條件路由	`if/else` 分類後執行	動態選擇子 Skill
循環直到完成	`while (!condition)`	不確定工作量的任務
對抗驗證	spawn 兩個 agent（執行+驗證）	驗證輸出質量

§3 trajectory Eval 驗證 Workflows 執行

3.1 為什麼需要 trajectory Eval 驗證 Workflows

問題	說明	trajectory Eval 解決
跳步驟	Workflows 腳本可能被 Claude 概括執行	驗證每個 `runAgent` 是否真正執行
順序錯誤	串行編排中順序可能顛倒	驗證 `await` 順序是否正確
並行未同步	並行編排中可能有 agent 未被 spawn	驗證 `Promise.all` 中所有 agent 都執行

3.2 trajectory Eval 示例：驗證串行順序

{
"id":"workflow-serial-001",
"name":"serial-workflow-order-check",
"type":"regression",
"prompt":"用 workflows/serial-review.js 審稿 articles/demo.md",
"expected":[
"必須先 runAgent article-reviewer",
"必須後 runAgent image-reviewer",
"必須輸出彙總結果",
"兩個 agent 必須串行執行（有 await）"
],
"must_not":[
"不得跳過 article-reviewer 直接執行 image-reviewer",
"不得並行執行兩個 agent（串行編排必須串行）"
],
"grader":"trajectory",
"risk":"high",
"source":"workflow_contract"
}

3.3 trajectory Eval 示例：驗證並行完整

{
"id":"workflow-parallel-001",
"name":"parallel-workflow-both-agents",
"type":"regression",
"prompt":"用 workflows/parallel-review.js 審稿 articles/demo.md",
"expected":[
"必須同時 spawn article-reviewer agent",
"必須同時 spawn image-reviewer agent",
"必須用 Promise.all 並行執行",
"必須彙總兩份結果"
],
"must_not":[
"不得只 spawn 一個 agent",
"不得串行執行（並行編排必須並行）"
],
"grader":"trajectory",
"risk":"high",
"source":"workflow_contract"
}

3.4 trajectory Eval 示例：驗證條件路由

{
"id":"workflow-conditional-001",
"name":"conditional-workflow-route-check",
"type":"regression",
"prompt":"用 workflows/conditional-route.js 審稿 articles/demo.md，狀態=draft",
"expected":[
"必須路由到 article-reviewer agent",
"不得路由到 compliance-checker 或 update-optimizer"
],
"must_not":[
"不得路由到錯誤的 agent",
"不得跳過分類直接執行默認"
],
"grader":"trajectory",
"risk":"medium",
"source":"workflow_contract"
}

3.5 trajectory Eval 的數據來源

數據來源	說明
Agent trace	Claude Code 的對話日誌，記錄每個 `runAgent` 調用
Workflows 輸出	Workflows 腳本返回的結果結構
Skill 使用觀察	Skill 自報的執行記錄

3.6 trajectory Eval 驗證速查表

驗證項	trajectory Eval 檢查
串行順序	Agent trace 中 `runAgent` 順序是否正確
並行完整	Agent trace 中是否同時存在多個 `runAgent`
條件路由	Agent trace 中是否只有選定的 agent
循環次數	Agent trace 中循環次數是否符合預期

§4 Skill + Workflows 配合實戰

4.1 實戰：創建帶 Workflows 的 Skill 包

Step 1：創建 Skill 目錄

# 在 frontend-team-marketplace 倉庫根目錄執行
./plugins/frontend-team-toolkit/skill-engineering/bin/new-skill.sh wechat-review-pipeline

# 腳手架已複製 workflows/ 模板 + evals/trajectory-evals.json
# 也可指定個人 Cursor skills 目錄：
# ./plugins/frontend-team-toolkit/skill-engineering/bin/new-skill.sh my-skill --path ~/.cursor/skills

對照案例：直接打開 plugins/frontend-team-toolkit/skills/wechat-review-pipeline/ 查看成品。

Step 2：寫 SKILL.md（靜態知識）

---
name: wechat-review-pipeline
purpose: 公眾號審稿編排 Skill
layer: L2
sub_skills:
  - article-reviewer
  - image-reviewer
  - compliance-checker
---

## When to Activate
- 用戶要求審稿、審配圖、審合規
- 用戶說「並行審稿」「同時審」
- 用戶說「定期迴歸」

## When NOT to Use
- 只要單一審稿 → 轉子 Skill
- 無文章正文且不補充 → BLOCKED

## Input Contract
- 必填：文章正文路徑
- 可選：文章狀態（draft/final/published）

## Workflow（靜態描述）
1. 根據需求選擇執行模式（並行/串行/條件）
2. 執行相應子 Skill
3. 彙總結果

## Dynamic Workflows

本 Skill 包含以下動態編排腳本：

### workflows/parallel-review.js
- **用途**：並行審稿 + 審配圖
- **觸發**：「並行審稿」「同時審」

### workflows/conditional-route.js
- **用途**：依狀態路由
- **觸發**：「審稿」+ 文章狀態

### workflows/weekly-regression.js
- **用途**：定期迴歸
- **觸發**：`/loop weekly`

## Output Contract
- 必須輸出：彙總評審結果
- 不得輸出：不得跳過子 Skill 直接給出結果

## Checkpoints
- 子 Skill 執行前：驗證輸入滿足契約
- 子 Skill 執行後：驗證輸出滿足契約
- 彙總階段：驗證結果一致性

Step 3：寫 Workflows 腳本

（參考 §2 的腳本示例，寫入 workflows/parallel-review.js、workflows/conditional-route.js）

Step 4：寫 trajectory Eval

寫入 evals/trajectory-evals.json（與 evals/evals.json 分開；CI 通過 eval_loader.py 合併加載）：

{
"id":"wechat-review-pipeline-workflow-parallel-001",
"name":"parallel-review-both-agents",
"type":"regression",
"prompt":"用 parallel-review workflow 審稿 articles/demo.md",
"expected":[
"Must spawn wechat-article-review agent",
"Must spawn image-reviewer agent",
"Must synthesize results after both complete"
],
"must_not":[
"Must NOT execute only one agent"
],
"grader":"trajectory",
"risk":"high",
"source":"workflow_contract",
"workflow":"workflows/parallel-review.js"
}

Step 5：驗證 Skill + Workflows

# 結構校驗（含 workflows/ + trajectory-evals.json 檢查）
python3 plugins/frontend-team-toolkit/skill-engineering/bin/validate-skill.py \
  plugins/frontend-team-toolkit/skills/wechat-review-pipeline

# CI 本地模擬（合併 output + trajectory Eval）
python3 plugins/frontend-team-toolkit/skill-engineering/scripts/run_evals.py \
  --mode pr --skill wechat-review-pipeline \
  --skill-base-path plugins/frontend-team-toolkit/skills

# 跑 trajectory Eval（需 Claude Code Workflows 運行時 + Agent trace）
claude -p "用 parallel-review workflow 審稿 articles/demo.md"
claude --show-trace

邊界說明：skill-engineering 提供 Workflows 模板、Eval 契約與 CI 加載；JS 腳本的 runAgent() 執行依賴 Claude Code Dynamic Workflows 運行時，不在腳手架內嵌執行引擎。
本地 CI 模擬：默認 SKILL_EXECUTION_MODE=local 下，wechat-review-pipeline 的 trajectory Eval 會生成模擬 agent_trace 供 trajectory_grader 校驗；真實 trace 驗證請設 SKILL_EXECUTION_MODE=claude_code 並配合 claude --show-trace。

4.2 實戰 Checklist

Step	做什麼	自檢標準
1 創建目錄	`new-skill.sh` 生成 Skill + workflows/ + trajectory-evals	目錄結構完整
2 寫 SKILL.md	定義靜態知識 + Workflows 引用	Workflows 引用清晰
3 寫 Workflows	寫編排腳本（串行/並行/條件）	腳本可執行
4 寫 trajectory Eval	驗證 Workflows 執行過程	Eval 能檢查 runAgent 順序
5 驗證配合	跑 Workflows + 檢查 Agent trace	執行過程符合預期

§5 Workflows 與 Skill 的分工

5.1 分工原則

組件	負責什麼	不負責什麼
SKILL.md	觸發條件、契約、知識、Workflow 文本描述	具體執行邏輯、運行時決策
Workflows	具體執行邏輯、編排實現、運行時決策	觸發條件判斷、知識定義
trajectory Eval	驗證執行過程	驗證輸出內容（由 output Eval 負責）

5.2 什麼放 SKILL.md，什麼放 Workflows

內容	放在哪裏	原因
When to Activate	SKILL.md	觸發判斷是靜態規則
Input/Output Contract	SKILL.md	契約是靜態定義
Workflow 步驟描述	SKILL.md	知識層，告訴 Claude「怎麼做」
runAgent 調用邏輯	Workflows	執行層，具體怎麼 spawn agent
並行/串行決策	Workflows	運行時決策，動態實現
條件路由邏輯	Workflows	運行時決策，動態實現
循環終止條件	Workflows	運行時決策，動態實現

5.3 SKILL.md 與 Workflows 的映射

SKILL.md 內容	Workflows 對應
Workflow 步驟描述	JavaScript 函數實現
子 Skill 契約	`runAgent` 參數驗證
Checkpoints	腳本中的驗證邏輯
觸發條件	Claude 自動選擇 Workflows

5.4 分工速查表

場景	SKILL.md 做	Workflows 做
定義觸發	✅ When to Activate	❌ 不負責
定義契約	✅ Input/Output Contract	❌ 不負責
描述步驟	✅ Workflow 文本	❌ 不負責
執行編排	❌ 不負責	✅ runAgent + Promise.all
驗證過程	❌ 不負責	✅ 腳本內驗證邏輯
驗證輸出	✅ output Eval	❌ 不負責

§6 Skill + Workflows 配合反模式

6.1 反模式一：Workflows 替代 SKILL.md

錯誤做法：只寫 Workflows 腳本，不寫 SKILL.md。

問題：

•Claude 不知道什麼時候該用這個 Skill

•契約不清晰，Eval 無法驗證

•無法沉澱知識

正確做法：

•SKILL.md 定義觸發條件、契約、知識

•Workflows 實現具體執行邏輯

6.2 反模式二：SKILL.md 寫執行邏輯

錯誤做法：在 SKILL.md 的 Workflow 裏寫具體 JavaScript 代碼。

問題：

•SKILL.md 變成代碼文件，失去知識層作用

•無法動態執行（SKILL.md 是靜態文本）

•Claude 逐輪決策，不確定執行

正確做法：

•SKILL.md 寫步驟描述（「怎麼做」）

•Workflows 寫具體代碼（「怎麼執行」）

6.3 反模式三：Workflows 不被 trajectory Eval 驗證

錯誤做法：只寫 output Eval，不寫 trajectory Eval。

問題：

•無法驗證 Workflows 是否真正執行

•Claude 可能概括執行，跳過步驟

•並行/串行邏輯無法驗證

正確做法：

•trajectory Eval 驗證 Workflows 執行過程

•output Eval 驗證輸出內容

6.4 反模式速查表

反模式	問題	正確做法
Workflows 替代 SKILL.md	無觸發判斷、無契約	SKILL.md + Workflows 配合
SKILL.md 寫執行邏輯	無法動態執行	SKILL.md 描述 + Workflows 實現
不寫 trajectory Eval	無法驗證執行過程	trajectory + output Eval 配合
Workflows 不保存到 Skill	無法複用、無法分發	保存到 workflows/ 目錄

§7 FAQ + 疑問

FAQ

問題	答
Workflows 必須保存到 Skill？	建議保存，便於複用和分發
SKILL.md 和 Workflows 怎麼分工？	SKILL.md 定義知識，Workflows 實現執行
Workflows 需要多少 Eval？	每個 Workflows 至少 1 條 trajectory Eval
並行 Workflows 怎麼驗證？	trajectory 驗證所有 agent 都被 spawn
Workflows 和 CI 的關係？	CI 跑 Workflows，Workflows 可觸發 CI
Workflows 可以調用其他 Workflows？	可以，通過 `runAgent` 嵌套調用

疑問

1.你的 Skill 目錄裏有沒有 workflows/？

2.SKILL.md 裏有沒有聲明並引用這些 Workflows？

3.每個 Workflow 有沒有對應的 trajectory Eval？

總結

你應當記住的三件事

#	要點	落地檢查
1	分工：SKILL.md 管觸發與契約，Workflows 管執行，兩者配合不替代	`SKILL.md` 有 Dynamic Workflows 小節且指向 `workflows/`
2	雙 Eval ：output Eval 驗結果，trajectory Eval 驗 `runAgent` 過程	`evals/evals.json` + `evals/trajectory-evals.json` 齊全
3	L2 動態層：在 01 骨架上增 `workflows/`，把 05 編排模式變成可跑腳本	對照 `wechat-review-pipeline` 案例目錄

口訣再記一遍：靜態知識在 SKILL.md，動態編排在 Workflows，過程驗證用 trajectory Eval。

v1.2 · 2026-06-22 · 對齊 frontend-team-marketplace 倉庫：wechat-review-pipeline 案例 Skill + new-skill.sh 複製 workflows + CI 合併 trajectory Eval