Skills、Workflows 與 Hooks

Windsurf 同時提供 Rules、AGENTS.md、Workflows、Skills、Hooks 和 Memories。它們都能“影響 Cascade 怎麼工作”，但啟用方式、上下文成本和維護責任完全不同。

官方 Workflows 頁面明確說：Workflows 是 manual-only，Cascade 不會自動呼叫；如果希望 Cascade 自己判斷何時採用某個 procedure，要使用 Skill。官方 Skills 頁面也給出 rule of thumb：需要 supporting files 且希望模型自動選用，用 Skill；短行為約束用 Rule；總是自己觸發，用 Workflow。

Hooks 是另一類機制：它不是提示詞，也不是能力包，而是在 Cascade 讀檔案、寫檔案、執行命令、處理 prompt 或輸出 response 等關鍵動作前後執行 shell command，用來做日誌、阻斷、校驗和企業治理。

1. 先按啟用方式分類

flowchart TD
    Need["要沉澱一條經驗"] --> Constraint{"是長期行為約束？"}
    Constraint -->|是| Scope{"按目錄生效？"}
    Scope -->|是| Agents["AGENTS.md"]
    Scope -->|否| Rule["Rule"]
    Constraint -->|否| Repeat{"是重複流程？"}
    Repeat -->|手動觸發| Workflow["Workflow"]
    Repeat -->|希望模型自動選用| Resource{"需要指令碼/模板/參考檔案？"}
    Resource -->|是| Skill["Skill"]
    Resource -->|否| RuleManual["manual rule 或簡短 workflow"]
    Need --> Guard{"需要自動阻斷或審計？"}
    Guard -->|是| Hook["Hook"]
    Repeat -->|只是這次背景| Memory["Memory"]

    style Skill fill:#dbeafe,stroke:#2563eb,stroke-width:2px
    style Workflow fill:#dcfce7,stroke:#16a34a,stroke-width:2px
    style Agents fill:#fef3c7,stroke:#d97706,stroke-width:2px
    style Hook fill:#fee2e2,stroke:#dc2626,stroke-width:2px

2. Workflow：手動 slash command runbook

Workflows 是 markdown 檔案。官方說明它們儲存在 .windsurf/workflows/ 目錄中，包含 title、description 和一系列給 Cascade 執行的步驟；儲存後透過 /[name-of-workflow] 呼叫。

官方還說明 Workflow 可以呼叫其他 Workflow。例如一個釋出流程可以拆成：

/release-check
  1. Call /lint-check
  2. Call /build-check
  3. Call /link-check
  4. Summarize risks before deployment

Workflow 的儲存位置：

官方還寫明 workflow 檔案限制為 12000 字元。不要把整套團隊手冊塞進一個 workflow；超過一屏的流程應該拆子 workflow。

Workflow 同名衝突時，官方 precedence 是：

1. System workflow
2. Workspace workflow
3. Global workflow
4. Built-in workflow

這對企業很關鍵。IT 或安全團隊可以部署同名 system workflow，覆蓋使用者本機或專案內版本，用來確保釋出、審計、變更流程不被隨意繞過。

3. Skill：帶材料的能力包

Skill 是資料夾能力包，核心是 SKILL.md。官方說明 Skills 使用 progressive disclosure（漸進披露——預設只把每個 Skill 的 name 和 description 給模型看，模型判斷要用時才載入完整 SKILL.md 和支援檔案，避免一上來把上百個 Skill 全塞進上下文）：預設只把 name 和 description 展示給模型，完整 SKILL.md 和 supporting files 只有在 Cascade 決定呼叫，或你 @mention 時才載入。

手動建立路徑：

.windsurf/skills/<skill-name>/SKILL.md
~/.codeium/windsurf/skills/<skill-name>/SKILL.md

SKILL.md 必須有 YAML frontmatter，至少包含 name 和 description：

---
name: deploy-to-staging
description: Run the staging deployment process with safety checks and rollback notes.
---

## Pre-deployment Checks

1. Check git status.
2. Run tests.
3. Verify required environment variables.

Skill 名稱只能使用小寫字母、數字和連字元。description 很關鍵，因為它幫助 Cascade 判斷什麼時候自動呼叫。

4. Skill 的作用域和相容目錄

官方列出 Skill 的三個主要作用域：

官方還說明，為了 cross-agent compatibility，Windsurf 也會發現 .agents/skills/ 和 ~/.agents/skills/；如果啟用了 Claude Code config reading，還會掃描 .claude/skills/ 和 ~/.claude/skills/。

這對團隊很重要：如果你已經有跨 agent 的 skill 主庫，不需要在 Windsurf 裡複製第二套，先確認 discovery 路徑和許可權策略。

5. 怎麼選

6. Hooks：自動治理，不是提示詞

官方 Hooks 頁面說明，Hooks 會在 Cascade 工作流中的關鍵點自動執行 shell command。每個 hook 透過 stdin 接收 JSON context，執行 Bash、Python、Node 或其他執行檔，然後透過 exit code 和 stdout/stderr 返回結果。

pre-hook 可以用 exit code 2 阻斷動作，所以它適合安全策略和強校驗。

配置位置：

官方說明三層 hooks 會合並執行，順序是 system → user → workspace。如果同一個事件多處配置，不是覆蓋，而是全部執行。

常見事件包括：

• pre_read_code / post_read_code
• pre_write_code / post_write_code
• 命令執行相關事件
• prompt / response 相關事件

適合用 Hooks 的任務：

• 讀取敏感目錄前阻斷。
• 寫入受保護檔案前要求人工處理。
• 寫程式碼後自動執行 formatter、lint 或測試。
• 記錄讀取、寫入、命令、模型和時間戳，滿足審計要求。
• 在企業裝置上 enforce 安全策略。

不適合用 Hooks 的任務：

• 長篇寫作指導。
• 需要模型理解業務語氣的流程。
• 需要 scripts、templates、references 的複雜能力包。

這些應該分別放到 Rule、Workflow 或 Skill。

7. 團隊沉澱順序

推薦順序：

1. 先把穩定硬規則寫進 root AGENTS.md。
2. 把目錄差異寫進子目錄 AGENTS.md。
3. 把按檔案型別觸發的規則寫進 .windsurf/rules/*.md。
4. 把手動觸發的重複步驟寫成 workflow。
5. 把跨專案、帶指令碼和模板的複雜任務寫成 skill。
6. 把自動阻斷、日誌和質量門禁寫成 hook。
7. 把外部系統能力接成 MCP。
8. 定期清理過期 rule、workflow、skill 和 hook，避免 Cascade 被舊約束帶偏。

不要反過來先寫 Skill。很多團隊所謂“Skill”，其實只是三句話行為約束；這種內容寫成 Rule 或 AGENTS.md 更穩定。

本章自檢

完成本章後，用這 5 個問題檢查：

1. Workflow 為什麼不會被 Cascade 自動呼叫？
2. Skill 為什麼適合帶 scripts、templates、checklists 和 references 的任務？
3. description 對 Skill 自動呼叫為什麼關鍵？
4. Hook 和 Workflow 的差異是什麼？
5. 你的團隊規範裡哪些應該移出 always-on rule？

透過標準：你能把一個團隊流程拆成“規則、目錄約定、手動流程、能力包、外部系統能力”，並說明每一塊放在哪裡維護。

官方來源

• Skills —— 官方 Skills 文件，覆蓋 progressive disclosure、建立方式、SKILL.md、required frontmatter、supporting resources、自動/手動呼叫、scope、system skills 和 Skills vs Rules vs Workflows。
• Workflows —— 官方 Workflows 文件，覆蓋 slash command、manual-only、discovery、storage locations、12000 字元限制、system workflows 和 precedence。
• Cascade Hooks —— 官方 Hooks 文件，覆蓋 pre/post hooks、配置層級、exit code 阻斷、輸入 JSON、跨平臺 command 和企業治理。
• Memories & Rules —— 官方 Rules、AGENTS.md、Workflows、Skills、Memories 的對比和推薦。

接下來去哪