---
title: "Skills、Workflows 與 Hooks"
description: "整理 Windsurf Skills、Workflows、Hooks、Rules、AGENTS.md 和 Memories 的團隊沉澱邊界。"
verifiedAt: "2026-05-09"
---

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，用來做日誌、阻斷、校驗和企業治理。

> [!TIP]
> **閱讀目標**：讀完本章，你應該能把團隊經驗分別落到 Rules、AGENTS.md、Workflow、Skill 或 Memory，而不是塞進一個大提示詞。

## 1. 先按啟用方式分類

| 機制 | 結構 | 啟用方式 | 適合什麼 |
| --- | --- | --- | --- |
| Rules | 單個 `.md`，可帶 frontmatter | `always_on`、`glob`、`model_decision`、`manual` | 行為約束、編碼風格、專案限制 |
| AGENTS.md | 普通 Markdown | 由目錄位置自動推斷 | 目錄職責、架構約定、分層規範 |
| Workflows | `.windsurf/workflows/*.md` | 手動 `/workflow-name` | PR review、釋出、測試、格式化 runbook |
| Skills | 資料夾 + `SKILL.md` + supporting files | 模型自動選擇或 `@mention` | 需要指令碼、模板、checklist、參考檔案的複雜任務 |
| Hooks | `hooks.json` + shell command | Cascade action 前後自動觸發 | 審計、阻斷敏感檔案、執行校驗、企業治理 |
| Memories | 本機 workspace 狀態 | 相關時自動檢索 | 一次性事實、臨時背景 |

```mermaid
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。例如一個釋出流程可以拆成：

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

Workflow 的儲存位置：

| Scope | Location | 說明 |
| --- | --- | --- |
| Workspace | `.windsurf/workflows/*.md` | 當前 workspace、子目錄或 git root 父目錄；可隨 repo 提交 |
| Global | `~/.codeium/windsurf/global_workflows/*.md` | 本機所有 workspaces 可用，不提交 |
| Built-in | Windsurf 管理 | 例如內建 `/plan` |
| System | macOS `/Library/Application Support/Windsurf/workflows/*.md`、Linux `/etc/windsurf/workflows/*.md`、Windows `C:\ProgramData\Windsurf\workflows\*.md` | Enterprise 由 IT 部署，只讀 |

官方還寫明 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` 時才載入。

手動建立路徑：

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

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

```md
---
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 的三個主要作用域：

| Scope | Location | Availability |
| --- | --- | --- |
| Workspace | `.windsurf/skills/` | 當前 workspace 可用，可隨 repo 提交 |
| Global | `~/.codeium/windsurf/skills/` | 本機所有 workspaces 可用，不提交 |
| System | macOS `/Library/Application Support/Windsurf/skills/`、Linux/WSL `/etc/windsurf/skills/`、Windows `C:\ProgramData\Windsurf\skills\` | Enterprise 全域性部署，只讀 |

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

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

<details>
<summary>深讀：Progressive disclosure 解決的不是“省 token”這麼簡單</summary>

如果把所有流程、指令碼說明、模板和 checklist 都寫進 always-on rule，Cascade 每次對話都會揹著一大包上下文，容易互相干擾。Skill 的 progressive disclosure 讓模型先只看 name 和 description，只有任務匹配時才載入完整材料。

這意味著 Skill 的 `description` 不是普通簡介，而是觸發條件。寫得太泛會誤觸發，寫得太窄會用不上。商業專案裡應該把 description 當成“什麼時候應該使用這個能力”的判斷句來寫。
</details>

## 5. 怎麼選

| 需求 | 推薦機制 | 理由 |
| --- | --- | --- |
| “所有任務先讀專案規則，禁止直接部署” | root `AGENTS.md` | 目錄範圍自動生效 |
| “測試檔案必須 mock 外部 API” | workspace rule + `glob` | 只在測試檔案觸發 |
| “每次釋出前按固定順序檢查” | Workflow | 手動 `/release-check` 可控 |
| “原始碼包脫敏、壓縮、生成報告” | Skill | 需要指令碼、模板和 checklist |
| “記住這次專案背景” | Memory | 一次性上下文，不當團隊規範 |
| “查詢 GitHub issue 或資料庫 schema” | MCP | 外部系統能力，不是規則或流程 |
| “Cascade 寫程式碼後自動跑 formatter 或測試” | Hook | 動作後自動執行，適合驗證 |
| “禁止 Cascade 讀取 secrets 目錄” | Hook + `.codeiumignore` | ignore 控制索引，pre-hook 可阻斷動作 |

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

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

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

配置位置：

| Scope | Location | 適合 |
| --- | --- | --- |
| System | macOS `/Library/Application Support/Windsurf/hooks.json`、Linux/WSL `/etc/windsurf/hooks.json`、Windows `C:\ProgramData\Windsurf\hooks.json` | 企業統一策略 |
| User | Windsurf IDE `~/.codeium/windsurf/hooks.json`、JetBrains Plugin `~/.codeium/hooks.json` | 個人日誌和偏好 |
| Workspace | `.windsurf/hooks.json` | 專案級校驗，可隨儲存庫版本控制 |

官方說明三層 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](https://docs.windsurf.com/windsurf/cascade/skills) —— 官方 Skills 文件，覆蓋 progressive disclosure、建立方式、`SKILL.md`、required frontmatter、supporting resources、自動/手動呼叫、scope、system skills 和 Skills vs Rules vs Workflows。
- [Workflows](https://docs.windsurf.com/windsurf/cascade/workflows) —— 官方 Workflows 文件，覆蓋 slash command、manual-only、discovery、storage locations、12000 字元限制、system workflows 和 precedence。
- [Cascade Hooks](https://docs.windsurf.com/windsurf/cascade/hooks) —— 官方 Hooks 文件，覆蓋 pre/post hooks、配置層級、exit code 阻斷、輸入 JSON、跨平臺 command 和企業治理。
- [Memories & Rules](https://docs.windsurf.com/windsurf/cascade/memories) —— 官方 Rules、AGENTS.md、Workflows、Skills、Memories 的對比和推薦。

## 接下來去哪

<Cards>
  <Card title="模型、用量與額度" description="繼續核對模型選擇、usage、quota 和 pricing 這類需要回官方頁面確認的事實。" href="/zh-Hant/docs/windsurf/official/06-models-usage" />
  <Card title="團隊與排障" description="繼續學習 Teams/Enterprise、troubleshooting 和上線前的安全檢查。" href="/zh-Hant/docs/windsurf/official/07-teams-troubleshooting" />
</Cards>
