8.0
热点
AI SCORE
编程提效2026-08-18 21:19
Cursor Skills完全指南：格式规范与跨Agent迁移实测
dev.to · AI#Cursor#AI编程#Agent Skills
Editor brief · 编辑速览
详解Cursor读取Skills的目录结构、SKILL.md格式字段、跨Claude/Codex的兼容性与差异，以及团队共享时的版本策略。
Publisher: Skills Board. Published August 15, 2026. Last checked August 15, 2026.
Cursor skills 是存放指令的文件夹，当任务与某个文件夹的用途匹配时，Cursor 的 agent 会加载其中的内容。每个 skill 包含一个 SKILL.md 文件，以及任务所需的脚本、参考资料和资源文件（可选）。Cursor 自身的文档将 Agent Skills 描述为一个开放的扩展 AI 智能体标准，而非 Cursor 的功能——这是你编写 skill 之前需要了解的最有用的一点。
这一点很重要，因为你编写的文件就是其他 agent 读取的文件。该格式最初由 Anthropic 开发并作为开放标准发布，规范位于 agentskills.io，Cursor 与 Claude Code、Codex 以及众多其他产品一同出现在其客户端展示区。
本文涵盖：Cursor 实际读取的内容、它扫描的所有目录（包括 Claude 和 Codex 的目录）、它记录的前端字段和未记录的字段、如何在几分钟内添加一个 skill、同一文件在多个 agent 之间迁移时哪些内容会保留、团队在多人依赖同一个 skill 时需要做哪些决定，以及 Cursor 未文档化的部分。
Cursor skill 是一个包含 SKILL.md 文件的目录：YAML frontmatter 中包含 name 和 description，随后是 Markdown 指令。Cursor 启动时从 skill 目录中发现 skills，将其呈现给 agent，agent 根据上下文决定每个 skill 的相关性。
Cursor 将 skills 描述为可移植、可版本控制、可执行和渐进式加载：任何支持该标准的 agent 读取相同的文件，skill 就是一个可以提交的文件，它可以打包脚本、模板和参考资料，agent 使用自身工具运行或读取这些内容，这些资源按需加载而非全部塞入上下文。
有两种方式触发一个 skill。Agent 根据你的请求与 skill 描述的匹配程度隐式选择，这就是为什么描述必须说明 skill 的用途和使用场景，要用实际输入的措辞。你也可以在 Agent chat 中输入正斜杠并搜索名称来显式调用。
Cursor 还内置了一些 skills，与你添加的 skills 一同出现，其中包括用于编写新 skill 的 /create-skill、用于代码审查的 /review 和 /review-security，以及用于将已有规则和斜杠命令迁移到 skills 的 /migrate-to-skills。完整列表参见 Cursor 的 skills 文档。
Cursor 从四个自身目录加载 skills，其中两个位于项目级别，两个位于用户级别，随后为了兼容性还会扫描其他四个属于其他 agent 的目录。这最后一部分是来自 Claude Code 或 Codex 的用户意想不到的细节，但这确实是有文档记载的，而非坊间传说。
分类文件夹是开放的。Cursor 递归遍历 skills 根目录，拾取它找到的任何 SKILL.md，因此你可以在 shipping/、debugging/ 或 workflow/ 子文件夹下对 skills 进行分组。分类文件夹仅用于组织：身份标识来自直接包含 SKILL.md 的文件夹。
嵌套的项目目录会自动限定作用域。仓库内任意位置的 .cursor/skills/ 或 .agents/skills/ 文件夹会被拾取，Cursor 文档说明其 skills 只在 agent 处理该目录内文件时才会出现。在 monorepo 中，apps/web/.cursor/skills/ 中的 skill 仅适用于 apps/web，而仓库级别的文件夹适用于全局，无需前端字段。
你可以查看实际发现了什么。打开侧边栏中的 Customize，转到 Skills，来自插件或项目的 skills 会与 Agent Decides 区中的规则一起出现，可按用户、工作区或团队作用域筛选。
两个字段是必填的，其余均为可选。其中两个可选字段是 Cursor 对标准的自定义扩展，这也是 Cursor skill 在其他 agent 中行为可能不同的原因。
frontmatter 下方的正文是纯 Markdown，格式不限，一旦 agent 激活该 skill，所有内容都会被读取。规范建议将 SKILL.md 保持在 500 行以内，并将详细参考资料移至单独的文件中，仅在指令要求时加载。六个规范字段中有三个——license、compatibility 和 allowed-tools——完全不在 Cursor 的表格中，下文的限制部分会涉及。
Skills 不是规则，Cursor 明确了两者的区别。规则内容包含在模型上下文的起始部分；2.4 发布说明将 skills 定位为更适合动态上下文发现和过程性操作指南。内置的 /migrate-to-skills 将符合条件的动态规则转换为 skills，并将斜杠命令转换为 disable-model-invocation 设为 true 的 skills。
关于 OpenAI 端的逐字段说明，包括 Codex 扫描的目录及其单独的 agents/openai.yaml 元数据文件，参见 Codex skills: what they are and how to use them。
文件本身会迁移，而在 Cursor 的情况下，比其他任何地方都更多的配置会迁移，因为三者中只有 Cursor 文档化了会读取另外两个产品的目录。不会迁移的是每个产品在标准之外添加的所有内容。
只要在规范范围内，文件就可以流转。它定义了六个 frontmatter 字段：name 和 description 为必填，license、compatibility、metadata 和 allowed-tools 为可选——最后一个标记为实验性，支持情况因产品而异。任何超出该集合的内容都是产品扩展，因此依赖 paths 或 disable-model-invocation 的 skill 在不支持这些字段的 agent 中会失去相应行为。
Cursor 读取其他目录省去了一道麻烦，但不是消除了差异。为 Claude Code 配置的仓库在 Cursor 中无需第二个文件夹即可工作，但反过来的情况没有文档记载：Claude Code 和 Codex 都没有文档化会读取 .cursor/skills。对于三者都读取的同一个文件夹，.agents/skills 是 Cursor 和 Codex 都有文档记录的路径，而 Claude Code 仍需要 .claude/skills 或指向它的符号链接。
可移植性关乎格式，而非结果。同样的指令可以在三个产品中加载，但仍产生不同的工作成果，因为工具、沙盒、模型和周围指令都不同。在告诉队友某个 skill 可以在某个 agent 中使用之前，先在每位队友实际运行的 agent 中测试一下。
关于同标准的 Claude 端说明，包括完整的前端字段表和 skills 运行的环境，参见 Claude skills: what they are and how to use them。
有三种有文档记录的方式可以最终获得 Cursor 可用的 skill：自己编写文件夹、安装打包了 skills 的插件，或请内置 skill 为你起草一个。手动方式值得先学会，因为其他两种方式在磁盘上产生的结果是一样的。
如果仓库中所有人都需要某个 skill，将其放在项目根目录的 .cursor/skills/ 或 .agents/skills/ 中。如果队友也使用 Codex，选择 .agents/skills/，因为两个产品都有文档记录该路径。属于你个人的 skill 放在 ~/.cursor/skills/ 或 ~/.agents/skills/。Monorepo 中单个包的 skill 放在该包自身的 skills 目录中，Cursor 会自动为其限定作用域。
创建一个以 skill 命名的目录，并在其中放入 SKILL.md 文件。前端字段需要 name 和 description。name 必须与父目录名称匹配，只能使用小写字母、数字和连字符，规范限制最多 64 个字符，不允许开头、结尾或连续出现连字符。
Cursor 说明 agent 使用 description 来判断相关性，所以这个字段决定了 skill 是否会被触发。用实际输入的措辞说明它的用途和使用场景。听起来像目录条目的描述不会触发 skill。
正文是纯 Markdown，格式不限。将 SKILL.md 保持在 500 行以内，将长篇参考资料移至 references/、可执行代码移至 scripts/、模板移至 assets/。这些内容仅在指令要求时加载——这正是该格式的要点所在。
当 skill 涉及 React 组件、Python 风格或某个包的规范时，添加 paths glob，Cursor 仅在 agent 处理匹配文件时才会呈现该 skill。放置在嵌套项目 skills 目录中的 skill 无需任何前端字段即可获得该作用域。
在 Agent 聊天中输入正斜杠并搜索技能名称。显式调用可以确认 Cursor 已找到该文件夹并解析了 frontmatter。之后就交给 agent，看看你的描述是否真的会在你预期的请求上触发。进入 Customize，再进入 Skills，可以查看 Cursor 发现了什么。
或者完全跳过编写环节
内置的 /create-skill 会起草一个包含结构和 SKILL.md 的技能，/migrate-to-skills 则可以将已有的符合条件的动态规则和斜杠命令转换过来。从 Cursor Marketplace 或团队 Marketplace 安装插件，会将其打包的技能一并引入，以 skills/ 目录结构组织，每个技能对应一个 SKILL.md。
---
name: release-notes
description: 根据已合并的 Pull Request 起草发布说明。当用户要求发布说明、更新日志或已上线内容的摘要时使用。
---
## 步骤
1. 列出上次 tag 之后已合并的 Pull Request。
2. 按新功能、修复和内部变更分组。
3. 用通俗易懂的语言，为每个面向用户的变更写一行。
4. 除非内部重构改变了行为，否则不写入。
## 输出
一个以版本号和日期为标题的 Markdown 区块。
两个问题藏在同一个词后面。分发是把文件弄到每个队友的机器上。推荐则是知道哪个技能适用于哪个任务、以及为什么选那个。Cursor 对第一个问题有不错的答案。第二个问题根本不是 Cursor 的问题。
如果团队使用的每个技能都放在大家都在工作的仓库里，答案很简单：把它们提交到项目根目录的 .cursor/skills/ 或 .agents/skills/，Cursor 会自动拾取，无需额外工具。对于单一仓库的团队，这是最佳配置，没有任何共享库能做得更好。这里不应该有任何内容让你放弃这种做法。
但当技能来自别人的仓库、技能在多个仓库中都有用、或者队友运行的是不同的 Agent 时，这种做法就不够用了。Cursor 对前两个问题的答案是插件：它支持 Agent Plugins 标准以及自己的 Cursor Plugin 格式，并在 Teams 和 Enterprise 计划中提供团队 Marketplace，每个插件有独立的安装模式。这解决了打包和推广问题，但无法覆盖在 Cursor 之外使用其他工具的队友，因为 Claude Code 或 Codex 安装的并不是 Cursor Plugin。
推荐层通常无处安放。团队最终选了哪个技能、为什么选它，结果往往散落在聊天记录、书签或某一个人的记忆里。Skills Board 是这一层的共享库：团队推荐的那套较小的技能集合，放在一个可搜索的地方，每个条目都可见原始来源，不强制假设队友使用哪种 Agent。
打开原始来源：每个已保存的技能都记录了它来自哪个仓库和路径，队友可以在使用前先阅读 SKILL.md。
复制安装命令：适用于那些命令匹配其配置的队友。这只是多种选择之一，不是唯一路径。
下载 ZIP：保存时源站点的最新文件，适合宁愿自己放置文件夹的人，可以放到 .cursor/skills 或 Cursor 扫描的其他任何位置。
通过 MCP 连接 Cursor：在项目的 .cursor/mcp.json 或全局的 ~/.cursor/mcp.json 中添加 Skills Board MCP 端点，就能在所有地方使用，然后在 Cursor 的 MCP 设置中登录。Agent 可以搜索同一个团队库并获取安装命令，还能根据授予的权限保存技能和组织集合。登录在浏览器中完成，无需复制 API key。
已保存的技能是团队推荐，不是安全审查、不是审批、也不是兼容性认证。
Skills Board 跟随保存的源中可用的最新版本。它不会固定或保留历史版本。
MCP 连接无法在 Cursor 内部安装或运行技能，也无法编辑或删除已保存的团队技能。
它不是技能目录的替代品。文件仍然需要通过某种方式落到 Cursor 扫描的目录中，具体路径由每个队友自行选择。
托管产品永久免费，代码采用 MIT 许可，你可以阅读或自行托管全部内容。
关于操作层面的版本——一个规范来源加每种 Agent 经测试的安装路径——请参阅 Manage skills across Claude Code, Codex, and Cursor。
有些被期望有文档的内容实际上没有。以下是我们阅读 Cursor 现有文档时发现的空白，原文照录，不做猜测。
Cursor 列出了四个自己的技能目录和四个兼容性目录，但没有说明当同一技能名称出现在其中两个目录时会发生什么。Claude Code 文档记录了优先级顺序，OpenAI 文档说明 Codex 不会合并同名技能并可能同时显示两者。Cursor 对两者都未做说明，所以将重复名称视为未测试状态。
Agent Skills 规范将 license、compatibility、metadata 和 allowed-tools 定义为可选，并将 allowed-tools 标记为实验性，各实现对其支持程度不一。Cursor 的 frontmatter 表格只记录了 metadata，没有记录 license、compatibility 或 allowed-tools。它们在 Cursor 中的行为未经验证。
Cursor 命名了 .codex/skills/ 和 ~/.codex/skills/ 作为 Codex 兼容性目录。OpenAI 文档记录了从工作目录到仓库根目录的 .agents/skills、 $HOME/.agents/skills 和 /etc/codex/skills。两者都记录的重叠部分是 .agents/skills，所以对于一个同时服务 Cursor 和 Codex 的文件夹来说，这是更安全的选择。
Cursor 描述了渐进式加载，但没有公布已发现技能列表可能占用多少上下文，也没有说明当安装了许多技能时会发生什么。OpenAI 为 Codex 发布了一个数字。Cursor 没有，所以你能保持安装多少个技能是一个需要观察而非查阅的事实。
Cursor 的技能页面说你可以从 GitHub 导入技能，通过 Customize、Rules、Add Rule、Remote Rule (Github)。其规则页面描述了相同的流程：扫描仓库中的 .mdc 文件并导入到 .cursor/rules/imported/。SKILL.md 文件夹如何进入 skills 目录没有明说，所以在依赖之前先在 Customize 然后 Skills 中检查结果。
2.4 发布说明称 Cursor 在编辑器和 CLI 中支持 Agent Skills。当前的 Cloud Agents 文档没有提及技能，Agent 概览页面也没有。是否每个 Cursor 界面都会加载提交到仓库的技能没有说明，所以不要假设它。
什么是 Cursor 技能？
Cursor 技能是一个包含 SKILL.md 文件的文件夹，SKILL.md 带有 YAML frontmatter 和 Markdown 指令。frontmatter 需要 name 和 description。Cursor 在启动时从其技能目录中发现技能，并将它们呈现给 agent，由 agent 判断每个技能何时相关。你也可以在 Agent 聊天中输入正斜杠来调用某个技能。
技能在 Cursor 中放在哪里？
Cursor 从 .cursor/skills/ 和 .agents/skills/ 加载项目级技能，从 ~/.cursor/skills/ 和 ~/.agents/skills/ 加载用户级技能。为兼容起见，它还会从 .claude/skills/、.codex/skills/、~/.claude/skills/ 和 ~/.codex/skills/ 加载。仓库内嵌套的技能目录也会被拾取，作用域限定在其所属文件范围内。
Cursor 会读取 Claude 技能吗？
会。Cursor 文档记录了为兼容而从 Claude 和 Codex 目录加载技能：.claude/skills/、.codex/skills/、~/.claude/skills/ 和 ~/.codex/skills/。格式是相同的 Agent Skills 标准，所以已经为 Claude Code 配置好的仓库不需要第二份拷贝。特定于某一产品的 frontmatter 字段仍然不会迁移过去。
Cursor 技能和 Cursor 规则有什么区别？
规则是声明式的且始终开启：其内容在开始时进入模型上下文。技能按需加载，当 agent 判断描述相关时或你调用它时才会加载。Cursor 的 2.4 发布说明将技能定位为更适合动态上下文发现和程序性操作指南，并提供了 /migrate-to-skills 来转换符合条件的规则和斜杠命令。
如何在 Cursor 中安装技能？
三条有文档的路径。在 Cursor 扫描的目录中自己创建文件夹并放入 SKILL.md。从 Cursor Marketplace 或团队 Marketplace 安装打包了技能的插件。或者通过 Customize、Rules、Add Rule、Remote Rule (Github) 从 GitHub 仓库导入。在 Customize 然后 Skills 下检查结果。
能让 Cursor 不自动使用某个技能吗？
可以。在 frontmatter 中将 disable-model-invocation 设为 true，该 skill 就会表现得像一个传统的斜杠命令：只有当你输入其名称（前面带斜杠）时才会进入上下文。若想缩小而非完全禁用自动使用的范围，可以设置一个 paths glob，这样该 skill 只在匹配的文件上出现。
团队如何共享 Cursor skills？
对于单个仓库，将其提交到 .cursor/skills/ 或 .agents/skills/，Cursor 就会自动加载。若要在多个仓库之间共享，Cursor 通过插件和 Teams 及 Enterprise 计划中的团队市场来分发 skills。但这两种方式都无法解决「团队推荐哪个 skill 以及为什么推荐」的问题，尤其是在队友使用不同智能体的情况下——这正是像 Skills Board 这样的共享库所填补的层面。
Cursor: Agent Skills：skill 目录结构，包含 Claude 和 Codex 兼容性路径、嵌套和分类文件夹、frontmatter 表格、可选目录、内置 skills、Customize 视图、GitHub 导入路径，以及 /migrate-to-skills。
Cursor 2.4: Subagents、Skills 和 Image Generation：Cursor 编辑器和 CLI 中引入 Agent Skills 的版本，以及将 skills 与常驻规则进行对比的框架。
Cursor: Plugins：插件所包含的内容、Agent Plugins 标准与 Cursor Plugins 并列、团队市场及其安装模式，以及从 Customize 管理 skills。
Cursor: Plugins reference：插件内部的 skills 格式：在 skills/ 下每个 skill 一个目录，各自拥有独立的 SKILL.md。
Cursor: Rules：规则内容如何进入模型上下文，以及扫描仓库中 .mdc 文件的远程规则（Github）导入流程。
Cursor: Customize Cursor：Customize 页面，在用户、团队或工作区级别管理 skills、插件和 MCP 服务器。
Agent Skills specification：六个 frontmatter 字段及其约束、可选的 scripts、references 和 assets 目录，以及渐进式披露和文件大小建议。
Agent Skills: overview and client showcase：作为一种开放标准的格式（最初由 Anthropic 开发），以及展示页面中列出支持该格式的产品（包括 Cursor）。
Claude Code: skills documentation：Claude Code 从哪里加载 skills、优先级顺序，以及嵌套项目 skills。
OpenAI: build skills for ChatGPT and Codex：Codex 扫描的目录、其调用语法、agents/openai.yaml 文件，以及初始 skill 列表的发布预算。
AGENTS.md vs SKILL.md：两种格式，两种不同职责
Claude skills: what they are and how to use them
Codex skills: what they are and how to use them
Manage skills across Claude Code, Codex, and Cursor
How to share AI agent skills with your team
A shared MCP skill library for teams
最初发表于 skillsboard.sh/cursor-skills。
如需进一步操作，你可以考虑屏蔽此用户和/或举报滥用行为