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

在 TRAE 中，技能（Skill）通过 `SKILL.md` 文件进行定义和管理。每个技能封装了指令、脚本及相关资源，用于为智能体提供可复用、面向特定场景的专业能力。
## 了解 TRAE 中的技能 {#d9db28cb}
一个技能可以被视为提供给智能体的一套 “专业能力说明书”（类似用户手册或操作指南）。在执行任务时，智能体可以按需加载相应的技能，从而增强其对任务的理解与执行能力。
### 主要特点 {#4db87c40}

* **结构化**
   一个技能对应一个 `SKILL.md` 文件，文件中以结构化的方式描述完成某一类任务所需的信息，例如：任务目标与适用场景；关键约束与注意事项；推荐流程或操作步骤；可选的脚本、模板或示例。
* **动态按需加载**
   智能体不会在任务开始时一次性读取所有技能的完整内容。在执行任务前，智能体会先扫描所有技能的简要描述，仅当判断当前任务与某个技能高度相关时，才会加载该技能的详细内容。这种按需加载机制可以有效减少上下文中的 Token 消耗、避免无关信息干扰智能体的决策。

### 使用场景 {#256519c1}

* **保证输出结果的一致性与规范性**
   需要智能体在不同时间、不同任务中，始终按照既定标准输出结果。例如，将统一设计规范、执行团队标准、保持品牌一致性或确保代码符合项目约定等要求封装为技能，从而将隐性的个人或团队标准转化为显式、可复用的专业能力，最终使输出结果更加稳定、可控。
* **自动化重复性工作流**
   需要频繁执行相同或高度相似的多步骤任务。例如，对于测试流程、代码规范检查、常规数据分析等难以避免的日常工作，可以将既有的 SOP 封装为技能。一旦相关任务被触发，智能体即可自动按照定义好的流程执行，从而减少重复的指令输入，提升效率。
* **总结与共享专业能力**
   总结个人经验或团队规范，并在更大范围内复用。例如，将技能在社区、交流群等公共平台进行分享，从而在不同的智能体、项目、团队间复用相同的技能。

### 技能 vs 其他功能 {#4e37c17b}

* **技能 vs 规则**
   规则采用全量加载机制，一旦开启对话，所有规则都会被注入并持续占用上下文窗口；技能则采用按需加载机制，仅在实际需要被调用时才加载到上下文中，从而显著降低 Token 消耗。
* **技能 vs MCP Server**
   技能用于向 TRAE 描述如何完成任务，而 MCP Server 负责向 TRAE 提供可以调用的工具。
   例如，TRAE 可以通过 Playwright MCP Server 获得页面操作等自动化测试能力；而对应的技能则用于约定测试工程结构、页面对象模型（POM）设计规范，以及常见测试用例的编写和执行流程，从而引导 TRAE 在正确的上下文中高效调用这些能力。

### 支持的技能类型 {#8574712c}
<!-- @cols-width: 112,740 -->
| | | \
|**类型** |**描述** |
|---|---|
| | | \
|全局技能 |跨项目全局生效的技能，可用于： |\
| | |\
| |* 统一个人 / 团队的通用开发范式，例如统一代码风格、命名规范、注释习惯； |\
| |* 提供跨项目可复用的工程能力，例如通用工具链的使用（Git、CI/CD、Playwright 等）； |\
| |* 固化个人或组织的长期偏好，例如输出结构（是否先给结论、是否列步骤、是否给示例）。 |
| | | \
|项目技能 |仅在当前项目生效的技能，可用于： |\
| | |\
| |* 注入项目专属的业务知识与规则，例如不可违反的业务约束与边界条件、项目内部术语、概念映射； |\
| |* 约束 AI 按项目的既定技术方案工作，例如技术栈、框架版本、架构限制等； |\
| |* 让 AI 深度参与当前项目的开发和维护，例如针对项目生成测试、Mock、脚手架代码；与项目使用的 MCP Server 或内部工具协同。 |

### 技能的结构 {#e9574a0a}
一个技能中必须包含一个 `SKILL.md` 文件，还可以根据实际需求添加其他文件，例如可执行的脚本、可参考的模板和风格指南等。例如：
```Plain Text
skill-name/
├── SKILL.md               # （必须）智能体的核心指令
├── examples/              # （可选）输入/输出示例
    ├── input.md
    └── output.md
├── templates/             # （可选）可复用的模板
    └── component.tsx
└── resources/             # （可选）参考文件、运行脚本或素材
    └── style-guide.md
```

### 技能所在目录 {#991b40ad}
技能相关文件所在目录如下：

* **项目技能**：项目所在路径下的 `.trae/skills/` 目录。
* **全局技能**：
   * macOS/Linux：本地根目录 `~/.trae-cn/skills`。
   * Windows：本地根目录 `%userprofile%/.trae-cn/skills`。

### SKILL.md 文件格式 {#d5170c57}
`SKILL.md` 文件的格式如下：
```Markdown
---
name: 技能名称
description: 简要描述这个技能的功能和使用场景

---

# 技能名称

## 描述
描述这个技能的作用。

## 使用场景
描述触发这个技能的条件。

## 指令
清晰的分步说明，告诉智能体具体怎么做。

## 示例 (可选)
输入/输出示例，展示预期效果。
```

## 创建技能 {#8be9a856}
### 方式一：通过对话，由 AI 自动创建技能 {#87274c6b}
你可以直接通过对话创建技能。你只需向 AI 描述你的需求，AI 就会自动为你生成对应技能的 `SKILL.md` 文件。例如：
```Markdown
帮我在 ./trae/skills 目录下创建一个新的技能

技能的名字叫 xxx

这个技能可以帮我做以下事情：
- xxx
- xxx
- xxx
```

### 方式二：手动创建技能 {#badf28b2}
通过指定技能类型、技能名称、描述和指令，手动创建技能。

1. 前往 **设置** > **技能与命令**。
2. 在 **技能** 部分，点击 **创建** 按钮，然后选择技能类型（**全局** / **项目**）。
   界面上出现 **创建技能** 窗口。
   ![Image=550x702](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/7c808357f3fb416c976af5b5c97e7f51~tplv-goo7wpa0wc-image.image)
3. 填写 **技能名称**、**描述** 和 **指令**。
   <!-- @cols-width: 122,635 -->
   | | | \
   |**字段** |**描述** |
   |---|---|
   | | | \
   |技能名称 |为该技能起一个简短且有辨识度的名称。 |
   | | | \
   |描述 |描述该技能是什么，以及应该在什么情况下被触发。 |
   | | | \
   |指令 |当该技能被触发时，你希望 AI 遵循哪些规则或信息。 |

4. 点击 **确认** 按钮。
   * 对于全局技能，添加后，它会直接出现在 **技能** 面板的 **全局** 页签下。
   * 对于项目技能，添加后，TRAE 将自动在当前项目的 `.trae/skills/{skill_name}` 目录下新建一个 `SKILL.md` 文件。文件内包含你的自定义技能配置。同时，该技能也会出现在 **技能** 面板的 **项目** 页签下。
5. (可选) 对于项目技能，根据指令中的描述，在 `{skill_name}` 文件夹下手动添加所需的脚本等资源。

### 方式三：手动导入外部技能 {#0ea60825}
若你需要使用外部已创建的技能，可以直接将 `SKILL.md` 文件或包含 `SKILL.md` 以及其他相关文件的 .zip 文件导入至 TRAE。

1. 前往 **设置** > **技能与命令**。
2. 在 **技能** 部分，点击 **创建** 按钮，然后选择技能类型（**全局** / **项目**）。
   界面上出现 **创建技能** 窗口。
3. 上传一个 `SKILL.md` 文件或一个包含 `SKILL.md` 文件的 .zip 文件。
   TRAE 会分析所上传的技能文件，然后自动填充 **技能名称**、**描述** 和 **指令** 字段。
4. 按需修改 TRAE 自动填充的 **技能名称**、**描述** 和 **指令** 字段中的内容，然后点击 **确认** 按钮。
   * 对于全局技能，添加后，它会直接出现在 **技能** 面板的 **全局** 页签下。
   * 对于项目技能，TRAE 将自动在 `.trae/skills/` 目录下新建 `{skill_name}` 文件夹，其中包含你所上传的所有文件。同时，该技能也会在 **技能** 面板的 **项目** 页签下展示。

## 启用/禁用技能 {#a3571418}
创建技能后，你可以通过打开/关闭该技能的开关来启用/禁用它。
使用该功能后，TRAE 会在项目的 `.trae/` 目录下创建 `skill-config.json` 文件。文件内罗列被禁用的项目技能。被禁用的全局技能不会出现在该文件中。
## 编辑/删除技能 {#a0c17ff7}
点击目标技能右侧的齿轮图标，然后在菜单中选择 **编辑** 或 **删除**，按需完成相应操作。
对于项目技能，你还可以选择 **应用到全局**，从而将其转换为全局技能。
## 在对话中使用技能 {#5b091232}
### 方式一：手动调用技能 {#9d088e00}
你可以直接向 AI 发送指令，明确告知 AI 调用某个技能来完成任务，例如：“用 codemap 技能总结一下这个分支的改动”。
### 方式二：由 AI 自动调用技能 {#00525fb0}
在执行任务时，AI 会结合当前任务内容与各技能中定义的 “适用场景” 或 “何时使用” 之类的描述，判断是否需要加载某个技能，并在合适的阶段自动调用相关技能。
例如，假设你定义了一个代码审核技能，其触发条件为 “当用户请求代码反馈或评审时”。当你提出 “这个函数写得如何”、“帮我审核以下代码” 之类的请求时，AI 会识别到这类请求与代码审核技能的相关性，并在无需额外指令的情况下加载并使用该技能，以完成对应的代码分析与反馈。
## 使用 .agents 技能目录 {#f734fc43}
`.agents` 技能目录（即 `.agents/skills/`）是由 [Agent Skills](https://agentskills.io/home) 规范约定的目录，用于存放技能。你可以将该目录添加至项目，让智能体在运行时自动发现并加载其中的技能。
### **注意事项** {#ac147835}
若你在 TRAE IDE 内创建的技能（位于 `.trae/skills/` 目录）与 `.agents/skills/` 中的技能重名，系统将优先调用 `.trae/skills/` 目录中的技能。
### 将技能安装至 .agents/skills/ 目录 {#9a2ab080}
你可以使用 “find-skills ” 技能，将所需技能快速安装至 `.agents/skills/` 目录。
“find-skills” 技能依托名为 `skills` 的命令行工具（CLI），让你可以从开放的 Agent Skills 生态中搜索、安装与管理各类模块化技能包。详情参考[查找 Skill](/ide/top-10-recommended-skills-for-development-scenarios#1aaa5672)。
### **使用** .agents/skills/ 目录 {#196cfaf5}

1. 将 `.agents/skills/` 目录添加至你的项目。
2. 启用 `.agents/skills/` 目录。
   1. 前往 **设置** > **技能与命令。**
   2. 在 **导入设置** 部分，打开 **启用 .agents 技能目录** 开关。
      ![Image=700x125](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/65321606845e474d9a370352c5676d14~tplv-goo7wpa0wc-image.image)

## 最佳实践 {#ea88c347}
Skill 的开发非一蹴而就，而是一个持续迭代的过程。关于构建和迭代 Skill 的最佳实践，参考[如何写好一个 Skill：从创建到迭代的最佳实践](/ide/best-practice-for-how-to-write-a-good-skill)。