designing-workflow-skills

設計工作流程技能

透過遵循結構化模式而非散文，建立能可靠執行的工作流程技能。

基本原則

<essential_principles>

<principle name="description-is-the-trigger">
description 欄位是唯一控制技能何時啟動的關鍵。

Claude 僅根據 frontmatter 的 description 決定是否載入技能。SKILL.md 的內文（包括「使用時機」與「不適用時機」章節）只有在技能已啟動後才會被讀取。請將觸發關鍵字、使用案例與排除條件放在 description 中。無論內文寫得多好，錯誤的 description 會導致錯誤啟動或遺漏啟動。

「使用時機」與「不適用時機」章節仍有其用途：它們在技能啟動後限縮 LLM 的行為範圍。「不適用時機」應明確指出替代方案：例如「簡單的模式比對請使用 Semgrep」，而非「不適用於簡單任務」。
</principle>

<principle name="numbered-phases">
階段必須編號，並附有進入與退出條件。

未編號的散文式說明會導致不可靠的執行順序。每個階段都需要：

• 編號（Phase 1, Phase 2, ...）
• 進入條件（開始前必須滿足的條件）
• 編號的行動步驟（要做什麼）
• 退出條件（如何知道已完成）
  </principle>

<principle name="tools-match-executor">
工具必須與執行者匹配。

技能使用 frontmatter 中的 allowed-tools:。代理使用 frontmatter 中的 tools:。子代理從其 subagent_type 取得工具。切勿列出該元件未使用的工具。對於有專用工具（Glob、Grep、Read、Write、Edit）的操作，切勿使用 Bash。

大多數技能與代理應在工具清單中包含 TodoRead 與 TodoWrite——這些工具可在多步驟執行期間進行進度追蹤，即使技能未明確管理任務也很有用。
</principle>

<principle name="progressive-disclosure">
漸進式揭露是結構性的，而非選擇性的。

SKILL.md 保持在 500 行以內。它只包含 LLM 每次呼叫所需的內容：原則、路由、快速參考與連結。詳細模式放在 references/。逐步流程放在 workflows/。僅限一層深度——不要有參考鏈。
</principle>

<principle name="scalable-tool-patterns">
指令必須產生可擴展的工具呼叫模式。

每個工作流程指令在執行時都會轉換為工具呼叫。如果工作流程要搜尋 N 個檔案中的 M 個模式，請合併為一個正則表達式——而不是 N×M 次呼叫。如果工作流程要為每個項目產生子代理，請使用批次處理——而不是每個檔案一個子代理。套用 10,000 檔案測試：在腦中對大型儲存庫執行工作流程，並確認工具呼叫次數維持在可控範圍。請參閱 anti-patterns.md 的 AP-18 與 AP-19。
</principle>

<principle name="degrees-of-freedom">
將指令的具體程度與任務的脆弱性匹配。

並非每個步驟都需要相同程度的規範。請根據每個步驟進行校準：

• 低自由度（精確指令，無變化）：脆弱操作——資料庫遷移、加密、破壞性動作。「請執行此腳本。」
• 中自由度（含參數的虛擬碼）：可接受變化的首選模式。「使用此範本並依需求自訂。」
• 高自由度（啟發式與判斷）：可變任務——程式碼審查、探索、文件。「分析結構並提出改進建議。」

一個技能可以混合不同自由度。安全稽核技能可能在探索階段使用高自由度（「探索程式碼庫中的驗證模式」），而在報告階段使用低自由度（「請使用此嚴重性分類表」）。
</principle>

</essential_principles>

使用時機

• 設計具有多步驟工作流程或階段執行的新技能
• 建立需要在多個獨立任務之間路由的技能
• 建構具有安全閘門（破壞性動作需確認）的技能
• 組織使用子代理或任務追蹤的技能
• 審查或重構現有工作流程技能的品質
• 決定如何在 SKILL.md、references/ 與 workflows/ 之間拆分內容

不適用時機

• 簡單的單一用途技能，無工作流程（僅需指引）——直接撰寫 SKILL.md
• 撰寫技能的實際領域內容（此技能教導結構，而非領域專業知識）
• 外掛程式設定（plugin.json、hooks、commands）——請使用外掛開發指南
• 非技能的 Claude Code 開發——此技能專門針對技能架構

模式選擇

為你的技能結構選擇正確的模式。請閱讀 workflow-patterns.md 中的完整模式說明。

技能有多少條不同的路徑？
|
+-- 單一路徑，每次都相同
|   +-- 是否包含破壞性動作？
|       +-- 是 -> 安全閘門模式
|       +-- 否 -> 線性進展模式
|
+-- 從共享設定出發的多條獨立路徑
|   +-- 路由模式
|
+-- 多個相依步驟依序進行
    +-- 步驟之間是否有複雜的相依性？
        +-- 是 -> 任務驅動模式
        +-- 否 -> 序列管線模式

模式摘要

模式	使用時機	主要特徵
路由	從共享輸入出發的多個獨立任務	路由表將意圖對應至工作流程檔案
序列管線	相依步驟，每個步驟饋入下一個	自動偵測可從部分進度繼續
線性進展	單一路徑，每次相同	編號階段，附有進入/退出條件
安全閘門	破壞性/不可逆動作	執行前有兩個確認閘門
任務驅動	複雜相依性，可容忍部分失敗	TaskCreate/TaskUpdate 搭配相依性追蹤

結構解剖

無論採用何種模式，每個工作流程技能都需要這個骨架：

---
name: kebab-case-name
description: "第三人稱描述，包含觸發關鍵字——這是 Claude 決定啟動技能的方式"
allowed-tools: Tool1 Tool2 Tool3  # 以空格分隔的工具名稱清單
# 選用欄位——完整參考請見 tool-assignment-guide.md：
# disable-model-invocation: true    # 僅使用者可呼叫（Claude 不可）
# user-invocable: false             # 僅 Claude 可呼叫（從 / 選單隱藏）
# context: fork                     # 在隔離的子代理上下文中執行
# agent: Explore                    # 子代理類型（需 context: fork）
# model: [model-name]               # 技能啟用時切換模型
# argument-hint: "[filename]"       # 自動完成時顯示的提示
---

# 標題

## 基本原則
[3-5 條不可妥協的規則，附 WHY 解釋]

## 使用時機
[4-6 個具體情境——在啟動後限縮行為範圍]

## 不適用時機
[3-5 個情境，附明確替代方案——在啟動後限縮行為範圍]

## [模式專屬章節]
[路由表 / 管線步驟 / 階段清單 / 閘門]

## 快速參考
[常用資訊的簡潔表格]

## 參考索引
[所有支援檔案的連結]

## 成功條件
[輸出驗證的檢查清單]

技能支援三種字串替換：以錢字符號前綴的變數用於引數與工作階段 ID，以及驚嘆號-反引號語法用於 shell 前置處理。技能載入器會在 Claude 看到檔案之前處理這些替換——即使在程式碼區塊內也是如此——因此切勿在文件文字中使用原始語法。完整變數參考與使用指引請見 tool-assignment-guide.md。

反模式快速參考

最常見的錯誤。完整目錄（含修正前後對比）請見 anti-patterns.md。

AP	反模式	一行修正
AP-1	缺少目標/反目標	新增「使用時機」與「不適用時機」章節
AP-2	單一 SKILL.md 過大（>500 行）	拆分至 references/ 與 workflows/
AP-3	參考鏈（A -> B -> C）	所有檔案距離 SKILL.md 僅一跳
AP-4	硬編碼路徑	所有內部路徑使用 {baseDir}
AP-5	損壞的檔案參考	提交前驗證每個路徑是否可解析
AP-6	未編號的階段	每個階段編號並附上進入/退出條件
AP-7	缺少退出條件	為每個階段定義「完成」的意義
AP-8	無驗證步驟	在每個工作流程結尾加入驗證
AP-9	模糊的路由關鍵字	每個工作流程路由使用獨特的關鍵字
AP-11	工具選擇錯誤	使用 Glob/Grep/Read，而非 Bash 替代方案
AP-12	工具權限過大	移除未實際使用的工具
AP-13	模糊的子代理提示	指定要分析、尋找與回傳的內容
AP-15	傾印參考資料	教導判斷力，而非原始文件
AP-16	缺少合理化拒絕	為稽核技能加入「應拒絕的合理化說詞」
AP-17	無具體範例	為關鍵指令展示輸入 -> 輸出
AP-18	笛卡兒乘積工具呼叫	將模式合併為單一正則表達式，一次 grep，再過濾
AP-19	無限制的子代理產生	將項目分批處理，每批一個子代理
AP-20	description 摘要了工作流程	description = 僅觸發條件，絕非工作流程步驟

AP-10（無預設/後備路由）、AP-14（代理缺少工具理由）與 AP-20（description 摘要工作流程）收錄於完整目錄。AP-20 因其高影響力而包含在上述快速參考中。

工具指派快速參考

將你的元件類型對應至正確的工具集。完整指南請見 tool-assignment-guide.md。

元件類型	典型工具
唯讀分析技能	Read, Glob, Grep, TodoRead, TodoWrite
互動分析技能	Read, Glob, Grep, AskUserQuestion, TodoRead, TodoWrite
程式碼生成技能	Read, Glob, Grep, Write, Bash, TodoRead, TodoWrite
管線技能	Read, Write, Glob, Grep, Bash, AskUserQuestion, Task, TaskCreate, TaskList, TaskUpdate, TodoRead, TodoWrite
唯讀代理	Read, Grep, Glob, TodoRead, TodoWrite
行動代理	Read, Grep, Glob, Write, Bash, TodoRead, TodoWrite

關鍵規則：

• 使用 Glob（而非 find）、Grep（而非 grep）、Read（而非 cat）——始終優先使用專用工具
• 技能使用 allowed-tools:——代理使用 tools:
• 僅列出指令實際參考的工具
• 唯讀元件不應包含 Write 或 Bash

應拒絕的合理化說詞

設計工作流程技能時，拒絕這些捷徑：

合理化說詞	為何錯誤
「下一個階段很明顯」	LLM 不會從散文推斷順序。請為階段編號。
「退出條件是隱含的」	隱含的條件就是被跳過的條件。請明確寫出。
「一個大的 SKILL.md 比較簡單」	寫起來簡單，執行起來糟糕。超過 500 行 LLM 會失去焦點。
「description 不太重要」	description 是技能觸發的方式。錯誤的 description 會導致錯誤啟動或遺漏啟動。
「Bash 什麼都能做」	Bash 檔案操作很脆弱。專用工具在編碼、權限與格式化上處理得更好。
「LLM 會自己找出工具」	它會猜錯。請為每個操作指定確切的工具。
「細節之後再加」	不完整的技能上線時就是不完整。請在撰寫前完整設計。

參考索引

檔案	內容
workflow-patterns.md	5 種模式，附結構骨架與範例
anti-patterns.md	20 種反模式，附修正前後對比
tool-assignment-guide.md	工具選擇矩陣、元件比較、子代理指引
progressive-disclosure-guide.md	內容拆分規則、500 行規則、大小指引

工作流程	用途
design-a-workflow-skill.md	從範圍界定到自我審查的 6 階段建立流程
review-checklist.md	結構化自我審查檢查清單，確保提交就緒

成功條件

一個設計良好的工作流程技能：

• [ ] 包含「使用時機」與「不適用時機」章節
• [ ] 使用可識別的模式（路由、管線、線性、安全閘門或任務驅動）
• [ ] 所有階段皆編號並附有進入與退出條件
• [ ] 僅列出實際使用的工具（最小權限）
• [ ] SKILL.md 保持在 500 行以內，細節放在 references/workflows
• [ ] 無硬編碼路徑（使用 {baseDir}）
• [ ] 無損壞的檔案參考
• [ ] 無參考鏈（所有連結距離 SKILL.md 僅一跳）
• [ ] 在工作流程結尾包含驗證步驟
• [ ] description 能正確觸發（第三人稱、特定關鍵字）
• [ ] 關鍵指令包含具體範例
• [ ] 基本原則解釋 WHY，而不只是 WHAT