这个标题，初看像是一条随手保存的带时间戳的备忘，20260122_165625，前面是日期，后面是秒数。但我更愿意把它看成一份给自己的提醒：别在工具迭代最快的这一年，继续用老办法写代码。
这段时间，AI 编程工具基本都长成了一个样子：侧边聊天、选中代码、生成补全，模型越换越强，但你会发现，不同人用同一款工具，产出效率的差距反而在拉大。问题不在模型，而在“使用方法”。真正拉开差距的，不是谁的提示词写得长，而是谁把重复性的思考过程沉淀成了能复用的“技能”。TRAE_Skills 就是一个让你把约定、流程、规范打包成独立能力单元的机制。这篇文章适合所有正在用 AI 编程助手、但总觉得“还差一口气”的开发者。读完你不仅能明白技能背后的设计思路，还能直接跟着步骤，从零构建出属于自己的第一个技能。
1. 先认清一个事实：工具同质化之后，拉开差距的是“技能”
说句实在话，2026 年的 AI 编程助手，大家在模型能力上的差异已经很小了。你用的底层模型，和你同事用的，很可能就是同一款。那为什么有人能一个下午把半周的工作干完，有人还在为一段报错反复追问？区别在于，前者的工具使用方式，已经从业余的“聊天模式”切换到了专业的“技能模式”。
1.1 为什么默认的对话方式不够
默认的对话方式，本质上是“每次从零开始”。你让模型按团队规范写一个用户登录接口，模型可以写，但你需要把规范重新粘贴一遍；你强调过“不要引入第三方库”，下个项目它照样忘；你上个月定的“所有新代码必须带错误处理”，你自己都忘了，它更不可能记住。
这不是记性问题，而是机制问题。对话式 AI 是无状态的，它唯一能依赖的就是当前会话的上下文。你换一个会话，它就把你当陌生人。你试图把规范长期挂在对话里，又会发现三个麻烦：对话一长，模型开始抓不住重点；粘贴规范这件事本身很费时间；最麻烦的是，团队里的其他人根本不知道你保留过这些约束，只能从头踩坑。
1.2 TRAE_Skills 的组成与运行机制
TRAE_Skills 的出发点，就是把“每次从零开始解释”变成“一次定义，处处复用”。在我自己的项目里，我是这样组织的：在项目根目录创建一个.trae/skills文件夹，里面每个技能就是一个独立子目录。一个技能文件夹通常包含一个SKILL.md文件，头部用 YAML 写元信息，正文用 Markdown 写完整的执行逻辑。
项目目录/ .trae/ skills/ code-review/ SKILL.md checklist.md机制上，当你在对话中输入“帮我审查这次改动的代码质量”这类需求时，TRAE 会根据技能元信息里的name和description，判断当前用户意图是否命中了这套技能；命中后，它会把SKILL.md里的指令、约束、示例注入到上下文中，作为本轮回复的行为准则。
这个机制最微妙的地方在于：技能不是“插件”，不是那种脱离主流程的功能模块，它更像是一份“现场操作手册”。模型依然由你自己主导，但手册会约束它按固定的流程、固定的输出格式去执行。这就保证了，你和队友触发同一个技能时，结果的一致性远高于自由发挥的对话。
2. 动手之前，先把 Skill 设计成“业务流程”
很多人在第一次接触 skill 时会犯同一个错误：直接写。写下几条“你要小心处理边界”“输出要规范”之类的废话，然后发现技能聊胜于无。问题在于，技能不是一段更长的提示词，而是一套业务流程的抽象。设计阶段想不清楚的事，写进指令里也一定是空的。
2.1 触发场景是写 description 的核心
技能能否被正确唤起，百分之七八十取决于description怎么写。我见过很多人的 description 写成了“用于代码审查”，结果真正需要审查时，模型却认为没必要调用，因为模型自己也能“看两眼代码”。问题就是描述没有讲清楚：什么时机、什么信号、什么诉求下，才需要启动整套流程。
以代码审查技能为例，理想的 description 里应该出现这样的信息：“当用户对一批代码改动提出复查、检查、提交前评审，且涉及多个文件、跨模块调用或上线前安全确认时使用；该技能会按检查清单逐项评估，并输出缺陷等级、修改建议和风险摘要。”
这句话交代了触发词“复查、检查、评审”、触发条件“多个文件、跨模块、上线前”、以及使用后的效果“逐项输出缺陷等级”。模型识别到这些关键词，再结合用户请求的上下文，命中率就会高很多。反过来，如果 description 只有一句“检查代码问题”，模型大概率不会启动技能，因为它认为普通对话已经够用了。
2.2 输入、输出和中间过程都要定义清楚
一个技能要有用，必须在设计文档里明确三件事：你交给模型的输入是什么，模型必须给出的输出是什么，中间要经过哪些步骤。缺少任何一个，执行起来都会飘。
拿“git 提交信息生成”这个技能举例，设计时可以这样定义：
- 输入：
git diff的结果、本次提交涉及的模块名、有没有关联单号或需求编号。 - 流程：先读取变更文件清单，分析改动类型是新增、修复还是重构，再总结影响范围，最后按团队提交规范生成信息。
- 输出：一段符合 Conventional Commits 规范、首行不超过 50 字、正文可展开说明的提交信息。
你看，输入和输出都有边界。模型不会自由发挥，不会在生成提交信息时顺手给你讲一段 git 原理。它只会像一个熟练的同事那样，按流程做事。
这里我想多说一句“中间过程”的重要性。很多技能失效，是因为你把“流程”写成了“要求”。要求是结果导向，流程是步骤导向。比如你写“必须检查数据库索引使用情况”，模型可能会做，也可能敷衍两句就跳过。但如果你写“读取迁移文件，找到本次新增的查询语句，确认涉及的列上是否有对应索引，若没有索引则输出优化建议”，它就不得不按步骤走。步骤越具体，越不容易被跳过。
2.3 约束越具体，模型越可控
技能里最怕出现的话是“注意代码质量”“确保安全性”这类空泛表述。模型确实会“注意一下”，然后继续按默认方式输出。我在实际使用中体会到，约束必须落到可判断、可执行的具体操作上。
举个例子，与其说“不要使用过时的 API”，不如列一份黑名单表格：本地存储优先使用当前框架的持久化方案，旧有的localStorage直接访问方式视为违规；网络请求统一走封装好的request方法，禁止裸调用底层客户端。把“纪律”翻译成“规则清单”，模型就能像一个熟悉团队规范的老员工一样落实到每一行代码。
另外，约束里一定要包含“停止条件”。技能不是万能的，当输入信息不足时，正确的做法是停下来向用户求证，而不是硬着头皮猜。我在技能模板里经常写这样一条：“如果发现关键信息缺失，例如未能读取到完整的改动文件列表，应立即询问用户补充，不要基于猜测输出结论。”
3. 从零构建：一个可落地的代码审查 Skill 全过程
理论说得再多，不如亲手建一个。下面我用“代码审查”这个场景，完整走一遍从目录创建到首次验证的过程。这套流程不依赖二次开发，也不需要写代码，只需要掌握 Markdown 和基础的 YAML。
3.1 先建目录：让 Skill 成为项目的一员
首先，在你的项目根目录下创建.trae/skills/code-review/文件夹：
mkdir -p .trae/skills/code-review cd .trae/skills/code-review这里有一个容易忽略的点：技能文件夹的命名最好用连字符分隔的小写英文，例如code-review、commit-message、api-schema-check。因为name字段会作为技能的唯一标识，如果包含中文或大驼峰命名，在触发阶段容易出现匹配方面的不确定性。目录建好以后，里面放两个文件：SKILL.md和checklist.md。
职责划分也很明确：SKILL.md负责“流程”，告诉模型审查分几个阶段、每个阶段要做什么、遇到问题怎么处理；checklist.md负责“标准”，提供具体的检查项和判定规则，相当于给模型一张打分表。这么分开写的好处是，团队更新审查标准时，只改checklist.md就够了，不会影响大流程的稳定性。
3.2 SKILL.md 元信息怎么写
在SKILL.md的最顶部，写一段 YAML front matter：
--- name: code-review description: 对代码变更进行系统性审查。当用户提交多文件改动、准备发起合并请求、或要求检查代码质量与潜在缺陷时激活。审查将按标准清单逐项评估，输出缺陷等级、风险摘要与修改建议。 ---注意，front matter 是固定格式，---两侧不能省略，字段名必须是全小写，冒号后要有空格。很多新人在这里栽跟头——漏了闭头分隔线，或者缩进不对，技能直接无法解析。写完以后，建议顺手检查一下文件是否以换行符结尾，这两个细节都是常见的解析报错原因。
description 我特意没有写“代码审查”四个字就结束，而是补上了触发条件和输出形式。前面说过，这一句直接决定技能会不会被唤起。你可以在 description 里多写几个同义触发词，比如“复查”“检查”“评审”“上线前把关”，这些词会被纳入匹配逻辑。但也不要堆砌成五十字的营销文案，描述太长会稀释关键信息，模型反而不容易抓住重点。
3.3 主指令部分的结构与措辞
接下来是SKILL.md的正文，也就是模型真正会读进去的指令。我的建议是结构分为四块：目标、执行流程、输出格式、兜底规则。下面是按这个思路搭出来的骨架，你可以直接复制调整：
# 代码审查技能 ## 目标 在用户发起代码审查请求时，基于改动范围内的文件， 检查逻辑正确性、风格一致性、潜在缺陷与提交规范， 输出可执行的修改建议。 ## 执行流程 1. 获取改动范围：优先读取用户提供的文件清单， 如果有 git 环境，可以尝试比对暂存区与工作区的差异。 2. 逐文件扫描：按 checklist.md 中列出的检查项， 对每个文件执行评估，记录问题所在行号与类型。 3. 交叉检查：当多个改动文件存在互相引用时， 额外检查接口签名、依赖关系与调用链上的变化。 4. 汇总输出：将问题按严重程度分为阻塞级、建议级、可选级三类， 阻塞级问题必须给出最小修复方案。 ## 输出格式 - 按类别分区块输出，每一类先列总数，再陈列问题列表。 - 每条问题包含：文件路径、行号、问题描述、修复建议。 - 如果检查中未发现任何阻塞级问题，需要在开头明确说明“未发现阻塞级问题”。 ## 兜底规则 - 如果无法读取到改动文件清单或相关信息不完整， 必须停下来询问用户补充，严禁编造审查结果。 - 对所有修复建议，必须基于代码事实，不得臆测。你可能会注意到，这个指令里全是“步骤”和“规则”，几乎没有语气词，也没有“请”“务必”这类请求式表达。原因是，技能不是让模型帮你一个忙，而是让它遵循一套流程。流程口吻的指令，模型执行起来更像“遵循手册办事”，效率远高于“听取要求办一件事”。
3.4 首次验证与迭代调整
写完SKILL.md，别急着让它进团队库。先在真实代码上用一次，观察输出质量，再决定怎么改。以我自己的经验，第一次测试基本都会暴露两个问题：一是输出格式与预期不符，比如模型把问题堆在一个自然段里，没有分行；二是检查深度不够，它只看了表面命名问题，没挖出逻辑缺陷。
针对格式问题，解决办法是强化“输出格式”部分的示例。Markdown 里的例子有奇效，因为模型对示例的模仿能力远强于对文字规则的理解。你可以在SKILL.md末尾追加一小段“输出示例”，用代码块展示一条阻塞级问题应该长什么样：
## 输出示例 阻塞级问题（2） - src/user/service.ts:114 对未登录用户直接返回用户资料， 存在越权访问风险。建议在方法入口增加会话校验， 参考 src/auth/middleware.ts 中 checkAuth 的用法。把示例塞进去之后，第二次测试的输出格式就基本稳定了。这也给我一个启发：技能文件的迭代核心是“示例驱动”，不要靠增加抽象规则来修正模型行为，给它看一个具体样本，比写三行强调性描述更管用。
4. 调试与共享：技能不被调用时，先查这三个地方
技能不是写完就能一劳永逸。在我把技能从个人项目推广到团队项目的过程中，遇到过不少奇怪现象，我把最常见的几个问题整理出来，排查顺序也排好了，按照这个顺序查，基本能定位八成问题。
4.1 技能没有被唤起？先查 description 而不是指令
当你发现自己在对话里明明说了“帮我审查代码”，技能却没有生效，第一反应别去怀疑指令写得不好，更别去翻技能正文反复调整措辞。你要检查的是description。技能唤起依赖的是元信息匹配，正文指令压根不参与触发判断。
最常见的失败原因，是 description 里的场景词和你的习惯用语不匹配。比如你平时总说“看一眼这段代码有问题没”，而 description 里只写了“代码审查”“review”。这时候模型会优先把它理解成一个普通的分析请求，去走通用对话流程。解决办法是回到 2.1 里说的触发词设计，把你真实使用场景中的口语词都补进去。
还有一种情况也常见：项目里有多个技能，它们的 description 描述的场景过于接近，导致模型不知道该选谁。比如同时存在code-review和refactor-check，描述里都是“检查代码质量”，模型很可能错误唤起其中一个。出现这种情况时，需要给不加技能划出边界——审查技能聚焦“改动与合并前”，重构检查聚焦“代码结构与性能隐患”——让描述互相错开。
4.2 指令与模型能力的边界：别让 Skill 替你完成一切
第二个高频问题是期望错位。有人把技能当成一个全自动执行器，认为写好指令后，模型就能像流水线一样完成整个任务。实际上，技能只是“行为公约”，它约束的是模型的工作流程和输出格式，并不改变模型本身的能力上限。
遇到模型做不了的事，比如需要读取特定系统权限下的真实配置，或者需要执行一条可能产生副作用的编译命令，技能写再多也没用。这时候，H2 级别的解决办法是：把这类任务拆成“技能给出步骤 + 用户在终端执行 + 结果反馈给技能继续分析”的循环。我在技能指令里会明确写上“如果步骤 3 需要在外部环境执行，请输出具体的命令，等待用户回传执行结果后继续”。这样既利用了技能的流程约束力，又不指望模型越界处理它做不到的事情。
另外要提醒的是，不能把敏感信息写进技能文件。技能文件通常跟随项目仓库同步，一旦入库就会被团队成员甚至更大的协作范围看到。密钥、内部接口的鉴权逻辑、未公开的业务细节，都不应该出现在技能里。需要用到的敏感配置，应该通过环境变量引用，并在指令中写清楚“读取环境变量 X，不要输出其值”。
4.3 团队共享、版本管理与持续迭代
技能文件本身是文本，天然适合放进代码仓库做版本管理。我在团队里推广时，直接把.trae/skills目录放在项目仓库根目录下，这样每个成员拉取代码后就自然同步了。最初也有人反对，觉得SKILL.md不是代码，没必要走评审流程。但正是因为没有评审，技能质量才会参差不齐。
我建议把技能文件的变更当成普通代码对待：合并前需要过 review，说明改动动机和影响范围；版本历史要保留在提交记录里，方便追溯。还有一个更实际的问题：技能里写的部分规则可能只适用于个别模块，如果整个项目共享一份全局技能仓，别的模块就会遭殃。解决办法是项目级技能放通用流程，模块特有规则通过外部引用文件挂进来，例如在指令中写明“读取docs/modules/order/rules.md中关于订单模块的额外约束”。这样既保持了全局技能的稳定，又兼顾了局部上下文。
持续迭代方面，我有一个固定的节奏:每次项目复盘时候，顺手把当周在对话里重复说明超过两次的内容，提炼补充进SKILL.md或checklist.md。这个小习惯让技能文件始终保持和团队现状同步，而不是写完就变成摆设。
5. 说几句没人写进文档的体会
文章写到这里，你会发现我几乎没有讲什么高深的技术。TRAE_Skills 本质不是一个编程工具，而是一套知识管理的思路。十来年前，我们靠文档沉淀团队规范，靠代码评审传递经验；现在，技能把沉淀和传递捏到了一起——规范写进指令，经验变成流程，每次模型执行技能，等于团队里最有经验的那个人在给所有参与者示范一遍该怎么做。
我个人实际操作中的体会是，别一开始就追求做一个大而全的“超级技能”。把目标定小一点：先挑一个你每周至少做三遍、且输出结果可以模板化的任务，比如生成提交信息、写接口文档、做上线前检查清单，用一下午把流程写进技能文件，用一周时间打磨示例和边界。等这一个小技能真正稳定运行了，你会对这种工作方式有一种“手上有趁手工具”的踏实感。
再分享一个小技巧：技能文件不要一口气写完。先写一版能跑的，然后故意不完善它，带着“这次用完下次再修”的心态去用。因为只有真实使用，你才知道哪些规则是模型容易忽略的，哪些检查项在项目里根本不触发。频繁小步更新，比憋一个完美版本再发布，效率高得多，质量也稳得多。
最后，时代不会淘汰会用 AI 的人，只会淘汰把 AI 当聊天框的人。当你开始把自己的工作流能力化，从一个“用工具的人”，变成一个“定义工具如何工作的人”，10 倍效率只是个顺带的结果而已。
