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

# 技能

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

最复杂的工程任务，往往不只是靠好的提示就能完成。它们可能还需要参考脚本、模板、检查清单以及其他辅助文件。技能让你能够把这些内容整合到文件夹中，供 Cascade 调用 (读取并使用) 。

技能是帮助 Cascade 稳定执行多步骤工作流程的绝佳方式。

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

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

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

<div id="using-the-ui-easiest">
  ### 使用 UI (最简单)
</div>

1. 打开 Cascade 面板
2. 点击面板右上角的三个点，打开自定义菜单
3. 点击 `技能` 部分
4. 点击 `+ 工作区` 创建工作区 (项目专属) 技能，或点击 `+ 全局` 创建全局技能
5. 为技能命名 (仅限使用小写字母、数字和连字符)

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

**工作区技能 (项目专用) ：**

1. 创建目录：`.windsurf/skills/<skill-name>/`
2. 添加一个带有 YAML frontmatter 的 `SKILL.md` 文件

**全局技能 (在所有工作区中均可用) ：**

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

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

每个技能都需要一个 `SKILL.md` 文件，其中包含 YAML frontmatter，用于定义该技能的元数据：

<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**：展示给模型的简要说明，用于帮助其判断何时调用该技能

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

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

将所有辅助文件放在 skill 文件夹中，与 `SKILL.md` 放在同一目录下。调用该 skill 时，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>

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

你的技能 frontmatter 中的 `description` 字段至关重要：它能帮助 Cascade 理解应在何时调用该技能。请编写清晰说明技能作用及其适用时机的描述。

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

你始终可以在 Cascade 输入框中键入 `@skill-name`，以显式启用某个技能。当你想确保使用特定技能，或者想调用某个可能不会因你的请求而自动触发的技能时，这种方式就很有用。

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

| 作用域             | 位置                            | 可用性                  |
| --------------- | ----------------------------- | -------------------- |
| 工作区             | `.windsurf/skills/`           | 仅限当前工作区。随你的代码仓库一同提交。 |
| 全局              | `~/.codeium/windsurf/skills/` | 你设备上的所有工作区。不会提交。     |
| 系统 (Enterprise) | 因操作系统而异 (见下文)                 | 所有工作区，由 IT 部署。只读。    |

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

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

企业版组织可以部署系统级技能，这些技能在所有工作区中均可用，且终端用户无法修改：

| 操作系统      | 路径                                              |
| --------- | ----------------------------------------------- |
| 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 判断何时调用该技能。请具体说明该技能的作用，以及适用场景。

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

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

<div id="skills-vs-rules-vs-workflows">
  ## 技能 vs 规则 vs 工作流程
</div>

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

|                       | 技能                           | 规则                                                 | 工作流程                           |
| --------------------- | ---------------------------- | -------------------------------------------------- | ------------------------------ |
| **Purpose**           | 带辅助文件的多步骤流程                  | 行为准则 (“应如何行事”)                                     | 用于重复性任务的提示模板                   |
| **Structure**         | 包含 `SKILL.md` 和任意资源文件的文件夹    | 带有 frontmatter 的单个 `.md` 文件                        | 单个 `.md` 文件                    |
| **Invocation**        | 由模型决定 (渐进式披露) 或通过 `@mention` | `always_on` / `glob` / `model_decision` / `manual` | 仅可**手动**通过 `/slash-command` 调用 |
| **In system prompt?** | 否——调用前只包含名称和描述               | 取决于激活模式                                            | 否——会列为可用命令                     |
| **Best for**          | 需要脚本/模板的部署、代码审查和测试流程         | 编码风格、项目规范、约束条件                                     | 需要你显式触发的一次性操作手册                |

\*\*经验法则：\*\*如果 Cascade 应该自动拾取它，*并且*它需要辅助文件，就使用技能。如果它是简短的行为约束，就使用规则。如果你希望始终由自己手动触发，就使用工作流程。

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

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

* **[工作流程](./workflows)** - 通过斜杠命令调用可复用的 Markdown 工作流程，自动化重复性任务
* **[AGENTS.md](./agents-md)** - 提供目录作用域的指示，并根据文件位置自动生效
* **[记忆与规则](./memories)** - 通过自动生成的记忆和用户定义的规则，在对话之间持续保留上下文