余山郡

深浅模式

在 Cursor 中配置与使用 Skill ​

本文说明 Skill 文件应放在哪里（全局 / 项目）、如何在 Cursor 里维护，以及 在 Agent 对话中如何用起来。Skill 是什么、与 Rules/MCP 的区别、以及 SKILL.md 写法，见：Skill 说明。需要 按场景挑选可安装的 Skill 名称与方向 时，见：Skill 推荐与清单。

全局配置 Skill（个人、所有项目可用） ​

个人（全局）Skill 放在用户主目录下，对所有仓库可见：

类型路径（macOS / Linux）路径（Windows 示意）
个人 Skill~/.cursor/skills/<skill-name>/C:\Users\<你的用户名>\.cursor\skills\<skill-name>\

把写好的 SKILL.md（及可选的 reference.md、scripts/ 等）放进对应子文件夹即可，无需在每个项目里复制一份。

请勿 把自编 Skill 放进 ~/.cursor/skills-cursor/ 当作「官方推荐安装位」。该目录多用于 Cursor 内置/随版本分发 的资源，手动往里塞自定义内容 可能被更新覆盖或与内置冲突。个人与团队编写的 Skill 请使用下文官方列出的目录（~/.cursor/skills、.cursor/skills 等）。若网上教程仍写「必须放 skills-cursor」，请与 Cursor 文档 · Agent Skills 对照后再决定。

在「当前项目」中配置 Skill ​

项目级 Skill 放在仓库根目录（与 .git 同级）下：

text
your-repo/
└── .cursor/
    └── skills/
        └── my-team-skill/
            └── SKILL.md

这样 克隆该仓库的同事 也会带上同一套 Skill，适合固化团队流程。

在 Cursor 里怎么改 ​

  1. 在左侧文件树中展开项目根目录，进入 .cursor/skills/（没有则新建 skills 文件夹，再建以技能名命名的子文件夹）。
  2. 在子文件夹中新建或编辑 SKILL.md，保存即可。
  3. 全局技能则在资源管理器中打开用户目录下的 .cursor/skills/，同样按「技能名文件夹 + SKILL.md」维护。

保存后，Agent 会按当前 Cursor 版本的规则发现这些技能（具体行为以官方文档为准）。

如何在 Cursor 中使用 Skill ​

  1. 自然语言点名
    在 Agent 对话里直接说：「按 xxx-skill 里的流程做」「先读 Skill：my-skill-name」等，让模型明确去加载对应目录下的说明。

  2. 依赖 description 自动匹配
    当你描述的任务与某个 Skill 的 description 高度重合时，Agent 可能自动选用；因此 描述里要写准关键词（例如 PDF、PostgreSQL、PR 评审、Conventional Commits 等）。写法详见 Skill 说明 中的 frontmatter 一节。

  3. 与 Rules 搭配
    项目里用 Rules 写「永远遵守的底线」，用 Skill 写「某类任务的 SOP」，减少单条消息长度，又保证一致性。

  4. 版本管理与评审
    项目 Skill 建议随代码走 Git：改动走 PR，和改代码一样评审，避免「口头规范」漂移。

希望 Skill「自动带上」：推荐顺序（对照官方） ​

先对齐事实（见 Agent Skills）：Cursor 会 发现 SKILL.md，默认由 Agent 按相关性 决定是否纳入上下文；没有「写两行 YAML 就保证用户每发一条消息必加载」的官方通用开关。
若你的目标是 尽量别每次手动 @ / /，又希望 稳定 让某套流程被读到，应把「强制」放在 Rules（系统级常驻提示），而不是赌 Skill 的自动命中。

推荐顺序（从稳到险、从省事到费事）：

  1. Project Rules 或 User Rules + alwaysApply: true + 正文用 @ 指向 SKILL.md（规则层保证「会话开头就带着去读谁」）。
  2. 根目录 .cursorrules 写同样语义（是否仍被当前版本、是否覆盖 Ask/Plan 等模式，以本机为准；更稳请迁到 .cursor/rules）。
  3. 只改 SKILL.md：用默认自动命中，或 disable-model-invocation: true 改为仅 /技能名 显式调用。
  4. 不改配置：每次在 Agent 里 / 选技能，或 @ 某个 SKILL.md。

1. 首选：.cursor/rules（或 User Rules）+ alwaysApply: true ​

在 .cursor/rules/*.mdc（或 .md）里建一条规则，frontmatter 与正文示例：

markdown
---
alwaysApply: true
---

使用 Agent 时，须先阅读并遵循：

@.cursor/skills/<技能文件夹名>/SKILL.md

（Skill 若在全局目录，可改为 `@` 能解析到的路径或绝对路径。）

再按该文件中的步骤、清单与约束执行；正文不必重复粘贴整份 Skill。
  • 项目级：文件在 .cursor/rules/，随 Git 共享。
  • 用户级：在 Cursor Settings → Rules 写同等内容，跨仓库生效；适用范围以 Rules 文档 · User Rules / FAQ 为准（例如 FAQ 写明 User Rules 不作用于 Inline Edit Ctrl+K）。

这是与 Rules 行为表 中 alwaysApply: true = 每次聊天都带上 一致的做法，也是「自动带上」里最 可预期、可审计 的一种。

2. 次选：仓库根 .cursorrules（纯文本） ​

仍有人把整段自然语言放在 .cursorrules，例如「每次提问必须启用某某 Skill……」。可以当作 快速试验，但要注意：

  • 官方当前主推 .cursor/rules + frontmatter；.cursorrules 的读取范围与模式覆盖 无统一长期承诺，以版本为准。
  • 纯文本是 提示词约束，不是编译器保证；若要长期团队使用，建议 迁到第一节的规则文件。
  • 至少写上 @.../SKILL.md 路径，避免只写技能中文名而模型从未读文件。

3. 只靠 SKILL.md 能做什么（不能做什么） ​

官方 frontmatter 主要包括：name、description、paths、disable-model-invocation、metadata（见 Skills 文档）。

你的意图建议配置
相关任务时让 Agent 自己考虑 是否带上默认（不设 disable-model-invocation: true），把 description 写具体
只有在我输入 /技能名 时才带上disable-model-invocation: true，在 Agent 聊天用 / 搜索并选择

不要依赖网帖常见的 auto_apply、trigger: always 等字段——不在官方字段表内，写了也可能被完全忽略；「每条必读」请回到 第 1 节的 Rules。

4. 手动一键（零配置、最可控） ​

  • Agent 输入框输入 /，搜技能名（官方说明的显式调用方式）。
  • 或用 @ 引用对应 SKILL.md，与 Rules 里 @ 引用同一机制。

适合大体积 Skill、或只在少数会话里启用。

5. 设置 / Agent 界面里的 Skills ​

部分版本在 Settings → Rules 一带展示已发现的 Skills；是否另有 Agent 顶栏 Skills、Auto-apply 等，以你当前 Cursor 界面为准。
文档层面：Skill 仍以 发现 + 相关性 为主逻辑；强制每条先读仍优先用 第 1 节 Rules + alwaysApply，少依赖未写进文档的 UI 开关。

6. 常见误传（与官方不一致时以官方为准） ​

误传对照官方时的理解
自编 Skill 必须放进 ~/.cursor/skills-cursor官方发现路径为 .cursor/skills/、~/.cursor/skills/、.agents/skills/ 等（文档表格）；自编内容放 skills-cursor 易被更新覆盖，不建议。
SKILL.md 里写 auto_apply / trigger 即可全局强制非官方字段；要稳定「先读后做」用 Rules alwaysApply + @SKILL.md。
某固定版本号以下「完全不能用 Skills」以 Cursor 发布说明为准，升级后核对 Skills 与 Rules。

小结 ​

场景做法
个人、跨项目~/.cursor/skills/<skill-name>/SKILL.md
仅本仓库、可共享.cursor/skills/<skill-name>/SKILL.md
使用方式对话中显式指定 + 写好 description 便于自动匹配
希望每条对话都强制参考某 Skill首推：.cursor/rules（或 User Rules）+ alwaysApply: true + @.../SKILL.md 指针；次选：根目录 .cursorrules 自然语言（效果依版本）；勿信：非官方的 auto_apply/trigger YAML、把自编 Skill 塞进 skills-cursor

Cursor 具体菜单名称与选项可能随版本更新；若与本文不一致，以 Cursor 官方文档 为准。

Released under the MIT License.

Copyright © 2025-present China Carlos