编写与限定 Skill

每个 Skill 使用自己的目录和 SKILL.md。name 只用小写字母、数字、连字符，且必须与直接父目录名称一致；description 说明任务及触发条件。

最小定义

在 .cursor/skills/api-review/SKILL.md 中写入：

---
name: api-review
description: Review API boundary changes and their validation tests.
paths:
  - "src/api/**/*.ts"
disable-model-invocation: true
---

Read the changed API boundaries and their callers.
Check input validation, error responses, and regression coverage.
Report findings with file paths and supporting evidence.

paths 接受列表或逗号分隔字符串，限定匹配文件工作时才向 Agent 展示。旧 globs 仍作为兼容回退接受，新 Skill 使用 paths。disable-model-invocation:true 仅在显式 /api-review 调用时纳入上下文。

目录与资源

scripts 放可执行辅助程序，references 放按需阅读的说明，assets 放模板或静态资源。正文用相对 Skill 根目录的路径引用它们，保持主文件聚焦实际流程。

Skills 根目录可以按类别递归分组，身份仍来自直接包含 SKILL.md 的文件夹。仓库子目录中的 .cursor/skills 或 .agents/skills 也会发现，并自动限定到对应子树，无需额外 paths。

Custom Mode

从 / 菜单选 Skill，Enter 附加到一条消息，Option+Enter（macOS）或 Alt+Enter（Windows）保持为会话 Custom Mode。可用 icon 和 color 定义 badge；未识别值回退为默认闪电图标。

color 可用 default、green、cyan、blue、purple、magenta、orange、yellow、red、brand。模式只改变 Skill 保持在上下文中的方式，不赋予额外系统权限。

迁移旧指令

/migrate-to-skills 可把无 globs、非 alwaysApply 的动态规则转为普通 Skill，把用户/工作区 slash commands 转为 disable-model-invocation:true 的 Skill。alwaysApply:true、带明确 globs 的规则和不存于文件系统的 User Rules 不迁移。

迁移后检查 .cursor/skills 中的结果，特别确认触发范围和手动调用语义。团队分享与个人同步见Skill 同步。