Cursor 怎么加载 Claude Skills 路径与作用域

Cursor 自动扫描四类 skills 目录，任务匹配时加载 SKILL.md；与 Anthropic 授权无关，是开放格式互通。

Cursor 怎么加载 Claude Skills 路径与作用域

想在 Cursor 里复用 Claude Code 写好的 skill，不必逐条复制进对话框。cursor 怎么加载 claude skills，官方机制是启动后扫描固定目录，任务与 description 匹配时再读完整 SKILL.md，平时只保留名字和描述占上下文。

作者：CodePass 技术编辑

Cursor 会扫哪些目录

Cursor Skills 帮助页 列出四类本地路径，优先级按「离当前工作区越近越优先」理解：

项目内：  .agents/skills/    .cursor/skills/
用户级：  ~/.agents/skills/  ~/.cursor/skills/

此外 Cursor 声明兼容 Claude Code 与 Codex 的习惯路径：项目内 .claude/skills/、.codex/skills/，以及用户目录 ~/.claude/skills/、~/.codex/skills/。把现有 Claude skill 目录原样放进上述任一路径，通常无需改文件名。Towards AI 2026-08-10 的解读强调：这是 SKILL.md 开放格式的互通，不是把 Claude Code 订阅「搬运」进 Cursor。

monorepo 里子包各自带 skills/ 时，作用域跟路径走：在 apps/web/ 打开工作区，只会加载该子树下的 skill，不会把兄弟包的 skill 全塞进同一会话。多包仓库建议把共享 skill 提到仓库根 .cursor/skills/，业务专用 skill 留在子目录。嵌套越深，description 越要写清包名或路径前缀，否则 agent 可能在错误的子项目里触发发布流程。

匹配时加载什么、平时占多少上下文

每个 skill 目录入口是 SKILL.md，frontmatter 里至少要有 name 和 description。Cursor 先把各 skill 的名字与描述做成清单常驻；只有当用户意图或 agent 判断与某条描述对齐，才把该 skill 全文注入上下文。

这和 Skills 和 MCP 有什么区别 里讲的「按需披露正文」一致：未触发的 skill 只花一行描述，触发了才付正文 token。清单里 description 过长会被截断，写 skill 时把触发条件写进描述前两句，比把步骤全堆在 frontmatter 更省窗口。

加载成功后在 Agent 侧栏或 skill 列表能看到条目；手动触发可用斜杠命令（与 Cursor 版本有关，以 Customize 页实际展示为准）。若同一 skill 在项目与用户目录各有一份，一般项目内版本优先；重名时以作用域更近的为准，避免在全局目录复制与项目冲突的 name。

可复制检查：在仓库根建 .cursor/skills/ping/SKILL.md，frontmatter 写 name: ping-test 与一句含「测试 skill 加载」的 description，Reload 后在 Agent 输入「按 ping-test skill 执行」看是否注入正文。未本机逐路径压测，步骤来自官方帮助页逻辑推导。

和 Anthropic 授权是两回事

Cursor 能读 .claude/skills/ 里的 SKILL.md，说的是文件格式互通，不是 Anthropic 给你开了额外席位，也不是 Claude Code 订阅自动延伸到 Cursor。

SKILL.md 规范来自 Agent Skills 开放标准（agentskills.io），任何兼容客户端都可以按同一 schema 发现与加载。你在 Claude Code 里写的发布流程 skill，拷到 .cursor/skills/release-check/SKILL.md，Cursor 按开放格式解析；权限、模型、工具仍走 Cursor 自己的策略。Anthropic 是否参与 Agent Plugins 治理席是另一话题，与「Cursor 能不能读 SKILL.md」无关。

若团队同时维护 Claude Code 与 Cursor，可以共用一份 skill 源码，通过 git submodule 或符号链接挂到两个目录，减少双份维护。打包成可分发目录时，也可对照 Cursor 支持 agent plugins 把 skills 与 MCP 收进 plugin.json，再被 Customize 页统一安装。

新建与迁移：2.4 起的斜杠命令

Cursor 2.4 及之后提供两个内置命令减轻手工建目录：

  • /create-skill：对话式生成 skill 目录与 SKILL.md 草稿
  • /migrate-to-skills：把 .cursor/rules 或冗长规则片段转成 skill 形态

入口在 Agent 输入框敲斜杠即可；生成后文件仍落在上述扫描路径，可进版本库 review。若你更习惯图形界面，Cursor Customize 页 也能浏览已加载的 skills 与插件，和斜杠命令改的是同一套磁盘文件。

迁移时注意：rules 里的事实性约束（语言版本、目录结构）仍适合留 rules；重复粘贴的多步流程更适合 skill。混用时别让同一流程在 rules 和 skill 里各写一遍，否则匹配时会双倍占上下文。/create-skill 生成草稿后务必人工删敏感信息；/migrate-to-skills 批量转换前先用 git 分支，方便 diff 掉误迁移的 secrets 或过期路径。

Cursor 2.4 之前没有这两条斜杠命令，只能手工建目录；升级 IDE 后旧 rules 仍生效，skills 是增量能力。团队文档里可同时链接 openai agent plugins 开放标准，说明 skills 将来如何打进 portable 插件包，与单目录加载是上下游关系。

装上了却不触发时的排查顺序

  1. 确认 SKILL.md 在 recognized 路径下，且 frontmatter 含合法 name、description。

  2. 看当前打开的是否为 monorepo 子目录；子目录 scope 下看不到上级的 skill 是预期行为。

  3. 描述是否写清「何时使用」；过于笼统的描述模型不会匹配。

  4. Reload Window 或重启 Cursor，排除缓存未刷新（社区反馈偶发，非官方保证）。

  5. 对比 Cursor 项目 rules 不生效 的同类问题：工作区根目录选错是最常见人为原因。

  6. frontmatter 缺 name 或 YAML 缩进错误会导致整文件被跳过；用 IDE 看 SKILL.md 是否被当成普通 Markdown 而非有效 skill。

团队场景：把 skills 进 CI 做 schema lint（agentskills.io 有字段说明），比靠肉眼 review 更稳。OpenAI Codex 路径 .codex/skills/ 与 Claude 路径可并存，Cursor 会按帮助页列出的顺序扫描，但同一流程不要在三个目录各维护一份，否则清单膨胀、描述截断更快。

参考资料