trae cn 的skill编写规则详解
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）
结果导向而非过程脚本：
❌ 差：“第一步：先检查语法；第二步：再检查格式...”（把 AI 当脚本用）。
✅ 好：定义验收标准（Acceptance Criteria）。告诉 AI “什么样的结果算合格”，让 AI 自己规划路径。例如：“所有函数必须有 JSDoc 注释”、“API 响应必须包含 error_code 字段”。
写“赋能”指南，而非冗长 SOP：
只写能增加 AI 任务完成概率的关键信息，避免消耗 Token 写废话。
单一职责：
一个 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): 修复分页逻辑溢出问题，增加页码边界校验`五、 创建与管理方式
手动创建（最推荐）：直接按上述规则编写
SKILL.md文件，放入对应目录。重启 TRAE 或刷新技能列表即可生效。对话创建：在 TRAE 中直接说：“帮我创建一个 Skill，用于生成 React 函数组件，要求使用 TypeScript 和 CSS Modules”。AI 会引导你生成文件。
导入导出：在 TRAE 设置页的“规则和技能”中，可以导入/导出 Skill 文件夹，方便团队共享。
避坑指南：
文件名必须全大写：
SKILL.md，不是skill.md。描述要精准：
description字段含糊会导致技能无法自动触发。少用全局技能：优先使用项目级技能，避免不同项目规范冲突。