技能

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

了解 TRAE CLI 中的技能

特点

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

类型

TRAE CLI 支持两类 Skill：全局 Skill、项目 Skill。

所在目录

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

基本结构

每个 Skill 都是一个独立的文件夹，其中必须包含一个 SKILL.md 文件，你还可以根据实际需求添加其他文件，例如可执行的脚本、可参考的模板和风格指南等。
一个最简的 Skill 目录结构如下：

.
└── .traecli/
    └── skills/
        └── skill-name/
            └── SKILL.md

SKILL.md 文件

SKILL.md 文件是 Skill 的核心，必须包含两部分：YAML Frontmatter（元数据）和 Markdown 正文（指令）。
YAML Frontmatter 位于文件顶部，使用 --- 分隔，用于定义 Skill 的基本信息，需配置的字段如下：

一个最小的 SKILL.md 示例如下：

---
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 目录树示例如下：

.
└── .traecli/
    └── skills/
        └── api-style-guide/
            ├── SKILL.md          # 核心入口（必需）
            ├── reference.md      # 详细参考文档（可选）
            ├── examples.md       # 完整的请求与响应示例（可选）
            └── scripts/
                └── lint.py       # 用于自动检查的辅助脚本（可选）

在 SKILL.md 中，你可以自然地引用这些文件，TRAE CLI 会在需要时加载它们。

创建 Skill

1. 在项目根目录（或本地根目录）下，创建 Skill 的文件夹：

   mkdir -p .traecli/skills/<skill-name>    # 在项目根目录下，创建项目 Skill
   mkdir -p ~/.traecli/skills/<skill-name>  # 在本地根目录下，创建全局 Skill
   

2. 在 <skill-name> 文件夹内，创建并编写 SKILL.md 文件。

3. 重启 TRAE CLI，使 Skill 生效。

提交与分享 Skill

将新创建或修改的 Skill 提交到版本库，团队其他成员在 git pull 后即可自动获得。

git add .traecli/skills/your-skill-name
git commit -m "feat: 添加 API 设计规范 Skill"
git push

更新 Skill

直接修改对应的 SKILL.md 或其他资源文件，然后提交变更即可。

验证 Skill

检查 Skill 是否被正确配置

验证 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。