技能（Skill）是一种模块化的能力扩展机制。你可以将特定的工作流程、知识和最佳实践封装成可复用的 Skill。在处理一个任务时，若该任务与某个 Skill 中所描述的使用场景相匹配，TRAE CLI 会自动加载并运用该 Skill，从而更精准、可靠地完成任务，无需你每次都提供重复的指令。本文档将全面介绍 Skill 的概念、类型、创建与使用方法，以及相关的最佳实践。 ## 了解 TRAE CLI 中的技能 ### 特点 * **按需触发** Skill 并非常驻内存。TRAE CLI 仅在你的请求与 Skill 的 `description`（功能描述）匹配时，才会动态加载并激活对应的 Skill。这确保了高效的资源利用。 * **渐进式披露** 在一个 Skill 中，你可以将详细的文档、示例或脚本拆分到独立的文件中。这种“渐进式披露”的设计，让 TRAE CLI 只在必要时加载相关资源。 ### 类型 TRAE CLI 支持两类 Skill：全局 Skill、项目 Skill。 |**类型** |**描述** | |---|---| |全局 Skill |跨项目全局生效的 Skill，可用于：|\ | ||\ | |* 统一个人 / 团队的通用开发范式，例如统一代码风格、命名规范、注释习惯；|\ | |* 提供跨项目可复用的工程能力，例如通用工具链的使用（Git、CI/CD、Playwright 等）；|\ | |* 固化个人或组织的长期偏好，例如输出结构（是否先给结论、是否列步骤、是否给示例）。 | |项目 Skill |仅在当前项目生效的 Skill，可用于：|\ | ||\ | |* 注入项目专属的业务知识与规则，例如不可违反的业务约束与边界条件、项目内部术语、概念映射；|\ | |* 约束 AI 按项目的既定技术方案工作，例如技术栈、框架版本、架构限制等；|\ | |* 让 AI 深度参与当前项目的开发和维护，例如针对项目生成测试、Mock、脚手架代码；与项目使用的 MCP Server 或内部工具协同。 | ### 所在目录 * 全局 Skill 的相关文件位于本地根目录 `~/.traecli/skills`。 * 项目 Skill 的相关文件位于 `.traecli/skills/` 目录。 ### 基本结构每个 Skill 都是一个独立的文件夹，其中必须包含一个 `SKILL.md` 文件，你还可以根据实际需求添加其他文件，例如可执行的脚本、可参考的模板和风格指南等。一个最简的 Skill 目录结构如下： ```Plain Text . └── .traecli/ └── skills/ └── skill-name/ └── SKILL.md ``` ### SKILL.md 文件 `SKILL.md` 文件是 Skill 的核心，必须包含两部分：YAML Frontmatter（元数据）和 Markdown 正文（指令）。 YAML Frontmatter 位于文件顶部，使用 `---` 分隔，用于定义 Skill 的基本信息，需配置的字段如下： |**字段** |**是否必填** |**描述** | |---|---|---| |`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`。 ``` ### 可选文件与“渐进式披露” 为了保持 `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 1. 在项目根目录（或本地根目录）下，创建 Skill 的文件夹： ```Bash mkdir -p .traecli/skills/ # 在项目根目录下，创建项目 Skill mkdir -p ~/.traecli/skills/ # 在本地根目录下，创建全局 Skill ``` 2. 在 `` 文件夹内，创建并编写 `SKILL.md` 文件。 3. 重启 TRAE CLI，使 Skill 生效。 ## 提交与分享 Skill 将新创建或修改的 Skill 提交到版本库，团队其他成员在 `git pull` 后即可自动获得。 ```Bash git add .traecli/skills/your-skill-name git commit -m "feat: 添加 API 设计规范 Skill" git push ``` ## 更新 Skill 直接修改对应的 `SKILL.md` 或其他资源文件，然后提交变更即可。 :::tip 提示更新后，需要重启 TRAE CLI 后才能加载最新版本的 Skill。 ::: ## 验证 Skill ### 检查 Skill 是否被正确配置 |**检查项** |**描述** | |---|---| |Skill 是否被有效配置 |运行内置的 `/skills` 命令。若 Skill 已被正确配置，它将在 TRAE CLI 面板中被展示。|\ | |![图片](https://p9-arcosite.byteimg.com/obj/tos-cn-i-goo7wpa0wc/384b1c5b734144758fdb1306dac5a1d9 =400x) | |**Skill 的文件路径是否正确** |确认 Skill 的路径是否正确，比如项目级 Skill 是否严格按照 `${PROJECT}/.traecli/skills//SKILL.md` 的结构存放。 | |**是否存在 YAML 语法错误** |检查 `SKILL.md` 文件头部的 `---` 分隔符是否完整，缩进是否正确（切勿 Tab 键）。 | |**`name`** ** 是否符合规范** |确保正确填写 `SKILL.md` 文件头部的 `name` 字段，该字段仅支持小写字母、数字和连字符 `-`，不可以包含中文、空格等。如果 `name` 不合法，将默认使用目录名。 | ### 验证 Skill 是否可被有效触发要让 Skill 在正确的时机被有效触发，关键在于编写一个明确的 `description`。一个好的描述应该包含具体关键词和场景。例如： * **模糊的描述（效果差）** ：`"处理文档"`； * **清晰的描述（效果好）** ：`"从 PDF 文件中提取文本和表格。当用户提到需要处理 PDF、表单或从文档中提取内容时使用"`。编写好 Skill 后，直接在 TRAE CLI 中提出与 `description` 中的关键词和场景相关的问题即可进行测试。若 Skill 未被触发，检查： * **描述过于模糊**：检查 `description` 字段中的描述是否足够具体，是否包含了用户提问时可能用到的关键词。 * **TRAE CLI 未重启**：在创建或修改 Skill 后，是否已重启 TRAE CLI。 ## 最佳实践 * **Skill 最小化原则**：一个 Skill 只做一件事情。例如，将 “文档处理” 拆分为 “PDF 表单填写”、“Word 格式转换” 等多个独立的 Skill。 * **明确用于触发 Skill 的关键词**：在 `description` 中使用精确的动词和名词，清晰定义 Skill 的适用场景。 * **拆分资源文件**：对于复杂 Skill，善用 `reference.md`、`examples.md` 等辅助文件，以减少主文件 `SKILL.md` 的长度，提升加载效率。 * **记录版本**：当 Skill 发生较大变更时，可以在 `SKILL.md` 中添加版本说明，方便追踪其演进历史。 ## TREA CLI 是否可以运行 TRAE IDE 中的 Skill？ 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。 :::

TRAE CN