项目命令放在 .trae/commands/，一个 Markdown 文件一条命令，文件名就是调用名。个人命令放在 ~/.trae-cn/commands，小组共用的步骤不要只放在自己电脑上。项目命令最多嵌套 3 层目录；前置元数据写 name 和 description，第二个 --- 下面是真正要执行的步骤；对话里输入 /，从 Commands 里选。
有三种情况会打开这一页：有一段步骤全组每周都要走一遍，想固化下来 → 抄「示例：两条可直接抄的命令」，改掉文件名就能用；输入 / 却找不到自己建的命令 → 看「没生效时的现象与修法」的前两条；拿不准该建成命令还是技能 → 看「命令在三个工具里的差别」的「新写法」那一行，再对照技能。
写错最多的是两件事，先记住。一是把还没固定下来的流程也建成命令，每次调用结果都不一样——命令的价值在于同一条步骤被重复执行，步骤没定就不要建。二是把命令当技能用，指望它自动触发：命令靠输入 / 调用，自动触发的是技能。
同一条命令连着调用两次，两次给出的结论是不是同一套？
答「不是」，正文里写的还是「检查一下」这类判不出对错的话。把它改成能判断动作的句子，再调一次。
一条命令就是一个 Markdown 文件，没有别的注册步骤。放对位置、起对名字，它才会出现在对话的 / 列表里。
| 项 | TraeCode 的写法 | 写错的后果 |
|---|---|---|
| 项目位置 | .trae/commands/<名称>.md | 放到别的目录，/ 列表里看不到 |
| 个人位置 | ~/.trae-cn/commands | 只在自己电脑上，换一个同学就没了 |
| 调用名 | 就是文件名，如 check-scope.md → /check-scope | 文件名带空格或大写，调用名对不上 |
| 目录深度 | 项目命令最多嵌套 3 层目录 | 放到第 4 层就不被识别 |
| 前置元数据 | name 和 description，第二个 --- 之前 | 缺了能在列表里显示的说明，别人不知道它是干什么的 |
| 正文 | 第二个 --- 之后，写真正要执行的多步动作 | 写成「检查一下」这类没有动作的句子，每次产出都不一样 |
| 怎么调用 | 对话输入 /，从 Commands 里选择 | —— |
字段不用背：建一条命令，在 / 列表里看得到、跑得出结果，就是对的。命令不会自动触发，这一点和技能相反：命令固定「怎么做」，由人决定「现在做」。
转工具时先看「新写法」这一行：另两家已经把命令并入技能，用 disable-model-invocation: true 表示「只许人调用」；TraeCode 仍是独立的 .trae/commands/ 目录。
| 项 | Claude Code | Cursor | TraeCode |
|---|---|---|---|
| 新写法 | 写成技能 .claude/skills/<名称>/SKILL.md 并加 disable-model-invocation: true | 写成技能 .cursor/skills/<名称>/SKILL.md 并加 disable-model-invocation: true | .trae/commands/<名称>.md，文件名就是调用名 |
| 旧写法 | .claude/commands/*.md 仍作为同名命令加载；两边同名时技能优先 | .cursor/commands/*.md 仍能加载 | —— |
| 个人位置 | —— | —— | ~/.trae-cn/commands |
| 目录深度 | —— | —— | 项目命令最多嵌套 3 层目录 |
| 调用方式 | 输入 / | 输入 / | 输入 /，从 Commands 里选择 |
| 名称约束 | —— | name 与目录名相同，只用小写字母、数字和连字符 | 文件名即名称 |
第一条在动手前划范围，第二条在合并前过一遍清单。两条都把动作写成能判断对错的句子，抄走之后把项目名和目录换成自己的。
输入 /check-scope 调用。它先看 README 里写明做什么、不做什么。
--- name: check-scope description: 判断这次改动是否越出当前阶段已经写明的范围 --- 只做 README 里写明的角色和能力，数据按登录用户的所属范围隔离。 当前阶段有哪些能力，以 README 为准。产品里给最终用户使用的功能，不是仓库里的技能文件。 不做：家长端、多校区运营、学科交易市场。 先列出这次会改的目录。 再逐条说明：哪条在上面的范围内，哪条该停。 不要为了「顺便」加上范围内没有的角色或存储。
输入 /pre-merge 调用。合并前跑一次，把结论写进合并请求说明里。
--- name: pre-merge description: 合并前把本次改动对照仓库约定过一遍 --- 逐条回答，每条都要给出证据（文件路径或行号）： 1. 这次改动的文件清单，逐行列出。 2. 有没有动 .env、密钥或网关地址？ 3. 新增的查询是否写成 `WHERE scope_id = ?`，并且绑定的是会话里的 scope_id？ 4. 有没有为让检查通过而删断言、跳过用例或上调阈值？ 5. 提交信息是否符合「类型: 一句话」？ 只报告结论与证据，不要顺手改代码。
命令的问题都出在「位置、名字、内容」三处，对照下面四条即可。
| 现象 | 原因 | 修法 |
|---|---|---|
输入 /check-scope 没有这条命令 | 文件名带了空格、大写字母，或没放在 .trae/commands/ | 用小写字母和连字符命名，路径改成 .trae/commands/check-scope.md，重开对话再看 / 列表 |
| 同一条命令调用两次，结论完全不一样 | 正文写的是「检查一下范围」这类没有可判断动作的句子 | 改成可判断的动作，如「先列出这次会改的目录，再逐条说明在不在范围内」 |
| 想让助手在自己觉得合适时自动用这条命令，它从不自动触发 | 命令靠输入 / 调用，本身不会自动触发 | 把它改成 .trae/skills/<名称>/SKILL.md 的技能，由 description 决定何时加载。见技能 |
放在子目录里的命令在 / 列表里找不到 | 嵌套超过了 3 层 | 把命令收回到 3 层以内，如 .trae/commands/frontend/lint-fix.md |