同一套步骤每次按同一顺序做、写进仓库说明又太长，就是写成技能的信号。它和命令的区别只在一个字段：加了 disable-model-invocation: true 就变成命令。
改这类代码时，助手在没提示的情况下会自己读出这份步骤吗？读出来以后，五步是不是按同一顺序做完？
答「不会」或「顺序每次不同」，先改 description 的措辞，再改正文的编号。这两处是技能被选中和被执行的全部依据。
技能是「一个目录一份 SKILL.md」，目录名就是技能名。正文超过一屏时，把背景拆到同目录的另一个文件里，正文只留步骤——助手默认读的是 SKILL.md，不会自动读旁边的文件。
仓库根目录/ ├── .cursor/skills/ │ ├── trace-retrieval/ │ │ ├── SKILL.md # 前置元数据 + 五步正文（本页实物） │ │ └── reference.md # 超过一屏的背景放这里 │ └── check-scope/ │ └── SKILL.md # 这是命令，带 disable-model-invocation ├── .claude/skills/trace-retrieval/SKILL.md └── .trae/skills/trace-retrieval/SKILL.md
三处目录的 SKILL.md 正文逐字照抄，前置元数据按工具换。新增一个技能就是建一个同名目录，删除就是删掉整个目录——留下空目录或只删文件，助手下次仍会试图读它。
提交前跑两条自检：ls -d .cursor/skills/*/ .claude/skills/*/ .trae/skills/*/，三处应当出现同名目录；grep -rn "name:" .cursor/skills/*/SKILL.md，每条 name 应当与所在目录逐字相同。别给没用到的工具建空目录。
场景：对助手说「把检索改成按更新时间过滤」，没说怎么改、按什么顺序核对，也没贴文档。
trace-retrieval 的 description 命中「修改检索」类任务，助手自己把 SKILL.md 读进上下文，按固定顺序做完：scope_id 取自当前会话、向量点 id 与切片 id 相同、没有命中就返回无依据、引用能回到那一条切片、准备两个所属范围的数据。
这三者都装「一段步骤」，最容易混用。判据是谁在什么时候决定用它。下表列出最容易被误做成技能的东西，以及它真正的落点。
| 容易被做成技能的 | 做成什么 | 怎么判 |
|---|---|---|
| 只在改某一类文件时成立的一条约束 | 规则 | 这条约束只在改这类文件时才用得到吗？是 → 规则；改文档时它不该在上下文里 |
人输入 /名称 才执行的清单 | 命令 | 需不需要人记得去用、由人拍板？是 → 命令 |
| 一次性的项目背景、历史决策 | docs/ | 它不是步骤，改一次就不再用 → 放文档 |
| 产品功能的文案、评分、讲解流程 | 业务代码与验收文档 | 它面向用户，不是开发流程里的步骤 → 放业务目录 |
| 需要只读或独立上下文的核对 | 子智能体 | 要不要独立上下文，或更小的工具范围？是 → 子智能体 |
description 是唯一的触发依据，要写清两件事：做什么、在什么任务里用。漏了后半句，助手判断不出时机，技能放在仓库里也等于没有。六个落点的完整对照见规则页的总表。
技能文件在三家工具里都叫 SKILL.md，差别只在放在哪个根目录；TraeCode 另外还有一个兼容来源。照下面这张表找到自己用的那一行，再进对应的落地页看完整写法。
| 工具 | 技能目录 | 落地页 |
|---|---|---|
| Cursor | .cursor/skills/名称/SKILL.md | Cursor 技能落地页 |
| TraeCode | .trae/skills/名称/SKILL.md | TraeCode 技能落地页 |
| Claude Code | .claude/skills/名称/SKILL.md | Claude Code 技能落地页 |