---
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="/docs/windsurf/official/06-models-usage" />
  <Card title="团队与排障" description="继续学习 Teams/Enterprise、troubleshooting 和上线前的安全检查。" href="/docs/windsurf/official/07-teams-troubleshooting" />
</Cards>
