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 的对比和推荐。

接下来去哪