项目技能放在 .trae/skills/<名称>/SKILL.md，个人技能放在 ~/.trae-cn/skills。一个技能必须有 SKILL.md，前置元数据里 name 和 description 必填。助手靠 description 决定要不要加载它，所以正文只留步骤，长说明放到同目录的其他文件；必须点名才执行的固定流程，写成命令，不要和技能放在同一个触发方式里。
有三种情况会打开这一页：同一段做法已经讲了三遍，想让它自己被想起来 → 抄「示例：一个技能加一份参考文件」，先改 description；技能写好了却从没被自动加载 → 看「没生效时的现象与修法」第一条；改了一份技能、对话里用的还是旧的 → 看第二条，去 .agents/skills/ 查有没有重名的那一份。
写错最多的是三件事，先记住。一，description 写得太笼统：只写「一个处理检索的技能」，助手判断不出什么时候该用，技能就从没被加载过。二，把产品功能写进技能：面向最终用户的能力属于需求和接口说明，.trae/skills/ 里只放给编程助手的步骤。三，同名技能放了两份：.agents/skills/ 要另开开关，重名时以 .trae/skills/ 为准，改错那一份等于白改。
不点名，只说一句「改一下检索」，助手会不会自己加载这个技能？
答「不会」，先改 description，写明什么任务里用。改完开一轮新对话，提一次相关任务再试。
技能和规则的分工用一句话就能分清：规则全量加载，进来就一直占上下文；技能按需加载，只在被判断为相关时才进来。所以把「每次对话都要遵守」的写成规则，「某类任务才用得上」的写成技能。
| 项 | TraeCode 的写法 | 写错的后果 |
|---|---|---|
| 项目位置 | .trae/skills/<名称>/SKILL.md | 放到别的目录，不会被发现 |
| 个人位置 | ~/.trae-cn/skills | 只在自己电脑上，小组共用就丢了 |
| 必需字段 | 前置元数据里的 name 与 description | 缺 description，助手无法判断何时加载 |
| 触发依据 | 只靠 description 判断相关性 | 写得笼统就等于不会被加载 |
| 正文写什么 | 分步指令，以及复查用的输入与期望输出 | 正文太长，每次加载都占更多上下文 |
| 长说明放哪 | 同目录的其他文件，如 reference.md | 塞进正文，等于每次都全量加载 |
| 另一个目录 | .agents/skills/ 要另开「设置 → 技能与命令 → 导入设置」的开关；与 .trae/skills/ 重名时以后者为准 | 改的可能是没生效的那一份 |
| 手动点名 | 对话里直接说「用 trace-retrieval 处理这次改动」 | —— |
SKILL.md 的推荐结构是「描述 / 使用场景 / 指令 / 示例（可选）」。字段不用背：写一个技能，提一次相关任务看它有没有被加载，实测一次就知道了。
三家的技能文件都叫 SKILL.md，只有根目录不同。真正要留意的是「重名/兼容」这一行：只有 TraeCode 有 .agents/skills/ 这个第二个来源。
| 项 | Claude Code | Cursor | TraeCode |
|---|---|---|---|
| 项目位置 | .claude/skills/<名称>/SKILL.md | .cursor/skills/<名称>/SKILL.md | .trae/skills/<名称>/SKILL.md |
| 个人位置 | ~/.claude/skills/ | —— | ~/.trae-cn/skills |
| 长说明放哪 | 正文留步骤 | 同目录 reference.md | 同目录其他文件 |
| 触发依据 | description | description，第三人称写「做什么、在什么任务里用」 | description |
| 重名/兼容 | —— | —— | 规范里的 .agents/skills/ 要另开「设置 → 技能与命令 → 导入设置」的开关；与 .trae/skills/ 重名时用后者 |
正文只留五步和复查方式，把「为什么这么定」和判定细节放到同目录的参考文件里。
在 description 里写清「什么任务里用」，助手才可能自动加载它。
--- name: trace-retrieval description: 修改检索或基于检索结果的回答时使用。包括命中来源、无依据判定，以及只引用当前用户范围内的切片。 --- 1. 检索条件中的 scope_id 来自当前会话，不读取请求中的 scope_id。 2. 若使用向量库，点的 id 与数据库切片 id 相同，payload 带上 scope_id。 3. 候选结果全部低于检索配置里的相似度阈值时，视为没有命中；没有命中就返回无依据，本轮不调用对话模型。 4. 命中之后，回答只使用这些切片中的句子，并带上出处（文档名 + 切片 id）。 5. 用两个所属范围各看一次：当前范围能读到，其他范围读不到。 判定细节和复查清单见同目录 reference.md。
把长说明放在这里，正文只给出文件名，它就不会被全量加载。
# 检索与回答的边界 ## 为什么不用请求里的 scope_id 请求参数由客户端提供，可以被改写；会话里的 scope_id 由登录态决定。 ## 命中与无依据怎么分 相似度阈值写在项目的检索配置里，不在这个文件里改。 没有命中时回答「无依据」，不出现材料中没有的句子。 ## 复查清单 - 两个所属范围各看一次：当前范围读得到，其他范围读不到。 - 其他范围读不到的表现，与记录不存在无法从响应区分。 - payload 里带 scope_id，点的 id 与数据库切片 id 相同。 - 回答里的每个句子都能指回某个切片的出处。
技能不生效和规则一样，不会报错。下面四条按发生频率排列，照着对号。
| 现象 | 原因 | 修法 |
|---|---|---|
| 技能写好了，改检索时从没被自动加载 | description 只写了「一个处理检索的技能」，没说在什么任务里用 | 改成「修改检索或基于检索结果的回答时使用，包括命中来源与无依据判定」，并写清边界 |
| 技能改了一份，对话里用的还是旧的 | 同名技能同时存在于 .trae/skills/ 与 .agents/skills/，重名时以 .trae/skills/ 为准 | 只在 .trae/skills/ 放技能，删掉或停用另一份 |
| 把「家长端」这类产品功能写进了技能，助手总想在代码里实现它 | 把面向最终用户的产品能力和给编程助手的步骤混在一起 | 把产品能力写到需求和接口说明里；.trae/skills/ 里只放改代码时要遵守的步骤 |
| 技能正文写到三百行，每次加载都吃掉一大块上下文 | 正文会被全量加载，长说明没有外置 | 正文只留分步指令，把判定细节、示例、清单移到同目录的 reference.md |