> ## Documentation Index
> Fetch the complete documentation index at: https://docs.windsurf.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 技能

> 技能帮助 Cascade 处理复杂的多步任务。

最棘手的工程任务往往不只是写几个好的提示这么简单。它们可能还需要参考脚本、模板、检查列表以及其他辅助文件。技能让你可以把所有这些内容打包成文件夹，供 Cascade 调用 (读取和使用) 。

技能是教会 Cascade 如何稳定、可靠地执行多步工作流的绝佳方式。

Cascade 使用 [**渐进式披露 (progressive disclosure) **](https://agentskills.io/what-are-skills#how-skills-work) 机制：默认情况下，只有技能的 `name` 和 `description` 会显示给 AI 模型。完整的 `SKILL.md` 内容和辅助文件**仅在 Cascade 决定调用该技能时** (或当你 `@mention` 它时) 才会被加载。即使定义了许多技能，这也能让你的上下文窗口保持精简。

有关 Skills 规范的更多详细信息，请访问 [agentskills.io](https://agentskills.io/home)。

<div id="how-to-create-a-skill">
  ## 如何创建技能
</div>

<div id="using-the-ui-easiest">
  ### 使用 UI（最简单的方式）
</div>

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

<div id="manual-creation">
  ### 手动创建
</div>

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

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

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

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

<div id="skillmd-file-format">
  ## SKILL.md 文件格式
</div>

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

<div id="example-skill">
  ### 示例技能
</div>

```markdown theme={null}
---
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]
```

<div id="required-frontmatter-fields">
  ### 必填 Frontmatter 字段
</div>

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

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

<div id="adding-supporting-resources">
  ## 添加辅助资源
</div>

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

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

<div id="invoking-skills">
  ## 技能调用
</div>

<div id="automatic-invocation">
  ### 自动调用
</div>

当你的请求与某个 skill 的描述匹配时，Cascade 会自动调用该 skill，并利用其指令和资源来完成任务。这是使用 skill 的最常见方式——你只需描述自己想做什么，Cascade 就会自动判断应使用哪些相关的 skill。

skill 的 frontmatter 中的 `description` 字段至关重要：它帮助 Cascade 理解在何时应调用该 skill。请撰写能够清晰说明该 skill 的作用，以及在什么情况下应该使用它的描述。

<div id="manual-invocation">
  ### 手动调用
</div>

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

<div id="skill-scopes">
  ## 技能作用域
</div>

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

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

<div id="system-level-skills-enterprise">
  ### 系统级技能 (Enterprise)
</div>

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

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

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

<div id="example-use-cases">
  ## 示例使用场景
</div>

<div id="deployment-workflow">
  ### 部署工作流
</div>

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

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

<div id="code-review-guidelines">
  ### 代码审查指南
</div>

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

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

<div id="testing-procedures">
  ### 测试流程
</div>

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

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

<div id="best-practices">
  ## 最佳实践
</div>

1. **编写清晰的描述**：描述有助于 Cascade 判断何时调用该 skill。要具体说明该 skill 的功能，以及在什么情况下应当使用它。

2. **包含相关资源**：模板、检查清单和示例能让 skill 更有用。思考一下哪些文件能帮助他人完成这项任务。

3. **使用具有描述性的名称**：`deploy-to-staging` 比 `deploy1` 更好。名称应清楚表明该 skill 的作用。

<div id="skills-vs-rules-vs-workflows">
  ## 技能 vs Rules vs Workflows
</div>

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

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

\*\*经验法则：\*\*如果你希望 Cascade 自动选用它，*并且*它需要辅助文件，就用技能。如果它只是简短的行为约束，就用 Rule。如果你总是想自己手动触发它，就用 Workflow。

<div id="related-documentation">
  ## 相关文档
</div>

如果 Skills 不是你想要的内容，可以查看这些其他 Cascade 功能：

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