最近一年我把 AI 编程工具从“偶尔问个问题”用到了“默认工作台”，试过各种提效方法，最后发现一个很有意思的现象：很多人天天把 Trae 挂在嘴边，却只用它的聊天窗写代码，从来没碰过自带的 Skill 功能。而 Skill 恰恰是那种“一开始觉得没必要，一旦用上就回不去”的能力。简单说，它能把一段重复劳动打磨成一份可复用的标准流程：你只需要把任务背景、约束条件和输出格式写清楚，AI 就能在合适的时机自动按这个流程干活，不用每次重讲一遍前提。这篇文章我会从最基础的 Skill 是什么讲起，带你一步步创建第一个能用、好用、可分享的 Skill。无论你是刚接触 AI 辅助开发的萌新，还是想给团队统一工作流的技术负责人，都能在这里找到可以直接上手的内容。
1. Skill 到底是什么，为什么值得花半小时去搭
1.1 Skill 不是“插件”，它更像一份岗位说明书
我第一次看到 Skill 这个概念时，以为是那种装了之后编辑器就多几个按钮的插件。实际用了之后才发现，它的本质非常简单：一份有固定格式的 Markdown 文档，放在约定的目录里，Trae 会读取并把它解析成 AI 能理解的指令包。你可以把 Agent 理解成一个聪明但需要明确指示的新人，Skill 就是他的岗位说明书。普通对话相当于你每天临时布置任务，每个任务都要从项目背景、代码风格、输出要求讲起；Skill 则把这些信息沉淀成文档，新人自己照着执行，标准始终一致。
为什么这个区别很重要？插件通常要写代码、要调用编辑器接口，做的是编辑器层面的事情；Skill 做的是“AI 行为规范”层面的事情。它不改变工具的外壳，而是改变 AI 在某个场景下的思考路径和输出方式。这种轻量设计带来的好处是：你不必学编程就能创建 Skill，写得不好也只是改一份文档，不会把 IDE 搞崩。门槛低到这个程度，总让我觉得不多建几个 Skill 有点浪费。
1.2 哪些场景值得建 Skill，哪些不建议建
长期用下来，我认为一个好场景至少要满足四个条件：第一，重复发生，比如每周都会做；第二，边界清楚，输入输出能被明确定义；第三，输出可验证，AI 做完你能快速判断对不对；第四，规则相对稳定，不需要天天改。
我把比较典型的适合场景整理在这里：
| 场景 | 典型输入 | 典型输出 | 难度 |
|---|---|---|---|
| 生成 Git 提交信息 | 变更 diff | 符合规范的 commit message | 低 |
| 单元测试生成 | 函数或模块代码 | 测试用例文档 | 中 |
| 代码审查 | 代码块或 PR diff | 问题清单、修复建议 | 中 |
| 需求拆解 | 一句话需求 | 需求文档、任务列表 | 中 |
| 文档更新 | 旧文档、变更说明 | 更新后的文档 | 低 |
| 依赖升级分析 | 依赖列表 | 升级影响分析报告 | 高 |
反过来，一次性任务就不建议建 Skill，比如“帮我把这段日志格式换一下”，这种任务的上下文太临时，写成 Skill 反而增加管理成本。还有需要实时外部数据或者必须人肉拍板的任务，也不适合交给 Skill。如果任务本身就是模糊的，Skill 写出来只会把模糊放大，AI 会用一个非常自信的语气输出一份非常不可靠的结果。
1.3 Skill 的通用文件结构：先认识 SKILL.md
不同版本的工具对 Skill 的目录要求可能略有差异，但主流的组织方式高度一致：一个 Skill 就是一个文件夹，文件夹名称就是 Skill 的名字，里面至少有一个入口文件 SKILL.md。进阶一点还会有 resources 子目录放参考材料，scripts 子目录放辅助脚本，但对大多数人来说，只维护一个 SKILL.md 就够了。
SKILL.md 通常分成两部分。开头是 YAML 格式的 frontmatter，用三根短横线包起来，记录 name、description、when_to_use、variables 这些元信息。这部分是给“调度系统”看的，AI 会通过 description 判断什么时候该调用这个 Skill。正文部分才是给“Agent 大脑”看的，写角色设定、工作流程、输出要求和禁止事项。这两部分的分工决定了你创建 Skill 时的思考顺序：先想清楚它什么时候该被触发，再想清楚它被触发后该怎么干活。
2. 创建 Skill 之前的准备：选场景、找入口、套模板
2.1 先挑一个“最小可用场景”，别一上来就做全家桶
我见过不少人第一次建 Skill 就想做个“全能助手”，把代码审查、测试生成、架构建议全塞进一个文件里，结果 AI 每次都被互相矛盾的指令干扰，输出质量很差。
建第一个 Skill 的正确姿势是选一个最小可用场景。我推荐从“生成 Git 提交信息”开始：输入就是一段 git diff，输出就是一句话提交说明，规则非常容易描述，比如“动词开头、不超过五十字、必须说明影响”。这样的场景半小时就能搞定，而且效果立竿见影——你每次提交代码时都能明显感觉到省事。等你熟悉了整个流程，再去挑战代码审查这种复杂的场景，就有了手感。
2.2 找到 Skill 入口和目录约定
我当前用的 Trae 版本，从左侧设置面板进入，里面有一项 Skill 管理，可以新建、编辑和导入导出。不同版本的入口可能不太一样，如果你的界面里没找到，直接在设置面板里搜“Skill”，或者在对话输入框里输入斜杠命令看看有没有提示。
Skill 作用的范围通常分为两种：项目级和全局级。项目级 Skill 放在项目根目录下，比如.trae/skills/下面的子目录，它只对当前项目生效，适合团队协作场景，因为规则可以随代码仓库一起提交。全局级 Skill 放在用户配置目录下，对所有项目生效，适合个人偏好。我的习惯是：和个人风格强相关的放全局，比如提交信息规范；和具体业务强相关的放项目，比如某个模块的审查清单。
2.3 一个可以直接上手的 SKILL.md 模板
下面这个模板，是我给 Skill 定的基础盘，你可以直接复制修改：
--- name: commit-helper description: 根据代码变更内容生成符合规范的 Git 提交信息，当用户要求生成提交信息或准备提交代码时使用。 when_to_use: 用户说“帮我写提交信息”“生成 commit message”，或者要求整理变更记录时。 variables: - name: type description: feat、fix、refactor、docs、test、chore 之一 default: feat --- # 角色 你是一名熟悉 Git 规范的项目维护者，善于用一句话概括代码变更的价值。 # 工作流程 1. 查看用户提供的 diff 或变更说明。 2. 确定变更类型，必要时可以修正 variables.type。 3. 生成一条提交信息，格式为：类型(模块): 一句话描述。 4. 如果变更较大，额外列出 2-3 条要点。 # 约束 - 描述必须使用中文，不超过 50 字。 - 不要在提交信息中提及文件名或行号。 - 如果 diff 信息不足，先向用户提问，不要自行猜测。这个模板的核心就在于：frontmatter 负责“何时被调用”，正文负责“被调用后做什么”。你保存之后，AI 读到 description 里的关键词，就会在合适的时机自动加载它。
3. 手把手创建第一个 Skill：从配置到首次调用
3.1 通过界面创建 Skill 的操作步骤
如果你使用的是带图形界面的版本，创建流程会非常直观。我按我自己的操作路径写一遍：
第一步，打开左侧设置面板，找到 Skill 管理项。第二步，点新建技能，名称填 commit-helper。第三步，把上面那段模板内容粘贴进去，注意 frontmatter 的三根短横线不能丢，YAML 冒号后面要跟一个空格。第四步，保存并关闭面板。第五步，回到对话输入框，输入斜杠，看看候选列表里有没有 commit-helper。第六步，随便挑一段真实的 git diff 粘贴进去，让它生成提交信息。
这一步虽然简单，大多数人还是会在第五步卡住：创建完直接就用，结果 AI 根本没反应。不要太早下结论，先确认工具确实重新扫描了 Skill 目录，有些版本需要重启插件面板才能识别新增的 Skill。
3.2 如果界面不支持，手动建目录一样能行
不是每个版本的 Trae 都提供了图形化的 Skill 新建按钮。遇到这种情况，最稳妥的方案就是手动建目录和文件：在你期望的作用范围内创建.trae/skills/commit-helper/目录，再用编辑器写一个 SKILL.md，内容就是上面那段模板，保存为 UTF-8 编码。
这样做的好处是你完全掌控文件位置，也方便后续用 Git 跟踪改动。唯一的坑是文件名和大小写：入口文件必须叫 SKILL.md，目录名建议用英文小写加短横线，不要用中文和空格。目录名就是 Skill 暴露给 AI 的名字，命名不规范会导致后续触发不稳定。
3.3 第一次测试 Skill，重点观察三件事
创建完 Skill，真正决定它能不能留下来的是测试。我每次测试新 Skill 都会观察三件事。
第一，触发是否成功：AI 有没有在合适的时机主动调用它，还是需要我在对话里反复提醒。第二，指令是否被完整执行：如果 Skill 要求输出表格却输出了文本，说明指令里有冲突或描述不够精确。第三，输出是否稳定：同一个输入连续测三次，结果是否大体一致，而不是每次风格都漂移。
如果发现输出不稳定，优先检查正文里的“约束”部分。约束写得越少，AI 的发挥空间越大，不稳定就越明显。我通常会在约束里加一条“严格按照工作流程顺序执行，禁止自行增加步骤”，这一句话能显著提高一致性。
4. 实战：把代码审查做成一条可复用的 Skill
4.1 需求分析与参数设计
代码审查是我个人用得最多的 Skill，因为它足够复杂，也足够体现 Skill 的威力。平时做一个 PR 的审查，要点开 diff、逐文件看逻辑、猜性能瓶颈，二十分钟起步，遇到不熟悉的老代码可能更久。而 AI 天生擅长读代码，缺的只是一套稳定的审查标准。
在写这个 Skill 之前，我先列了需要的变量：language，代码语言，决定审查经验；mode，quick 还是 detail，决定扫描的深度；focus，安全、性能、逻辑还是风格；output_format，表格还是纯文本。参数化的意思是：同一个 Skill 在“快速扫描”和“深入审查”之间切换，只需要在对话里给一个参数，而不需要维护两份文档。
4.2 完整代码审查 Skill 示例
我把这个 Skill 简化到一个可以直接照抄的版本：
--- name: code-review-helper description: 对指定代码或代码变更进行系统性审查，检查潜在缺陷、性能隐患、安全风险与代码规范问题。当用户提到 code review、代码审查、代码质量检查，或要求复查某段代码时使用。 when_to_use: 用户要求审查代码、检查 Pull Request、分析代码质量问题时。 variables: - name: language description: 需要审查的编程语言，例如 Python、Java，不确定时填 auto default: auto - name: mode description: quick 表示快速扫描，detail 表示深入逐行审查 default: detail - name: focus description: 重点关注方向，可填 security、performance、logic、style default: security - name: output_format description: 结果输出格式，table 或 text default: table --- # 角色 你是一名经验丰富的代码审查专家，精通多种编程语言，擅长发现逻辑漏洞、性能瓶颈、安全隐患和可维护性问题。 # 工作流程 1. 如果提供的是一段 diff，先逐项理解变更内容，判断影响范围。 2. 如果提供的是完整文件，先梳理结构，再按模块逐段审查。 3. 按优先级从高到低检查：阻断性缺陷（BUG、崩溃、数据丢失）> 安全隐患 > 性能问题 > 可维护性 > 风格问题。 4. 每发现一个严重级别为“严重”的问题，都必须给出文件或行号、代码片段、问题描述、修复建议。 # 输出格式 如果 output_format 为 table，使用 Markdown 表格： | 问题位置 | 严重级别 | 问题描述 | 修复建议 | # 约束 - 不要花费篇幅表扬代码，除非值得作为正面示例。 - 不确定的问题不要含糊其辞，基于代码逻辑给出判断；信息不足时先向用户索要上下文。 - 最后用三行总结：严重问题数量、整体评级、最优先修复项。这个示例充分体现了前面提到的设计原则。角色部分让 AI 进入专家模式，工作流程部分规定了执行的先后顺序，输出格式部分直接绑死了输出结构，约束部分剔除了无关内容。有了这四个部分，AI 的输出质量就基本可控了。
4.3 使用效果与影响范围
把这个 Skill 用在真实项目里，最直观的变化是时间。原来人工过一遍三百行变更可能需要二三十分钟，现在 AI 在几分钟内生成一份初版审查意见，我只需要核对严重问题是否属实、决定是否采纳建议。这不是把 AI 当老师，而是把它当一台自动筛出风险点的扫描仪。
从影响范围看，Skill 的价值不只是省时间。它让团队里的每个人都用同一套质量标准做代码审查，新人不再因为没经验而漏掉安全问题；它让规则随着代码仓库沉淀下来，团队成员调整后也不会丢掉原有的检查清单；它还为后续的自动化流转提供了基础，比如审查完可以顺手调用另一个 Skill 生成修复方案。这种“一次建设、长期受益、多人共享”的特性，才是它被称为效率神器的真正原因。
5. 进阶玩法：版本管理、组合流水线与团队共享
5.1 把 Skill 当作代码来管理
Skill 本质上是纯文本，所以完全可以享受代码管理带来的好处。我会把项目级 Skill 的目录纳入 Git 仓库，修改时像改代码一样提交变更记录，这样每次调整都有迹可循，出了问题也能回滚。
管理上我坚持三条规范。第一，命名统一：格式是“动作-对象”，比如 commit-helper、code-review-helper，不用中文也不用大写。第二，每个 Skill 目录里加一个简要的 README，写清楚适用场景、主要变量、更新历史，省得一个月后自己都忘了当初为什么这样写。第三，每次改完 SKILL.md 之后做一次小回归测试，用之前的测试输入验证结果没有退化。很多人觉得这是小题大做，但一旦 Skill 数量超过五个，混乱就会开始侵蚀效率。
5.2 多个 Skill 组合成工作流
单个 Skill 解决单点问题，多个 Skill 组合起来能覆盖一整条业务链条。我经常用的组合是：需求拆解 Skill 先把一句话需求展开成需求文档，接着代码生成 Skill 按需求文档产出实现方案，再交给代码审查 Skill 把关，最后让提交信息 Skill 生成一条规范的变更记录。
要让这条流水线顺畅，关键技巧是让每个 Skill 的输出都能被下一个 Skill 消费。比如需求拆解 Skill 把结果固定输出为 Markdown 标题加任务清单，代码生成 Skill 在第一个步骤里就明确“从需求文档的任务清单中逐项生成代码”。如果上一个输出是乱七八糟的散文，下一个 Skill 就不得不靠猜来提取关键信息，整个链条的质量都会崩。所以建议在 Skill 的产出阶段统一使用结构化格式，能用表格就用表格，能列清单就列清单。
5.3 团队共享与分发建议
如果你在团队里发现某个 Skill 特别好用，完全可以把它分享出去。最朴素的做法是把 Skill 目录打包，附带 README 发到内部仓库。为了减少别人的使用成本，我会在 README 里写清楚三样东西：这个 Skill 解决什么问题、需要哪些环境支持、有哪些推荐参数组合。
分享前一定要做一次“敏感信息扫描”，因为 Skill 里的示例和描述未必包含密钥，但可能包含内部项目代号、特定业务约定，这些对团队外的人可能是噪音甚至是风险。一个干净的 Skill 应该是通用的、自解释的，拿掉组织上下文之后依然能正常工作。能做到这一点，你的 Skill 已经从个人脚本升级成了团队的公共资产。
6. 常见问题与排查技巧实录
6.1 Skill 没有被 AI 识别，第一件事查这里
遇到 Skill 不生效，我通常按下面的顺序排查。
第一步，检查目录和文件名。入口必须是 SKILL.md，目录名不要带空格和中文，大小写尽量统一。很多时候问题就出在文件名写成了 skill.md 或者 Skill.md，工具是区分大小写的。第二步，检查 frontmatter 是否合法。YAML 对格式很敏感，冒号后少了一个空格，整段配置就可能解析失败。第三步，检查 description 是否覆盖了你的任务描述。AI 是靠 description 来决定要不要加载 Skill 的，你的任务表述和 description 里的关键词差异太大时，它宁可不用。第四步，重启面板或重新加载项目，排除缓存问题。
6.2 生成结果不符合预期，问题多半出在指令本身
如果 Skill 能被触发但输出质量差，九成问题出在指令本身。最常见的情况是正文写得太空，只有一句“请帮我审查一下代码”，AI 就只能自由发挥。解决办法是把工作流程拆成步骤，每个步骤给一个明确动词，再给一个输出格式示例。有了格式示例，AI 的输出就会往这个形状上靠。
另一个高频问题是变量没传对。比如 Skill 定义了 language 变量，对话里没有提供，默认值又是 auto，AI 可能就不按目标语言去分析，直接拿自己最熟悉的语言习惯来套。如果你在某个项目里反复遇到这种情况，可以把默认值设置为该项目常用的语言，而不是 auto。实际体验下来，“信息不足时先向用户提问”这句话能解决一大半的返工问题。
6.3 多个 Skill 相互冲突怎么办
当你的 Skill 多起来之后，会遇到两个 Skill 同时被触发、指令互相打架的情况。比如代码审查 Skill 要求“直接基于代码逻辑判断”，另一个规范 Skill 却要求“先列出风险再输出结论”，AI 就会在两者之间摇摆。
解决思路有三个方向。第一，在 frontmatter 的 when_to_use 里加上更严格的条件，比如限定到“当用户要求审查 pull request 时”，减少误触发。第二，把互相相关的 Skill 合并成一个，在同一份文档里用分节的方式管理不同用途。第三，调整 description 里的措辞，让两个 Skill 的触发词尽量错开。我的经验是，大部分冲突都源于触发词重叠，先把 description 写好，往往比改正文更见效。
6.4 踩坑避雷速查表
最后把常见问题汇总成一张表，方便你直接对照排查：
| 现象 | 可能原因 | 解决办法 |
|---|---|---|
| Skill 完全不出现 | 目录或文件名不对 | 确认是 SKILL.md，目录不含中文和空格 |
| frontmatter 解析失败 | YAML 格式错误 | 检查冒号后的空格、缩进、特殊字符 |
| 总是被误触发 | description 写得太宽泛 | 加上精确的触发条件 |
| 输出风格漂移 | 约束太少 | 增加输出格式模板和禁止事项 |
| 变量不生效 | 参数名与正文引用不一致 | 统一变量名，避免大小写混用 |
| 改完没变化 | 未重新加载 | 保存后重启面板或重新加载项目 |
| 团队共享后失效 | 路径或版本不一致 | README 中注明目录结构和版本要求 |
我个人用过一段时间后的感受是，Skill 最大的坑不是技术，而是贪多。我一度建了十几个 Skill，最后高频使用的只有三四个，其他的都成了躺在目录里的僵尸文档。真正有价值的 Skill，一定是你每个星期都会遇到、每次都要花一点时间思考的重复性工作。把这种工作固化下来，其实不只是省时间，也是在把一个团队的隐性规范变成显性资产。建第一个 Skill 的时候，从最小场景开始，用起来之后一点点迭代，这个节奏比一次性规划一整套要健康得多。希望你也能早点体会到这种“调教一次，长期受益”的乐趣。
