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

# 技能

> 通过向代码仓库提交 SKILL.md 文件，教会 Devin 可复用的流程

<div id="what-are-skills">
  ## 什么是技能？
</div>

技能是你提交到代码仓库中的 `SKILL.md` 文件，用来教会 Devin **可复用的流程**——任何你希望 Devin 始终一致遵循的可重复工作流。无论是在打开 PR 之前测试你的应用、部署到某个环境、研究代码库，还是为新服务搭建脚手架——只要你能把它写成分步说明，就能把它变成一个技能。

它们遵循开放的 [Agent Skills standard](https://agentskills.io/specification)，因此同一个技能文件可以在多个 AI 编码工具之间通用。

请将技能文件放在代码仓库中的 `.agents/skills/<skill-name>/SKILL.md` 路径下。Devin 会自动在你所有已连接的代码仓库中发现这些文件。完整的文件格式参考请参见 [Agent Skills specification](https://agentskills.io/specification)。

<div id="why-skills-matter">
  ## 为什么技能很重要
</div>

如果没有技能，Devin 在每次会话中都必须从头摸索工作流程。有了技能后，你只需定义一次流程，Devin 之后每次都能稳定地照着执行。当你的某个工作流程符合以下情况时，技能就特别有用：

* **每次都应以相同方式完成** — 例如测试检查清单、部署步骤、评审流程
* **需要仓库级知识** — 例如要启动哪些服务、使用哪些端口、运行哪些命令
* **能从动态上下文中受益** — 例如在调用时引入 git diff、分支名称或环境信息

<div id="devin-suggests-skills-automatically">
  ## Devin 会自动推荐技能
</div>

Devin 可以自动为你推荐技能。在一次会话中，当 Devin 测试你的应用，或在你的设置中了解到新的信息后，它会建议创建或更新一个技能，以记录这些知识。你会在会话时间线中看到一条建议，其中包括：

* 学到内容的摘要 (例如“how to start the backend with Docker”)
* 建议的 `SKILL.md` 文件内容
* 一个用于将该技能提交到代码仓库的 **"Create PR"** 按钮

随着时间推移，Devin 会在你的代码仓库中逐步构建起一个技能库，涵盖如何运行、测试和部署你的应用。

<div id="examples">
  ## 示例
</div>

<div id="testing-before-opening-a-pr">
  ### 在打开 PR 之前进行测试
</div>

一个用于指示 Devin 如何在创建拉取请求之前验证 Next.js 应用的技能：

```markdown theme={null}
---
name: test-before-pr
description: Run the local dev server and verify pages before opening any PR that touches frontend code.
---

## Setup

1. Install dependencies: `npm install`
2. Start the database: `docker-compose up -d postgres`
3. Run migrations: `npx prisma migrate dev`
4. Start the dev server: `npm run dev`
5. Wait for "Ready on http://localhost:3000"

## Verify

1. Read the git diff to identify which pages changed
2. Open each affected page in the browser
3. Check for: console errors, layout issues, broken links
4. Screenshot each page at desktop (1280px) and mobile (375px) widths

## Before Opening the PR

1. Run `npm run lint` and fix any issues
2. Run `npm test` and confirm all tests pass
3. Include screenshots in the PR description
```

<div id="deploying-to-an-environment">
  ### 部署到某个环境
</div>

一个使用目标环境参数来部署应用，并支持动态内容注入的技能：

```markdown theme={null}
---
name: deploy
description: 将应用部署到目标环境并运行冒烟测试。
argument-hint: <environment>
triggers: ["user"]
---

## Deploy

1. Make sure you are on the correct branch for this deploy
2. Run `./scripts/deploy.sh $0`
3. Wait for the deploy script to complete successfully

## Verify

1. Curl `https://$0.example.com/health` and confirm a 200 response
2. Run the smoke test suite: `npm run test:smoke -- --env=$0`
3. Report the deployment URL and test results

## Current context

- Branch: !`git branch --show-current`
- Last commit: !`git log --oneline -1`
```

使用 `@skills:deploy staging` 调用时，`staging` 会替换 `$ARGUMENTS` 和 `$0`，而 `` !`command` `` 块会插入实时的 git 信息。`triggers: ["user"]` 字段可确保 Devin 仅在你明确要求时才运行此技能——它不会自动启用。

<div id="investigating-a-part-of-the-codebase">
  ### 探查代码库的某个部分
</div>

一种用于引导式代码探索的技能，将 Devin 限制为仅使用只读工具：

```markdown theme={null}
---
name: investigate
description: Research a part of the codebase and produce a written summary with file references.
allowed-tools: Read, Grep, ListDir
argument-hint: <topic or area to investigate>
---

## Research

1. Search the codebase for files related to: $ARGUMENTS
2. Read the most relevant files thoroughly
3. Trace the call chain and data flow

## Summarize

1. Write a summary of how $ARGUMENTS works
2. Include specific file paths and line numbers for every claim
3. Note any concerns, edge cases, or areas that need attention
```

`allowed-tools` 字段会将 Devin 限制为只读操作——不能编辑，也不能执行 shell 命令。这对于只想进行分析而不产生副作用的探索任务非常有用。

<div id="skill-discovery">
  ## 技能发现
</div>

Devin 会从**两个来源**中发现技能，并在每次会话开始时将它们合并：

1. **已建立索引的代码库 (indexed repos) ** — Devin 的后端会在与你的组织连接的所有代码库中为 `SKILL.md` 文件建立索引。这些技能在会话开始时即可立即使用，此时还未克隆任何代码库。
2. **已克隆的代码库 (cloned repos) ** — 当代码库被克隆到会话使用的机器上时，Devin 会在磁盘上扫描其中的 `SKILL.md` 文件。通过磁盘扫描发现的技能会更新或覆盖来自同一代码库的任何匹配的索引技能，确保 Devin 始终使用当前正在处理分支上的最新版本。

当某个代码库在会话中途完成克隆时，Devin 会自动重新扫描该代码库，从而在无需重启的情况下识别到新添加或已修改的技能。

<div id="supported-skill-file-locations">
  ### 支持的技能文件位置
</div>

Devin 会在以下所有目录中搜索 `SKILL.md` 文件：

* `.agents/skills/<skill-name>/SKILL.md` ** (推荐) **
* `.devin/skills/<skill-name>/SKILL.md`
* `.github/skills/<skill-name>/SKILL.md`
* `.claude/skills/<skill-name>/SKILL.md`
* `.cursor/skills/<skill-name>/SKILL.md`
* `.codex/skills/<skill-name>/SKILL.md`
* `.cognition/skills/<skill-name>/SKILL.md`
* `.windsurf/skills/<skill-name>/SKILL.md`

在每个代码仓库中都会扫描上述八个路径。

<div id="what-devin-loads-from-a-skill-file">
  ### Devin 从技能文件中加载的内容
</div>

当发现某个技能时，Devin 会解析 YAML **frontmatter** (顶部的 `---` 块) 并提取：

| Field           | Purpose                               |
| --------------- | ------------------------------------- |
| `name`          | 标识该技能。如果省略，则回退为父目录名称。                 |
| `description`   | 在技能列表中显示的简短摘要，让 Devin (以及你) 知道该技能的作用。 |
| `allowed-tools` | 限制技能激活时 Devin 可以使用哪些工具。               |

除了标准规范外，Devin 还支持以下额外的 frontmatter 字段：

| Field           | Purpose                                                               |
| --------------- | --------------------------------------------------------------------- |
| `argument-hint` | 与技能名称一起显示的提示文本，用于描述预期参数。                                              |
| `triggers`      | 控制谁可以调用该技能——默认为 `["user", "model"]`。将其设置为 `["user"]` 可阻止 Devin 自动激活它。 |

frontmatter **之后**的所有内容都是技能主体——当技能被调用时，Devin 会按照其中的分步说明执行。

完整的文件格式参考请参见 [Agent Skills specification](https://agentskills.io/specification)。

<div id="how-devin-uses-skills">
  ## Devin 如何使用技能
</div>

在每次会话开始时，Devin 会看到所有可用技能的列表 (名称 + 描述) 。当某个技能被**调用**时，Devin 会读取完整的 `SKILL.md` 文件，并将其正文作为系统级指令注入到当前上下文中。这意味着在接下来的任务中，Devin 会主动遵循该技能中的步骤——它不仅仅是一个参考，而是直接引导 Devin 的行为。

Devin 可以通过多种方式使用技能：

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

当 Devin 判断某个技能与当前任务相关时，会自动调用它。比如，如果你让 Devin 修复前端代码中的一个 bug，并且存在一个 `test-before-pr` 技能，Devin 会在打开 PR 之前先激活它。若要禁止对只希望显式触发的技能进行自动调用，请在 frontmatter 中设置 `triggers: ["user"]`。

<div id="mention-a-skill-in-your-prompt">
  ### 在提示中提到某个技能
</div>

你可以在消息中加入 `@skills:skill-name` 来让 Devin 使用某个特定技能：

```
Fix the login bug on the /auth page @skills:test-before-pr
```

你还可以传入参数：

```
@skills:deploy staging
```

在技能主体中，凡是出现 `$ARGUMENTS`、`$ARGUMENTS[0]`、`$1` 等的地方，都会被替换为对应的参数值。

<div id="one-active-skill-at-a-time">
  ### 一次只启用一个技能
</div>

Devin 在同一时间只能有一个技能处于激活状态。调用一个新技能会替换掉之前的技能。技能被激活时，Devin 会按照该技能的步骤依次执行，完成每一步后再继续进行下一步。

<div id="searching-and-listing">
  ### 搜索和列出
</div>

如果 Devin 需要在会话中途找到合适的技能，它可以按关键词或目录搜索技能。你也可以让 Devin 列出可用技能，或在你向技能文件推送更改后重新加载这些技能。

<div id="limitations">
  ## 限制
</div>

* **全局 / 组织级技能** — 目前，技能只存在于各个代码仓库中。对于组织范围的技能，可以创建一个专门的「skills」仓库作为变通方案。我们正在探索对适用于所有仓库的组织级技能提供原生支持。
* **组合多个技能** — 当前一次只能激活一个技能。我们正在开发对工作流串联与组合的支持。

<div id="skills-vs-playbooks">
  ## Skills 与 Playbooks 的区别
</div>

Skills 和 [playbooks](/zh/product-guides/creating-playbooks) 都为 Devin 提供可复用的指令，但它们的工作方式不同：

|           | Skills                                                 | Playbooks                             |
| --------- | ------------------------------------------------------ | ------------------------------------- |
| **存放位置**  | 在你的代码仓库中，作为 `SKILL.md` 文件——与代码一起纳入版本控制                 | 在 Devin web 应用中——通过 UI 管理             |
| **触发方式**  | Devin 会自动发现并调用，或者你可以在任意 prompt 中通过 `@skills:name` 显式引用 | 在启动会话时手动附加到该会话                        |
| **作用范围**  | 作用于单个代码仓库——Devin 会根据与任务相关的仓库自动选用合适的 skills             | 作用于整个组织——任何团队成员都可以在任意会话中附加任意 playbook |
| **自动建议**  | Devin 在测试你的应用或学到新内容后，会建议创建新的 skills                    | 由团队成员手动创建                             |
| **最适合用于** | 测试流程、本地开发环境配置、部署检查清单、与仓库紧密相关的工作流                       | 可复用的 prompt 模板、跨仓库任务模式、入职/上手指南        |

**我应该用哪一个？** 如果你的指令与某个特定代码仓库强相关——比如如何运行、测试或部署——请使用 skill。如果你的指令是适用于多个仓库或团队的通用型 prompts，请使用 playbook。

<div id="learn-more">
  ## 了解更多
</div>

* [Agent Skills specification](https://agentskills.io/specification) —— `SKILL.md` 文件格式、frontmatter 字段和目录结构的开放标准
* [Knowledge](/zh/product-guides/knowledge) —— 用于提供上下文提示和事实信息 (而非分步操作指引)
* [Playbooks](/zh/product-guides/creating-playbooks) —— 用于附加到会话的可复用提示模板