Cascade 技能

最棘手的工程任务往往不只是写几个好的提示这么简单。它们可能还需要参考脚本、模板、检查列表以及其他辅助文件。技能让你可以把所有这些内容打包成文件夹，供 Cascade 调用 (读取和使用) 。技能是教会 Cascade 如何稳定、可靠地执行多步工作流的绝佳方式。 Cascade 使用 渐进式披露 (progressive disclosure) 机制：默认情况下，只有技能的 name 和 description 会显示给 AI 模型。完整的 SKILL.md 内容和辅助文件仅在 Cascade 决定调用该技能时 (或当你 @mention 它时) 才会被加载。即使定义了许多技能，这也能让你的上下文窗口保持精简。有关 Skills 规范的更多详细信息，请访问 agentskills.io。

如何创建技能

使用 UI（最简单的方式）

打开 Cascade 面板
点击面板右上角的三个点以打开 Customizations 菜单
点击 Skills 部分
点击 + Workspace 以创建工作区（针对特定项目的）技能，或点击 + Global 以创建全局技能
为该技能命名（仅使用小写字母、数字和连字符）

手动创建

工作区 Skill（针对特定项目）：

创建目录：.windsurf/skills/<skill-name>/
添加带有 YAML 头部信息的 SKILL.md 文件

全局 Skill（在所有工作区可用）：

创建目录：~/.codeium/windsurf/skills/<skill-name>/
添加带有 YAML 头部信息的 SKILL.md 文件

SKILL.md 文件格式

每个 skill 都需要一个 SKILL.md 文件，其 YAML frontmatter 中包含该 skill 的元数据：

示例技能

---
name: deploy-to-production
description: Guides the deployment process to production with safety checks
---

## Pre-deployment Checklist
1. Run all tests
2. Check for uncommitted changes
3. Verify environment variables

## Deployment Steps
Follow these steps to deploy safely...

[Reference supporting files in this directory as needed]

必填 Frontmatter 字段

name：技能的唯一标识符（会显示在 UI 中，并用于 @ 提及）
description：提供给 AI 模型的简要说明，帮助其判断在何时调用该技能

有效名称示例：deploy-to-staging、code-review、setup-dev-environment

添加辅助资源

将任何辅助文件放在技能文件夹中，与 SKILL.md 放在一起。这些文件会在调用该技能时供 Cascade 访问：

.windsurf/skills/deploy-to-production/
├── SKILL.md
├── deployment-checklist.md
├── rollback-procedure.md
└── config-template.yaml

技能调用

自动调用

当你的请求与某个 skill 的描述匹配时，Cascade 会自动调用该 skill，并利用其指令和资源来完成任务。这是使用 skill 的最常见方式——你只需描述自己想做什么，Cascade 就会自动判断应使用哪些相关的 skill。 skill 的 frontmatter 中的 description 字段至关重要：它帮助 Cascade 理解在何时应调用该 skill。请撰写能够清晰说明该 skill 的作用，以及在什么情况下应该使用它的描述。

手动调用

你可以随时在 Cascade 的输入框中输入 @skill-name 来显式激活某个 skill。当你想确保使用某个特定的 skill，或者想调用一个可能不会因你的请求而自动触发的 skill 时，这会非常有用。

技能作用域

作用域	位置	可用范围
工作区	`.windsurf/skills/`	仅当前工作区。随代码仓库一同提交。
全局	`~/.codeium/windsurf/skills/`	当前机器上的所有工作区。不随代码仓库提交。
系统 (Enterprise)	特定于操作系统 (见下文)	所有工作区，由 IT 部署。只读。

为实现跨代理兼容性，Windsurf 也会在 .agents/skills/ 和 ~/.agents/skills/ 中发现技能。如果你已启用 Claude Code 配置读取，.claude/skills/ 和 ~/.claude/skills/ 也会被扫描。

系统级技能 (Enterprise)

Enterprise 组织可以部署适用于所有工作区且终端用户无法修改的技能：

OS	Path
macOS	`/Library/Application Support/Windsurf/skills/`
Linux/WSL	`/etc/windsurf/skills/`
Windows	`C:\ProgramData\Windsurf\skills\`

每个技能都是一个子目录，其中包含一个 SKILL.md 文件，与工作区技能相同。

示例使用场景

部署工作流

创建一个包含部署脚本、环境配置和回滚方案的 Skill：

.windsurf/skills/deploy-staging/
├── SKILL.md
├── pre-deploy-checks.sh
├── environment-template.env
└── rollback-steps.md

代码审查指南

包含风格指南、安全检查清单和审查模板：

.windsurf/skills/code-review/
├── SKILL.md
├── style-guide.md
├── security-checklist.md
└── review-template.md

测试流程

汇总测试模板、覆盖率要求和 CI/CD 配置：

.windsurf/skills/run-tests/
├── SKILL.md
├── test-template.py
├── coverage-config.json
└── ci-workflow.yaml

最佳实践

编写清晰的描述：描述有助于 Cascade 判断何时调用该 skill。要具体说明该 skill 的功能，以及在什么情况下应当使用它。
包含相关资源：模板、检查清单和示例能让 skill 更有用。思考一下哪些文件能帮助他人完成这项任务。
使用具有描述性的名称：deploy-to-staging 比 deploy1 更好。名称应清楚表明该 skill 的作用。

技能 vs Rules vs Workflows

这三者都可以用来自定义 Cascade，但它们在结构、调用方式和上下文成本上有所不同：

	技能	Rules	Workflows
用途	带辅助文件的多步骤流程	行为准则（“如何表现”）	用于可重复任务的提示模板
结构	包含 `SKILL.md` 和任意资源文件的文件夹	带 frontmatter 的单个 `.md` 文件	单个 `.md` 文件
调用方式	由模型决定（渐进式披露）或通过 `@mention` 调用	`always_on` / `glob` / `model_decision` / `manual`	仅支持手动，通过 `/slash-command`
会出现在系统提示词中吗？	不会——调用前只包含名称和描述	取决于激活模式	不会——仅列为可用命令
最适合	需要脚本/模板的部署、代码审查、测试流程	编码风格、项目约定、约束条件	由你显式触发的一次性操作手册

**经验法则：**如果你希望 Cascade 自动选用它，并且它需要辅助文件，就用技能。如果它只是简短的行为约束，就用 Rule。如果你总是想自己手动触发它，就用 Workflow。如果 Skills 不是你想要的内容，可以查看这些其他 Cascade 功能：

Workflows - 使用可复用的 Markdown 工作流，通过斜杠命令触发，实现重复性任务的自动化
AGENTS.md - 提供以目录为作用域的指令，根据文件位置自动生效
Memories & Rules - 通过自动生成的记忆和用户自定义规则，在多轮对话之间持久保留上下文

编辑器

Cascade

账户

上下文感知

故障排查

安全性

技能

如何创建技能

使用 UI（最简单的方式）

手动创建

SKILL.md 文件格式

示例技能

必填 Frontmatter 字段

添加辅助资源

技能调用

自动调用

手动调用

技能作用域

系统级技能 (Enterprise)

示例使用场景

部署工作流

代码审查指南

测试流程

最佳实践

技能 vs Rules vs Workflows

​如何创建技能

​使用 UI（最简单的方式）

​手动创建

​SKILL.md 文件格式

​示例技能

​必填 Frontmatter 字段

​添加辅助资源

​技能调用

​自动调用

​手动调用

​技能作用域

​系统级技能 (Enterprise)

​示例使用场景

​部署工作流

​代码审查指南

​测试流程

​最佳实践

​技能 vs Rules vs Workflows

​相关文档

如何创建技能

使用 UI（最简单的方式）

手动创建

SKILL.md 文件格式

示例技能

必填 Frontmatter 字段

添加辅助资源

技能调用

自动调用

手动调用

技能作用域

系统级技能 (Enterprise)

示例使用场景

部署工作流

代码审查指南

测试流程

最佳实践

技能 vs Rules vs Workflows

相关文档