TRAE 的 Skill 本质上是一份给 AI 的“标准化操作手册”（SOP），通过 SKILL.md文件定义。它解决了重复写 Prompt 的痛点，让 AI 在特定场景下能稳定输出符合你规范的结果。

一、 核心文件与目录结构

Skill 的核心是一个名为 SKILL.md的 Markdown 文件，必须放在特定的目录下 TRAE 才能识别。

1. 存放位置（二选一）

• 项目级技能（推荐）：仅当前项目生效。

  • 路径：项目根目录/.trae/skills/你的技能名/SKILL.md

• 全局技能：所有项目生效。

  • 路径：~/.traecli/skills/你的技能名/SKILL.md（Mac/Linux）

  • 路径：%USERPROFILE%\.traecli\skills\你的技能名\SKILL.md（Windows）

2. 标准目录树

项目根目录/
└── .trae/
    └── skills/
        ├── code-reviewer/      # 技能文件夹（建议英文短横线命名）
        │   └── SKILL.md        # 核心文件（必须全大写）
        └── api-designer/
            └── SKILL.md

---

二、 SKILL.md 编写详解（核心）

文件分为两部分：YAML 元数据（头部）和 Markdown 正文（指令）。

1. YAML Frontmatter（必填，用于触发）

位于文件最顶部，用 ---包裹。这是 AI 判断“是否调用该技能”的唯一依据。

---
name: code-reviewer  # 技能ID，必须小写字母+连字符，不能有空格中文
description: 用于代码审查，检查逻辑错误、安全漏洞和代码规范。当用户请求review代码、代码优化或代码检查时触发。
---

• name：技能的唯一标识符，建议简短明确（如 vue3-ts-component）。

• description：最关键字段。必须清晰描述“做什么”+“何时触发”。AI 会根据这里的描述匹配用户意图。不要在这里写具体步骤。

2. Markdown 正文（核心指令）

这里是给 AI 的详细操作指南。建议采用以下结构化章节（非强制，但强烈推荐）：

# 角色与目标
你是一名资深后端开发专家，专注于代码质量和可维护性。你的任务是对提供的代码进行深度审查，确保其符合团队规范且无严重逻辑漏洞。

## 触发条件（When to Use）
- 当用户提及“review”、“代码审查”、“检查代码”时。
- 当用户提交代码片段并询问改进意见时。

## 核心指令（Instructions）
### 1. 分析阶段
- 首先，理解代码的**业务意图**和上下文。
- 若代码复杂，先梳理核心逻辑流程图。

### 2. 审查维度（Checklist）
- **逻辑错误**：检查边界条件、循环终止条件、空值处理。
- **安全性**：排查 SQL 注入、XSS、硬编码密钥。
- **性能**：识别循环内不必要的计算、重复查询。
- **规范**：检查命名（驼峰/蛇形）、注释覆盖率、函数长度。

### 3. 输出规范
- **语言**：使用中文回复。
- **格式**：采用 Markdown，分点列出问题。
- **优先级**：按【严重】【警告】【建议】三级分类。
- **示例**：对于每个问题，必须提供**修改后的代码示例**。

## 示例（Examples）
**用户输入**：

javascript

function getUser(id) {

return db.query("SELECT * FROM users WHERE id = " + id);

}

**AI 输出**：
**【严重】SQL 注入风险**
- **问题**：直接拼接用户输入 `id` 到 SQL 语句。
- **建议**：使用参数化查询或 ORM。
- **修正代码**：

javascript

function getUser(id) {

return db.query("SELECT * FROM users WHERE id = ?", [id]);

}

---

三、 高级编写原则（来自官方 Meta-Skill）

1. 结果导向而非过程脚本：

   • ❌ 差：“第一步：先检查语法；第二步：再检查格式...”（把 AI 当脚本用）。

   • ✅ 好：定义验收标准（Acceptance Criteria）。告诉 AI “什么样的结果算合格”，让 AI 自己规划路径。例如：“所有函数必须有 JSDoc 注释”、“API 响应必须包含 error_code 字段”。

2. 写“赋能”指南，而非冗长 SOP：

   • 只写能增加 AI 任务完成概率的关键信息，避免消耗 Token 写废话。

3. 单一职责：

   • 一个 Skill 只做一件事（如：git-commit-generator只生成提交信息，不要在里面混入代码格式化逻辑）。

---

四、 实战：创建一个“Git 提交规范” Skill

步骤 1：创建文件

• 路径：项目根目录/.trae/skills/git-commit-gen/SKILL.md

步骤 2：写入内容

---
name: git-commit-gen
description: 根据代码变更生成符合 Conventional Commits 规范的提交信息。当用户请求生成commit message、提交代码或总结变更时触发。
---

# Git 提交信息生成器

## 指令
1.  分析用户提供的 `git diff` 内容或代码变更描述。
2.  根据变更类型自动添加前缀：
    - `feat:` 新功能
    - `fix:` 修复 Bug
    - `docs:` 文档更新
    - `refactor:` 重构（不改变行为）
3.  格式：`<type>(<scope>): <subject>`，例如 `fix(auth): 修复登录态过期时间计算错误`。
4.  主体内容用中文简要说明变动原因和影响。

## 示例
**输入**：修复了用户列表页分页失效的问题，当页码大于总数时返回空数组。
**输出**：`fix(user-list): 修复分页逻辑溢出问题，增加页码边界校验`

---

五、 创建与管理方式

1. 手动创建（最推荐）：直接按上述规则编写 SKILL.md文件，放入对应目录。重启 TRAE 或刷新技能列表即可生效。

2. 对话创建：在 TRAE 中直接说：“帮我创建一个 Skill，用于生成 React 函数组件，要求使用 TypeScript 和 CSS Modules”。AI 会引导你生成文件。

3. 导入导出：在 TRAE 设置页的“规则和技能”中，可以导入/导出 Skill 文件夹，方便团队共享。

避坑指南：

• 文件名必须全大写：SKILL.md，不是 skill.md。

• 描述要精准：description字段含糊会导致技能无法自动触发。

• 少用全局技能：优先使用项目级技能，避免不同项目规范冲突。