> ## 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.

技能（Skill）是一种模块化的能力扩展机制。你可以将特定的工作流程、知识和最佳实践封装成可复用的 Skill。
在处理一个任务时，若该任务与某个 Skill 中所描述的使用场景相匹配，TRAE CLI 会自动加载并运用该 Skill，从而更精准、可靠地完成任务，无需你每次都提供重复的指令。
本文档将全面介绍 Skill 的概念、类型、创建与使用方法，以及相关的最佳实践。
## 了解 TRAE CLI 中的技能 {#33266e83}
### 特点 {#33266e83}

* **按需触发**
   Skill 并非常驻内存。TRAE CLI 仅在你的请求与 Skill 的 `description`（功能描述）匹配时，才会动态加载并激活对应的 Skill。这确保了高效的资源利用。
* **渐进式披露**
   在一个 Skill 中，你可以将详细的文档、示例或脚本拆分到独立的文件中。这种“渐进式披露”的设计，让 TRAE CLI 只在必要时加载相关资源。

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

### 所在目录 {#a7a64e19}

* 全局 Skill 的相关文件位于本地根目录 `~/.traecli/skills`。
* 项目 Skill 的相关文件位于 `.traecli/skills/` 目录。

### 基本结构 {#8b240aa3}
每个 Skill 都是一个独立的文件夹，其中必须包含一个 `SKILL.md` 文件，你还可以根据实际需求添加其他文件，例如可执行的脚本、可参考的模板和风格指南等。
一个最简的 Skill 目录结构如下：
```Plain Text
.
└── .traecli/
    └── skills/
        └── skill-name/
            └── SKILL.md
```

### SKILL.md 文件 {#9f4cbeae}
`SKILL.md` 文件是 Skill 的核心，必须包含两部分：YAML Frontmatter（元数据）和 Markdown 正文（指令）。
YAML Frontmatter 位于文件顶部，使用 `---` 分隔，用于定义 Skill 的基本信息，需配置的字段如下：
<!-- @cols-width: 137,100,623 -->
| | | | \
|**字段** |**是否必填** |**描述** |
|---|---|---|
| | | | \
|`name` |是 |Skill 的名称，使用小写字母、数字和连字符，例如 `api-style-guide`。 |
| | | | \
|`description` |是 |Skill 的核心描述。这是 TRAE CLI 判断何时触发该 Skill 的关键依据。它应该清晰地说明“这个 Skill 做什么”以及“什么时候使用它”。 |

一个最小的 `SKILL.md` 示例如下：
```Plain Text
---
name: api-style-guide
description: 用于检查和规范项目中的 API 设计是否符合团队的最佳实践。当需要评审或撰写新的 API 时使用。
---

# API 设计规范
本规范旨在统一项目中的 API 设计风格，确保一致性与可维护性。

## 设计原则
1. **资源导向**：API 应围绕资源进行设计，使用标准的 HTTP 方法（GET, POST, PUT, DELETE）。
2. **版本控制**：所有 API 都应包含版本号，例如 `/v1/users`。
3. **错误处理**：提供标准化的错误响应格式。

## 命名约定
- 路径名使用小写字母和连字符，例如 `/user-profiles`。
- 参数名使用蛇形命名法（snake_case），例如 `user_id`。
```

### 可选文件与“渐进式披露” {#b853fcab}
为了保持 `SKILL.md` 的简洁并高效利用上下文，你可以将详细的文档、示例或脚本拆分到独立的文件中。这种“渐进式披露”的设计，让 TRAE CLI 只在必要时加载相关资源。
一个更完整的 Skill 目录树示例如下：
```Plain Text
.
└── .traecli/
    └── skills/
        └── api-style-guide/
            ├── SKILL.md          # 核心入口（必需）
            ├── reference.md      # 详细参考文档（可选）
            ├── examples.md       # 完整的请求与响应示例（可选）
            └── scripts/
                └── lint.py       # 用于自动检查的辅助脚本（可选）
```

在 `SKILL.md` 中，你可以自然地引用这些文件，TRAE CLI 会在需要时加载它们。
## 创建 Skill {#2c4924cd}

1. 在项目根目录（或本地根目录）下，创建 Skill 的文件夹：
   ```Bash
   mkdir -p .traecli/skills/<skill-name>    # 在项目根目录下，创建项目 Skill
   mkdir -p ~/.traecli/skills/<skill-name>  # 在本地根目录下，创建全局 Skill
   ```

2. 在 `<skill-name>` 文件夹内，创建并编写 `SKILL.md` 文件。
3. 重启 TRAE CLI，使 Skill 生效。

## 提交与分享 Skill {#241dc8c5}
将新创建或修改的 Skill 提交到版本库，团队其他成员在 `git pull` 后即可自动获得。
```Bash
git add .traecli/skills/your-skill-name
git commit -m "feat: 添加 API 设计规范 Skill"
git push
```

## 更新 Skill {#f916e83d}
直接修改对应的 `SKILL.md` 或其他资源文件，然后提交变更即可。
:::tip 提示
更新后，需要重启 TRAE CLI 后才能加载最新版本的 Skill。
:::
## 验证 Skill {#3c289962}
### 检查 Skill 是否被正确配置 {#4d489096}
<!-- @cols-width: 192,674 -->
| | | \
|**检查项** |**描述** |
|---|---|
| | | \
|Skill 是否被有效配置 |运行内置的 `/skills` 命令。若 Skill 已被正确配置，它将在 TRAE CLI 面板中被展示。 |\
| |![Image=400x310](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/384b1c5b734144758fdb1306dac5a1d9~tplv-goo7wpa0wc-image.image) |
| | | \
|**Skill 的文件路径是否正确** |确认 Skill 的路径是否正确，比如项目级 Skill 是否严格按照 `${PROJECT}/.traecli/skills/<skill-name>/SKILL.md` 的结构存放。 |
| | | \
|**是否存在 YAML 语法错误** |检查 `SKILL.md` 文件头部的 `---` 分隔符是否完整，缩进是否正确（切勿 Tab 键）。 |
| | | \
|**`name` 是否符合规范** |确保正确填写 `SKILL.md` 文件头部的 `name` 字段，该字段仅支持小写字母、数字和连字符 `-`，不可以包含中文、空格等。如果 `name` 不合法，将默认使用目录名。 |

### 验证 Skill 是否可被有效触发 {#18bd9300}
要让 Skill 在正确的时机被有效触发，关键在于编写一个明确的 `description`。一个好的描述应该包含具体关键词和场景。
例如：

* **模糊的描述（效果差）**：`"处理文档"`；
* **清晰的描述（效果好）**：`"从 PDF 文件中提取文本和表格。当用户提到需要处理 PDF、表单或从文档中提取内容时使用"`。

编写好 Skill 后，直接在 TRAE CLI 中提出与 `description` 中的关键词和场景相关的问题即可进行测试。
若 Skill 未被触发，检查：

* **描述过于模糊**：检查 `description` 字段中的描述是否足够具体，是否包含了用户提问时可能用到的关键词。
* **TRAE CLI 未重启**：在创建或修改 Skill 后，是否已重启 TRAE CLI。

## 最佳实践 {#1701732f}

* **Skill 最小化原则**：一个 Skill 只做一件事情。例如，将 “文档处理” 拆分为 “PDF 表单填写”、“Word 格式转换” 等多个独立的 Skill。
* **明确用于触发 Skill 的关键词**：在 `description` 中使用精确的动词和名词，清晰定义 Skill 的适用场景。
* **拆分资源文件**：对于复杂 Skill，善用 `reference.md`、`examples.md` 等辅助文件，以减少主文件 `SKILL.md` 的长度，提升加载效率。
* **记录版本**：当 Skill 发生较大变更时，可以在 `SKILL.md` 中添加版本说明，方便追踪其演进历史。

## TREA CLI 是否可以运行 TRAE IDE 中的 Skill？ {#89b1a594}
TRAE CLI 兼容 TRAE IDE 中的 Skill。
TRAE IDE 存储项目 Skill 的目录是 `.trae/skills/`，存储全局 Skill 的目录是本地根目录 `~/.trae-cn/skills`。TRAE CLI 可以读取和运行这两个目录下的 Skill。
:::tip 提示
TRAE IDE 支持在 Skill 的名称中使用中文，但 TRAE CLI 不支持。因此，如果 TRAE IDE 中的 Skill 的名称包含中文，TRAE CLI 将无法识别该 Skill。
:::