Trae如何使用Skill?Trae 里使用 Skill 的路子很短:把一份 SKILL.md 放进项目 .trae/skills/ 目录(或在「设置 → 技能与命令」里创建、导入),然后在对话里点名"用某某技能做这件事",或等 AI 按技能描述自动调用。据官方 Changelog,Skills 自 2026 年 1 月 23 日的正式版起已支持 IDE 与 SOLO 两种模式。本文按创建、编写、调用、排坑四条线讲清。 Trae的Skill是什么
一个 Skill 就是一个文件夹加一份必需的 SKILL.md,文件里写清三件事:在什么条件下用(When)、按什么步骤做(How)、产出什么结果(What)。文件夹里还可以按需放 examples/(输入输出示例)、templates/(可复用模板)、resources/(参考文件、脚本、素材)。
它和"把要求写进规则"最大的差别在于加载方式。规则是全量加载:一旦开始对话,所有规则都被注入并持续占用上下文;技能是按需加载:智能体先只扫一遍所有技能的简要描述,判断当前任务确实相关,才把这个技能的详细内容读进来。这就是官方文档反复强调的"动态按需加载"——它省的不只是 token,更避免了无关信息干扰模型判断。
所以判断"要不要做成 Skill",官方给的问法很直接:这件事你是不是需要做第二次以上,而且它更适合用结构化的指令来描述?官方英文文档给了个更朴素的标准——同一句提示如果你已经打了三遍,就该把它写成 SKILL.md 了。
TraeCode 目前内置了 4 个技能,可以直接拿来参考官方是怎么写的:
- TRAE-security-review:代码安全扫描,审查合并请求与代码差异中的漏洞风险。
- TRAE-code-review:代码审查,针对质量、正确性与工程实践给出结构化反馈。
- TRAE-debugger:运行时调试,启动调试服务器收日志,按"假设 → 插桩 → 复现 → 分析 → 修复 → 验证"推进。
- TRAE-generate-mini-app:生成基于 Taro 框架的多端小程序代码。
⚠️ 先破一个流传很广的过时说法:网上大量教程(含 2026 年 3 月前后的社区帖)仍在说"Skills 功能只在 SOLO 模式下可用"。这曾经是对的,但已经不是现状。据 TRAE 官方 Changelog:2026 年 1 月 13 日(v3.5.21)Skills 首次上线,当时确实仅支持 SOLO 模式;2026 年 1 月 23 日(v3.5.24 / v3.5.25)升级为正式版,已支持在 IDE 模式与自定义智能体中使用,并新增全局 / 项目两类技能与启停开关。同一批老教程里"设置 → 规则技能"这个菜单路径也已改名,中文文档当前口径为 「设置 → 技能与命令」(英文文档写的是 Settings → Rule & Skills),照着旧路径找会找不到入口。
Skill与规则、MCP、子智能体的区别
Trae 里能"引导 AI"的机制有好几种,选错就会写出一个又长又贵的规则文件。按官方文档与官方博客的口径,一张表说清各自的位置。
| | |
|---|
| | 临时、探索性的需求;同一句提示重复到第三次,就该改写成 Skill |
| | 只留轻量偏好:代码风格、回答语言、目录约定;工作流指令应搬进 Skill |
| | |
| | 需要独立分工的专门工作;若多个子智能体都要同一份专长,抽成 Skill 复用而不是各写一遍 |
| | 需要外部能力时(浏览器操作、数据库等);"怎么把工具用好"这层约定交给 Skill |
| | |
一句话概括:MCP 决定"能调用什么",Skill 决定"该怎么调用、按什么流程调用"。官方举的例子是 Playwright 场景——MCP Server 提供页面操作能力,Skill 则约定测试工程结构、页面对象模型设计和用例编写流程。
三种创建Skill的方式
官方文档给了三条路径,覆盖从"我现在就要一个"到"我已经有现成的"全部情况。
| | |
|---|
| 直接在对话框里描述需求,例如"帮我在 .trae/skills 目录下创建一个新的技能,名字叫某某,这个技能可以帮我做以下几件事:……" | |
| 设置 → 技能与命令 → 技能 → 创建,先选类型(全局 / 项目),再填技能名称、描述、指令三项,点确认 | |
| 同一入口上传一个 SKILL.md,或包含它的 .zip 包;系统会自动分析并填充名称、描述、指令三个字段,按需修改后确认 | |
创建完成后的落点不一样:全局技能会直接出现在「技能」面板的「全局」页签下;项目技能则由 TraeCode 自动在项目的 .trae/skills/{技能名}/ 目录下新建 SKILL.md,同时出现在「项目」页签下,需要配套脚本时,就在这个技能文件夹里手动补进去。
SKILL.md怎么写
官方文档给出的最小格式是这样,前面是 YAML 元数据,后面是四段正文:
元数据这两行看着简单,却是最影响成败的地方——模型就是靠它判断"这个技能跟当前任务有没有关系"。官方最佳实践给了明确的写法规范:
- name:简洁、唯一的标识符;用小写字母、数字和连字符;推荐动名词形式;长度不超过 64 个字符。好的例子是 running-tests、deploy-microservice、database-migration;反例是 test-helper(语义模糊)、data-skill-v2(含版本信息)、deployService(命名不规范)。
- description:用第三人称、从模型视角描述;要包含核心功能与触发时机的关键词;长度不超过 1024 个字符。反例是"I can help you review code"(第一人称)和"Helps with code review"(没写触发时机)。
正文部分,官方推荐按五个标准来写,缺一项就多一分不确定性:
- 边界明确:既写正向条件(Use this skill when),也写负向条件(Do NOT use this skill when)。官方原话是,模型最容易犯的错不是"不知道怎么做",而是"不知道什么时候该做"。
- 输入输出结构化:像函数签名那样写清 Input 和 Output 的字段、类型与可选性,不要用"帮用户跑一下测试"这种模糊说法。
- 步骤明确可执行:指令要是指令式的具体动作,不是概括性描述。反例是"检查 PR,运行测试,然后更新状态"。
- 失败策略完备:显式写出 On Failure——校验失败怎么回、重试几次、什么情况通知人。模型失败时容易自由发挥。
- 职责绝对单一:一个技能只做一件事,对应一个核心动作。把"运行测试 + 更新 PR 状态 + 发通知 + 跑 lint"捆在一起,命中率会明显下降。
还要给约束强度分级:方法多解、依赖上下文的任务给原则(如代码审查先看安全性再看可读性);有首选模式、允许变通的任务给模板或伪代码;操作脆弱、必须固定顺序的任务给可执行脚本(如数据库迁移)。
让SKILL.md保持可维护
官方把这一层叫"渐进式披露":SKILL.md 是入口和导航,不是包罗万象的大文件。三条可直接照做的规则:主体内容尽量控制在 500 行以内;引用文件保持一层引用深度,避免 A 引用 B、B 又引用 C 的链式结构;超过 100 行的参考文件,在顶部加一个目录。
如果技能里带脚本,脚本的健壮性优先于巧妙:错误要显式处理并给出下一步建议(形如 ERROR: 文件未找到 加一行 HINT: 请检查路径,或运行 init-config.sh 生成默认配置),验证类脚本要明确列出通过项与失败项,不要把 TIMEOUT = 30 这种数字直接丢进去——任何影响行为的常量都要有语义化命名和来源说明。
两种调用方式:手动指定与自动触发
技能创建好之后,触发它有两种路径。
| | |
|---|
| 在对话里直接点名,例如"用 codemap 技能总结一下这个分支的改动" | 要结果可复现、不想让 AI 猜的场景;复杂任务优先用这种 |
| AI 结合当前任务与技能里"使用场景 / 何时使用"的描述,自行判断并在合适的阶段加载 | |
官方举的例子很好懂:如果你定义了一个触发条件是"当用户请求代码反馈或评审时"的代码审查技能,那么当你说"这个函数写得如何""帮我审核以下代码"时,AI 会识别出相关性并自动加载该技能,不需要额外指令。反过来说,自动调用能不能命中,几乎完全取决于 description 和"使用场景"写得好不好——这也是下面"五个常见坑"里的第一条。
全局技能与项目技能的区别
正式版新增的两类技能,是这次升级里最实用的改动:把"跨项目通用"和"只属于这个项目"的东西分开,避免全局技能被一堆项目细节污染。
| | |
|---|
| 跨项目生效。适合统一代码风格与命名规范、通用工具链用法(Git、CI/CD 等)、个人或团队长期偏好(是否先给结论、是否列步骤) | macOS / Linux:~/.trae-cn/skills;Windows:%userprofile%/.trae-cn/skills |
| 仅当前项目生效。适合项目专属业务约束与术语、既定技术栈与框架版本、针对本项目的测试与脚手架生成 | 项目目录下的 .trae/skills/{技能名}/ |
两件事顺带记一下:项目技能可以点齿轮图标选择「应用到全局」,直接转成全局技能;技能也能随时关闭,不用的时候关掉可以避免被打扰。
技能目录、重名与导入开关
除了 .trae/skills/,Trae 还认一个来自开放规范的目录,两者的优先级不一样。
| |
|---|
| 在 TraeCode 内创建的技能默认落在这里。两个目录出现同名技能时,优先调用本目录中的技能 |
| 由 Agent Skills 开放规范约定的目录,把技能放进项目即可让智能体运行时自动发现;但需要先在设置 → 技能与命令 → 导入设置里打开「启用 .agents 技能目录」开关 |
往 .agents/skills/ 里装技能,可以用内置的 find-skills 技能,它依托一个名为 skills 的命令行工具,能从开放生态里搜索、安装和管理技能包;从 GitHub 下载或 clone 之后导入也是同样效果。
另外,技能的启用状态是有文件记录的:关闭某个技能后,TraeCode 会在项目的 .trae/ 目录下创建 skill-config.json,里面罗列被禁用的项目技能;被禁用的全局技能不会写进这个文件。团队协作时如果发现"我这边技能没触发、同事那边正常",先看这个文件。
五个常见坑
- 坑一:目录放错或撞名。技能放哪儿决定了它什么时候生效——项目专属的放 .trae/skills/,跨项目复用的放 ~/.trae-cn/skills。放进 .agents/skills/ 却没在设置里打开「启用 .agents 技能目录」开关,技能等于没装;两个目录同名时又会优先取 .trae/skills/,于是你以为在用 A,实际跑的是 B。
- 坑二:description 边界不清。只写"这个技能用来做代码审核",模型就只能靠猜。正确做法是同时写清该用和不该用的条件——官方反例是"用户想让流水线跑一下测试"这种表述,正例则明确到"PR 状态为待合并、需要执行自动检查时才用;只是查看测试报告时不用"。
- 坑三:一个技能塞太多功能。把运行测试、更新 PR 状态、发通知、跑 lint 打包进同一个技能,看起来省事,实际会让模型难以判断何时该用、从哪里开始,命中率和稳定性一起下降。拆成四个单一职责的技能,反而更可靠。
- 坑四:把 SKILL.md 写成给人看的文档。技能是下达指令,不是解释原理。写成"这个技能可以帮助团队提升代码质量"这类宣传句、或者步骤全是概括性描述,模型拿不到可执行的动作序列。同理,正文写成上千行也没有收益——500 行以内、一层引用、长文件加目录,才是官方推荐的结构。
- 坑五:没有基线也没有评测,就一直往上加规则。官方最佳实践的顺序是"先跑一遍不用技能的基线 → 记下不稳定和走偏的地方 → 写 3 到 5 个能判定通过与否的用例 → 再写最小可用技能"。等用过一段时间暴露了新问题,再补规则。评测没通过时,正确动作是简化技能,而不是继续叠加新条款。另外记得别把时效性内容写死进技能("2025 年 8 月前用旧接口"这种),官方建议把过期配置挪进 deprecated/ 目录并标注。
Trae Skill常见问题
Q:用 Skill 要额外付费或装插件吗?
A:不需要。技能是 TraeCode 自带的能力,本质上就是你项目或本地目录里的一组 Markdown 文件,创建和管理都在设置里完成。
Q:Skill 只能在 SOLO 模式下用吗?
A:不是。这是过时教程里最常见的错误。据官方 Changelog,2026 年 1 月 13 日的版本仅支持 SOLO 模式,但 2026 年 1 月 23 日的正式版已扩展到 IDE 模式与自定义智能体。
Q:Skill 和规则(Rules)到底该用哪个?
A:看是否需要常驻。规则是全局全量加载、一直占用上下文,适合轻量的风格偏好;技能按需加载,适合有明确步骤的工作流。规则文件变臃肿时,把工作流部分搬进技能是官方推荐的做法。
Q:SKILL.md 要写多长?
A:官方建议主体控制在 500 行以内。更详细的内容拆成独立文件由 SKILL.md 链接,保持一层引用深度,不要链式引用。
Q:怎么让技能更容易被自动触发?
A:两处下手——名字要直观可识别,description 要写清"什么时候用"和"什么时候不要用"。官方原文的表述是:触发条件写得越具体,命中越准。
Q:技能应该放在哪个目录?
A:项目专属放项目下的 .trae/skills/;跨项目通用放全局目录(macOS / Linux 为 ~/.trae-cn/skills)。若使用开放规范的 .agents/skills/,需先在设置里打开对应开关。
Q:怎么关掉某个技能?已经关掉了为什么别人还说是开着的?
A:用技能列表里的开关即可。注意禁用状态是分层的:被禁用的项目技能会写进项目 .trae/skill-config.json,被禁用的全局技能不写进该文件,所以团队里各人的全局技能状态本来就可能不一致。
Q:项目技能能变成全局技能吗?
A:可以。在技能列表里点该项目技能右侧的齿轮图标,选择「应用到全局」即可转换。编辑与删除也在这个菜单里。
Q:从 GitHub 下载的技能怎么装进来?
A:两条路——在「技能」里点创建,上传 SKILL.md 或包含它的 .zip,系统会自动解析并填充名称、描述、指令三个字段;或者把技能放进项目的 .agents/skills/ 目录,再到设置 → 技能与命令 → 导入设置里打开「启用 .agents 技能目录」。
Trae如何使用Skill?现在清楚了吧?本文的分享就到这里结束了,赶紧操作试一试吧~