创建技能 - Devin Docs

技能定义为位于具名目录中的 SKILL.md 文件。本页将介绍编写高效技能所需了解的全部内容。

文件结构

按作用域将技能放置到相应的目录中：

# 项目专属（已提交到 git）
.devin/skills/
└── my-skill/
    └── SKILL.md

# 全局 — 在所有项目中可用（未提交）
# Linux/macOS:
~/.config/devin/skills/
└── my-skill/
    └── SKILL.md

# Windows:
%APPDATA%\devin\skills\
└── my-skill\
    └── SKILL.md

目录名称是该技能的标识符 (用于调用 /my-skill) 。SKILL.md 文件包含可选的 YAML frontmatter 和该技能的提示内容。

在 Windows 上，%APPDATA% 通常会解析为 C:\Users\<YourUser>\AppData\Roaming。

Frontmatter 参考

---
name: my-skill
description: What this skill does (shown in completions)
argument-hint: "[file] [options]"
model: sonnet
subagent: true
allowed-tools:
  - read
  - grep
  - glob
  - exec
permissions:
  allow:
    - Read(src/**)
  deny:
    - exec
  ask:
    - Write(**)
triggers:
  - user
  - model
---

Your prompt content goes here...

所有 Frontmatter 字段

字段	类型	默认值	描述
`name`	string	目录名称	技能的显示名称
`description`	string	无	显示在 Slash Command 补全建议中
`argument-hint`	string	无	显示在命令名称后的提示 (例如 `[filename]`)
`model`	string	当前模型	覆盖运行此技能时所使用的模型
`subagent`	boolean	`false`	将此技能作为子 Agent 运行，而不是以内联方式运行
`agent`	string	无	使用特定的 custom 子 Agent Profile 将此技能作为子 Agent 运行
`allowed-tools`	list	所有工具	限制此技能可使用的工具
`permissions`	object	继承	此技能的权限覆盖设置
`triggers`	list	`[user, model]`	此技能可通过何种方式调用

模型覆盖

使用 model 字段，可让某个技能使用与当前会话中激活模型不同的模型运行。这对于简单任务使用更快的模型，或为复杂任务使用能力更强的模型都很有帮助：

---
name: quick-fix
description: Fast lint fix using a lightweight model
model: swe
---

Fix the lint errors in the current file.

模型名称使用与 --model CLI 参数相同的取值 (例如 opus、sonnet、swe、codex) 。完整列表请参见 Models。技能完成后，会话将返回到之前正在使用的模型。

将技能作为子 Agent 运行

将技能作为子 Agent 运行是实验性功能。subagent 和 agent frontmatter 字段可能会在未来版本中发生变化。

默认情况下，技能的提示会注入当前对话中，由 Agent 直接内联处理。你也可以将技能作为子 Agent运行，这会启动一个拥有自己上下文窗口的独立工作进程。这种方式适合执行目标明确、可独立完成的任务的技能，避免其输出干扰主对话。将技能作为子 Agent 运行有两种方式：

`subagent: true`

将 subagent: true 设为以子 Agent 形式运行该技能，并使用默认的 subagent_general Profile：

---
name: deep-research
description: Thorough codebase research on a topic
subagent: true
model: sonnet
allowed-tools:
  - read
  - grep
  - glob
---

Research the topic the user asked about thoroughly.

Search broadly, follow references, and trace call chains.
Report all findings with specific file paths and line numbers.

调用时，此技能会生成一个前台子 Agent，并将该技能的提示作为其任务执行。父 Agent 会等待子 Agent 完成，然后读取并汇总结果。

`agent: <profile>`

使用 agent 字段，可通过特定的自定义子 Agent Profile以子 Agent 的形式运行该技能：

---
name: review-pr
description: Review the current PR using the reviewer subagent
agent: reviewer
---

Review the staged changes for correctness, security, and style issues.

agent 的值必须与已注册的子 Agent Profile 名称一致 (可以是内置的，如 subagent_explore / subagent_general，也可以是你定义的自定义 Profile) 。子 Agent 会继承该 Profile 的系统提示、工具限制和模型，而技能的内容则会成为任务。

如果同时设置了 agent 和 subagent，则以 agent 为准。若两者都已指定，技能上的 model 字段会覆盖子 Agent Profile 的模型。

以子 Agent 形式运行的技能不会再生成嵌套子 Agent——如果某个技能已经在子 Agent 中执行，则会改为内联运行，以防止无限递归。

使用技能编排子 Agent

由于技能可以作为子 Agent 运行，你可以用它们来编排多步骤工作。定义一组子 Agent 技能，让每个技能分别处理一个明确的任务，然后编写一个调用它们的普通技能。外层技能会成为编排器——它会调用每个子 Agent、收集结果，并决定下一步要做什么。例如，下面是两个子 Agent 技能，以及一个协调它们的编排器：

---
name: research-changes
description: 研究近期代码修改及其影响
subagent: true
allowed-tools:
  - read
  - grep
  - glob
  - exec
---

分析此代码仓库中的近期变更：

1. 运行 `git log --oneline -20` 查看最近的提交
2. 针对每个重要提交，检查具体改动内容及原因
3. 识别其中的规律、潜在风险或需要关注的问题

报告你的发现，并附上具体的文件路径和提交引用。

---
name: validate-tests
description: Run tests and validate coverage for recent changes
subagent: true
allowed-tools:
  - read
  - grep
  - glob
  - exec
---

Validate the test suite for the project:

1. Identify the test framework and run command
2. Run the full test suite
3. Check for any failing tests
4. Review test coverage for recently changed files

Report which tests pass, which fail, and any coverage gaps.

---
name: health-check
description: Full project health check — research changes then validate tests
---

Perform a full health check on this project:

1. First, use the /research-changes skill to understand recent changes
2. Then, use the /validate-tests skill to verify the test suite
3. Finally, synthesize the findings from both into a summary:
   - What changed recently and why
   - Whether tests are passing
   - Any risks or recommended actions

调用 /health-check 会在主 Agent 中运行编排器。它会调用 /research-changes，后者会启动一个子 Agent 来检查代码库。完成后，它会调用 /validate-tests，再启动另一个子 Agent 来运行测试。随后，编排器会汇总这两项结果，生成最终摘要。子 Agent 技能在调用其他技能时绝不会再使用子 Agent，即使这些技能带有 subagent: true——它们也会以内联方式运行。这意味着你无需担心无限嵌套。编排模式始终只有一层：编排器启动子 Agent，而这些子 Agent 会以内联方式执行其余所有内容。

提示内容

SKILL.md 文件的正文 (即 frontmatter 之后的部分) 是在调用该技能时注入的提示内容。

权限

技能可使用与主权限配置相同的语法来定义自身的权限作用域：

permissions:
  allow:
    - Read(src/**)
    - Exec(npm run test)
  deny:
    - Write(/etc/**)
    - exec
  ask:
    - Write(src/**)

技能权限的工作机制：

allow — 这些作用域会在技能执行期间自动获批
deny — 这些作用域会在技能执行期间被阻止
ask — 这些作用域始终会提示用户

技能权限是在会话的基础权限之上叠加的 (而非替代它) 。技能无法授予在更高层级 (项目或组织配置) 中被拒绝的权限。

可用工具

限制该技能可使用的工具：

allowed-tools:
  - read
  - grep
  - glob

可用工具名称：read, edit, grep, glob, exec 你也可以启用 MCP 工具：

allowed-tools:
  - read
  - mcp__github__list_issues
  - mcp__github__create_issue

如果未指定 allowed-tools，该技能将可访问所有工具。对于安全关键型技能，务必仅开放最低必要的工具。

示例

代码评审技能

---
name: review
description: Review staged changes for issues
allowed-tools:
  - read
  - grep
  - glob
  - exec
permissions:
  allow:
    - Exec(git diff)
    - Exec(git log)
---

Run `git diff --staged` and review the changes for quality issues.

Evaluate:
1. **Correctness** — Any logic errors or edge cases?
2. **Security** — Any vulnerabilities introduced?
3. **Performance** — Any obvious inefficiencies?
4. **Style** — Consistent with the codebase?

Provide a summary with specific line references.

组件生成器

---
name: component
description: Generate a React component from a description
argument-hint: "<ComponentName>"
allowed-tools:
  - read
  - edit
  - grep
  - glob
model: sonnet
permissions:
  allow:
    - Write(src/components/**)
---

使用用户提供的名称创建一个新的 React 组件：

1. 检查 src/components/ 中的现有组件以了解样式规范
2. 在 src/components/<ComponentName>/<ComponentName>.tsx 创建组件文件
3. 在 src/components/<ComponentName>/index.ts 创建桶导出
4. 在 src/components/<ComponentName>/<ComponentName>.test.tsx 添加基本测试
5. 遵循现有组件中的模式

部署检查清单

---
name: deploy
description: Run through the deployment checklist
triggers:
  - user
allowed-tools:
  - read
  - exec
  - grep
permissions:
  allow:
    - Exec(npm run)
    - Exec(git)
---

Run through the deployment checklist:

1. Run the test suite: `npm run test`
2. Run the linter: `npm run lint`
3. Check for uncommitted changes: `git status`
4. Verify the build: `npm run build`
5. Show the current branch and last commit

Report the status of each step. If anything fails, stop and explain the issue.

搜索能手

---
name: find
description: Find relevant code across the project
argument-hint: "<what to find>"
allowed-tools:
  - read
  - grep
  - glob
triggers:
  - user
  - model
---

Search the codebase thoroughly for what the user asked about.

Use grep for content search and glob for file discovery.
Provide relevant file paths and code snippets.
Explain how the pieces connect.

提示

让提示更聚焦

一个技能应专注于把一件事做好。与其做一个大型技能，不如创建多个技能。

包含示例

在提示中向 Agent 展示什么样的输出才算理想。

使用 allowed-tools

限制可用工具能让技能更安全，也更可预测。

使用 /skill-name 测试

调用你的技能，并持续调整提示，直到输出符合你的预期。

​文件结构

​Frontmatter 参考

​所有 Frontmatter 字段

​模型覆盖

​将技能作为子 Agent 运行

​subagent: true

​agent: <profile>

​使用技能编排子 Agent

​提示内容

​权限

​可用工具

​示例

​代码评审技能

​组件生成器

​部署检查清单

​搜索能手

​提示

让提示更聚焦

包含示例

使用 allowed-tools

使用 /skill-name 测试

文件结构

Frontmatter 参考

所有 Frontmatter 字段

模型覆盖

将技能作为子 Agent 运行

`subagent: true`

`agent: <profile>`

使用技能编排子 Agent

提示内容

权限

可用工具

示例

代码评审技能

组件生成器

部署检查清单

搜索能手

提示