Cursor Skills 入门：从原理到实战，打造可复用的 AI 编程技能包

先开门见山。Cursor Skills 是 Cursor 这款 AI 编程编辑器里的一项核心能力：把“指令 + 示例 + 输出格式”打包成一个 markdown 文件，放到指定目录，当你在对话里提出相关需求时，AI 会自动加载这份技能说明，并按你定义的规范工作。我最初以为它只是 Rules 换了个名字，真正用起来才发现，它解决的是我一直很头疼的问题——每次开新项目都要重新交代技术栈、编码规范、输出格式，现在全装进技能包里，让 AI 自己读。

这篇指南适合三类人：刚接触 Cursor 的小白，想知道 Skills 怎么用、在哪配；已经在用 Cursor 但总感觉 AI 回答不够“懂你”的开发者；以及对 agent 指令工程感兴趣、想系统化提升 AI 协作效率的朋友。我会从原理讲到安装，从白嫖社区技能包到自己手写，最后附上我在实际使用中踩过的坑，尽量让你看完就能直接上手。

1. Cursor Skills 到底是干什么的

1.1 Skills 和 Rules 的本质区别

很多人容易把 Cursor 的 Skills 和 Rules 搞混，其实它们的加载机制完全不同。Rules 是“常驻上下文”，你写在项目规则文件里的每一条要求，AI 在每一轮对话里都会看到，相当于给 AI 立了一个一直在执行的“员工手册”。而 Skills 是“按需加载”，每个技能是一个独立文件夹，里面放一个 SKILL.md 文件，文件开头用 frontmatter 写清楚技能的名称和描述。AI 会先根据你当前提问的语义，去匹配所有技能的 description，匹配上了才把完整的 SKILL.md 注入上下文。

打个比方。Rules 就像公司墙上贴的规章制度，任何时候都得遵守；Skills 更像仓库里的一摞专项作业指导书，比如“客户投诉处理流程”，只有真的来了投诉工单，员工才会去翻那本手册。这个设计有个直接好处：省上下文。如果你的项目规则里塞了几十条规范，那每次对话都会白白消耗大量 token，AI 的注意力也会被稀释。用 Skills 之后，平时只保留少量核心规则，遇到专业任务才临时加载对应的操作手册，既精准又不浪费。

1.2 它解决的三类真实痛点

我在实际项目里总结下来，Cursor Skills 主要解决三件事。

第一，不用反复“教育” AI。以前写前端项目，每次让 AI 生成组件，我都要在对话里补一句“我们用的是 React + TypeScript，组件用 function 声明，样式用 CSS Modules，变量名统一小驼峰”。这听起来不麻烦，但一旦项目换人、换分支、隔了几周再看，这些约定早就丢了。把技术栈和规范写进一个前端开发技能后，AI 会自动按约定输出，人只需要审查结果。

第二，专业任务输出更稳定。比如让 AI 分析一份日志、写一段测试用例、给一段代码审查意见，如果没有技能约束，它每次的格式和深度都有随机性。技能里可以定义步骤、检查清单、输出模板，把“AI 的自由发挥”压缩到可控范围内。社区里流传比较广的“月老打分”技能就是这个思路：让 AI 给回复质量逐项打分，最后输出一张打分表，评价标准全部写在技能文件里。

第三，团队交付标准统一。你在项目根目录放一个 .cursor/skills，新同事 clone 仓库后重新打开 Cursor，他就会自动拥有团队定义的代码规范、提交信息格式、测试要求。这对多人协作项目来说，价值比个人使用高得多。

1.3 它的触发链路

理解触发链路是学会写技能的关键。一次完整调用分三步：用户在对话框输入需求；Cursor 把当前对话内容与每个技能 SKILL.md 里的 description 做语义匹配；一旦判定相关，就把整份技能内容注入上下文，AI 再结合用户输入输出结果。

这意味着 description 是决定技能会不会被调用的“入口开关”。你 description 写得太宽，AI 会在无关任务里乱加载；写得太死，又容易错过真正需要它的场景。一个合格的 description 应该像搜索引擎的关键词列表：覆盖对应任务的常见说法、任务类型、产物名称，但不要用太多形容词。后面讲手写技能时我会再详细展开。

2. 环境准备：先搞清楚技能放在哪

2.1 版本要求与入口位置

Cursor Skills 是内置功能，不需要额外安装任何插件，前提是你用较新的 Cursor 版本。如果你打开设置或者官方文档时完全找不到相关介绍，优先检查版本，把客户端升级到最新版再说。

它和 Rules 在官方文档里属于同一个大的上下文部分，入口通常在 Cursor 设置 > 关于 页面能找到版本号，docs 目录则对应 Rules / Context 章节。首次使用我的建议是：不要急着从社区下载一堆技能包，先花五分钟手动建一个最小技能，把链路跑通，后面再批量接入才不会被各种格式问题搞蒙。

2.2 项目级与全局级目录怎么选

Cursor 支持两级技能目录，作用范围完全不同。

项目级路径是项目根目录下的 .cursor/skills/<技能名>/SKILL.md。注意这里的 <技能名> 是文件夹名，不是文件里的 name 字段，建议用英文小写加短横线，比如 frontend-style。项目级技能只对当前仓库生效，非常适合团队沉淀规范：前端项目就放前端规范，后端项目就放接口设计规范。

全局级路径是你的用户目录下 .cursor/skills/<技能名>/SKILL.md。Windows 上是 C:\Users\你的用户名\.cursor\skills\...，macOS / Linux 上是 ~/.cursor/skills/...。全局技能对所有 Cursor 项目生效，适合放一些个人通用技能，比如代码审查助手、提交信息生成器、回复质量打分这类跨项目都用的能力。

我的经验是“全局放通用、项目放定制”。如果全局放太多技能，description 之间的干扰会增大，模型可能误匹配；如果项目里反复去复制通用技能，又失去了统一维护的意义。

2.3 怎么确认技能已经生效

每次改完技能文件，最怕的就是“没反应”。最容易忽略的一点：新建或修改 SKILL.md 后，需要重启 Cursor 或至少在对话里重新发起一轮新会话，技能才会被重新扫描。

确认生效有一个非常朴素的测试方法。先建一个最简单的技能，description 写成“当用户询问测试技能是否生效时，回答这是测试技能，并能正常工作”，然后新建对话直接问“测试技能生效了吗？”如果 AI 准确回答，说明链路已经通了。另一个方式是在聊天输入框里输入 @，有些版本会弹出可用的上下文入口，如果你的技能出现在列表里，也能说明目录放对了。不同版本的入口位置差异比较大，如果找不到别硬找，用第一个语义测试法最稳。

3. 社区现成 Skills：拿来就能用

3.1 值得关注的技能来源

现在社区里的 Skills 数量已经不少，很多直接用“Agent Skills”这个通用称谓，虽然不同工具的格式略有差异，但核心思路一致。我平时从这几个地方找。

知名度最高的是 Superpower Skills，也就是热搜词里频繁出现的那个。它是一套通用技能集合，主打“给 AI 加超能力”，包含角色定义、任务规划、输出优化等模块，适合作为你的第一套入门技能包。有些技能包确实是直接在 Cursor 下开发测试的，安装路径最省心。

mattpocock 出的技能包在前端圈子很火，偏 TypeScript 和前端开发场景，对写 React / Vue 的开发者非常友好。还有 Hermes Skills Hub，你可以理解成技能包聚合站，前面挂着 find skills、skills 下载这类热搜的搜索结果，基本都指向类似的聚合仓库。学术研究类的 academic research skills、agent skills 赋能人文社科混合研究方法论文写作这类话题，也有对应的技能包，我在 5.2 会单独讲怎么把它们落地到 Cursor 里。

需要提醒的是：很多热门技能包本来是给 Claude Code、OpenCode 或者 Codex 写的，它们和 Cursor Skills 文件结构相似，但不保证 100% 能直接跑。下载前先看目录里有没有 .cursor 部署说明，没有也没关系，手动改改路径就能用。

3.2 安装步骤：从下载到生效

以 Superpower Skills 为例，完整安装流程大致五步。

第一步，从官方仓库下载压缩包或直接 git clone 到本地。第二步，解压后查看文件夹内部结构，确认是不是 skills/<技能名>/SKILL.md 的形态。如果你看到的是 SKILL.md 散落在各级目录里，需要按 2.2 的路径规则重新整理。第三步，选一个作用范围。想全局生效就把整个技能文件夹复制到 ~/.cursor/skills/ 下；只想在某个项目里用，就复制到项目根的 .cursor/skills/ 下。第四步，重启 Cursor。第五步，新开对话做一次语义触发测试，比如“请使用 superpower 技能的模式帮我规划这个任务”，看 AI 是否有对应表现。

这里有个非常常见的坑：很多技能包文件结构是 skills/xxx/SKILL.md，如果你直接把最外层的 skills 文件夹整个复制到 .cursor/ 下面，最后会变成 .cursor/skills/skills/xxx/SKILL.md，多套了一层，技能就识别不出来。复制前一定要检查最终路径确实是 “存放目录 / 技能名 / SKILL.md” 这种结构。

3.3 免费额度用完的合法处理

“Cursor 免费次数用完”这个热搜词估计能排进所有 Cursor 相关搜索的前三名。我的建议是：先用官方提供的免费额度把技能调试好，不要在技能没跑通的时候浪费额度。这个额度是每月刷新一次的，用来体验主模型和高级模型基本够用。

如果你用的是免费版，高峰期会经常看到那句 “we're experiencing high demand right now. please upgrade to pro or tr...” 的提示。这句话的意思是官方服务进入高峰，免费用户在排队，不是你的账号出问题了。处理方式很简单：要么等几分钟再试，要么切到对话框右上角的快速小模型先顶着。如果日常工作重度依赖 Cursor，升级 Pro 或者自己配 API Key 是更稳的方案，至于“破解版”一类的东西，我建议碰都别碰，账号安全性、代码隐私、模型稳定性都得不到保障。

4. 手写第一个 Cursor Skills

4.1 SKILL.md 完整结构

一个标准技能只有两样东西：一个目录加一个文件。目录名就是技能标识，文件名必须是 SKILL.md，里面由 frontmatter 和正文组成。frontmatter 用三根短横线开头，里面写 name 和 description 两个字段，正文则用 Markdown 写任意指令内容。

我提供一个最小模板，你可以直接复制。

markdown复制---
name: code-review
description: 当用户要求审查代码、检查代码质量、找潜在缺陷时，使用该技能进行系统化代码审查，并按固定格式输出问题列表。
---

# 代码审查规范

你是一名资深代码审查工程师，请严格按照以下步骤执行：

1. 阅读用户提供的代码片段或文件路径。
2. 按 正确性、可维护性、性能、安全性 四个维度检查。
3. 使用中文输出，每个问题格式为：严重级别 | 问题描述 | 修改建议 | 所在行号。
4. 最后输出一个“整体评价”段落，给出结论性建议。

这里的 name 是机器标识，description 决定了技能的召回率，正文则是 AI 真正会执行的“操作手册”。我见过很多人把全部精力放在正文上，却随便写 description，结果技能做得很细但永远不会被触发，这是新手最容易犯的错误。

4.2 一个可复制的“回复质量打分”技能示例

如果你暂时没有特别复杂的业务需求，我建议从“回复打分”类技能开始练手，逻辑简单又立刻能看出效果。这个思路对应社区流传的月老打分技能：给 AI 的每一次回复做结构化评价，让输出质量可量化。

下面是一个完整可用的 SKILL.md，我直接放在全局目录里。

markdown复制---
name: response-scorer
description: 当用户要求对回复内容打分、评价回复质量、评估回答效果时，使用该技能对回复进行结构化评分。适合用户给出参考回复并要求评价的场景。
---

# 回复质量打分评估

对用户提供的回复内容进行系统化评分，评分维度固定为 4 项：

- 准确性：信息是否准确，有无事实性错误。
- 完整性：是否覆盖了用户核心问题。
- 可操作性：给出的建议或方案能否直接落地。
- 表达质量：逻辑是否清晰，结构是否合理，是否冗长。

输出格式：

| 维度 | 得分(1-10) | 理由 |
| ---- | --- | --- |
| 准确性 | 8 | 信息基本正确，但缺少部分边界说明 |
| 完整性 | 7 | 覆盖主问题，遗漏了成本分析 |
| 可操作性 | 6 | 有步骤但不够具体，缺少示例 |
| 表达质量 | 9 | 结构清晰，阅读顺畅 |

最终给出 1-2 句改进建议，并给出总分（四项平均分）。

如果用户没有提供参考回复，而是要求你主动生成一段内容，请先主动询问需要以什么身份、什么场景生成，再开始输出。

这个技能我第一次写完用了不到五分钟，但效果立竿见影。每次让 AI 给一段回答打分，它不会再给出“很好、不错、可以改进”这种空话，而是真给你一张表，哪里有问题、扣了几分、怎么改，全都清清楚楚。

4.3 写技能的三条原则

第一，description 要像“需求关键词清单”。想想你平时会用什么话术要求 AI 做这件事，把这些话术原文写进去。比如“帮我看看这段代码”虽然没明说“审查”，但也应该能被技能召回。

第二，正文是一份“SOP”，不是一份“背景说明”。别写“你在前端方面很有经验”这种废话，直接写“针对用户描述的需求，先输出技术方案，再列组件拆解，最后给代码示例”。AI 更擅长执行步骤明确的指令。

第三，能给模板就上模板。打分技能里我直接给出了表格模板和评分维度，AI 照着填就行。写技能跟写需求文档一个道理：你给的结构越清晰，拿到的结果越稳定。

5. 场景实操：三类热门 Skills 怎么写

5.1 前端开发场景的技能

前端开发 skills 是社区里需求最大的方向，因为前端项目约定非常多：技术栈、样式方案、命名规则、组件组织方式。如果你不把这些固化到技能里，AI 生成出来的代码很容易“能用但不符合项目规范”。

下面是一个面向 React 项目的前端开发辅助技能片段：

markdown复制---
name: react-page-builder
description: 当用户要求开发页面、编写组件、生成前端界面时，使用该技能。适合 React + TypeScript + CSS Modules 技术栈的项目。
---

# React 页面开发流程

1. 技术选型一律使用 React 18 + TypeScript，组件使用 function 声明，不写类组件。
2. 样式优先使用 CSS Modules，文件名与组件名保持一致，禁止使用全局 class 污染。
3. 组件命名使用大驼峰，变量与函数使用小驼峰，常量使用大写下划线。
4. 输出顺序：先给出组件职责说明，再给出 props/state 设计，最后贴完整代码块。
5. 所有组件必须标注必要的注释，关键逻辑必须解释“为什么这样写”。

这样一份技能不需要很长，但 AI 的输出会立刻“项目化”。写前端技能时我建议结合你实际项目，把当前项目用的 UI 库、状态管理方案、接口请求封装方式也写进去，越贴合实际越有用。

5.2 学术论文写作场景的技能

“agent skills 赋能人文社科混合研究方法论文写作”这类话题听起来高大上，其实落地到 Cursor 里就是一个把研究范式写成指令的技能。如果你是硕博生或者科研工作者，平时用 AI 辅助写论文，这类技能能大幅提升初稿质量。

学术写作技能的关键是把学术规范写进正文，比如：

markdown复制---
name: academic-paper-assistant
description: 当用户需要撰写学术论文、梳理文献综述、设计研究方法、润色学术语言时，使用该技能。适合人文社科领域的论文写作与修改。
---

# 学术论文写作辅助

1. 先询问论文类型与目标期刊/学位要求，再开始写作。
2. 结构遵循：引言-文献综述-研究设计-结果分析-讨论-结论。
3. 混合研究方法项目中，必须明确说明定量数据与定性数据的分析方式，以及二者的整合逻辑。
4. 文献引用统一使用指定格式，包含作者、年份、出版来源。
5. 语言要求规范学术化，避免口语表达，禁止主观评价类空洞表述。
6. 修改论文时，逐段输出问题分析，再给出修改后的完整段落。

我用这类技能帮朋友改过论文结构，最明显的变化是 AI 不再随意发挥研究结论，而是先问清楚研究设计和样本情况再动笔。对学术场景来说，这种“约束”恰恰是好事。

5.3 测试场景的技能

skills 在测试上的应用也是热门方向。搜索引擎里那个“vscode+codebuddy+playwright 测试skills在哪下载”的问题我见过不少，这里给你一个可以直接用的 Playwright 测试辅助技能思路，不用满世界找现成的。

markdown复制---
name: playwright-test-writer
description: 当用户要求编写端到端测试、生成 Playwright 测试用例、补充测试断言时，使用该技能。
---

# Playwright 测试用例编写规范

1. 先向用户确认要测试的页面路径和关键交互流程。
2. 测试用例必须遵循 arrange-act-assert 三段式结构。
3. 定位器优先使用 getByRole、getByText、getByLabel 等语义化方式，只有在无法构造时再使用 CSS 选择器。
4. 断言必须同时覆盖“正向流程”和“关键边界情况”，重要操作后补一条可访问性断言。
5. 输出格式：先列出测试场景列表，再逐条输出完整代码。

你把这个技能放进 .cursor/skills 后，再让 AI 给登录页面写测试，它就会按统一规范生成，而不是每次产出一堆风格不同的用例。测试技能特别适合团队落地，因为测试规范统一了，审查成本会低很多。

6. 常见问题与排查实录

6.1 技能没有生效怎么办

这是最频繁的售后问题。我整理了一份排查顺序，按以下步骤走基本能解决。

第一步，检查目录层级。确认最终路径是 技能目录/SKILL.md，没有多套一层文件夹。第二步，检查文件名。必须是 SKILL.md，全大写，不能是 Skill.md 或 skills.md。第三步，检查 frontmatter。开头和结尾的 --- 不能少，name 和 description 字段格式要正确，否则文件会被当成普通 markdown 忽略。第四步，重启 Cursor 并新开对话。第五步，用最直接的语言触发测试，比如“请你使用 xxx 技能处理这个任务”，不要用太含糊的表述。第六步，如果还不行，临时把技能里的内容直接贴进对话，确认指令本身没问题，再回头排查文件路径。

还有一个隐藏问题：如果你同时开了多个 Cursor 窗口，新窗口不一定立刻刷新技能文件。全部关掉重开是最保险的方式。

6.2 Cursor 中文设置与汉化的安全建议

这个问题在热搜里出现频率极高。先说结论：Cursor 官方没有中文界面设置项，想用中文最稳的办法是让 AI 用中文回答，而不是去折腾界面汉化。

让 AI 全程中文回复有两个层次。浅层做法是每次对话第一句加“请用中文回答”。深层做法是在全局 Rules 里写一句“无论用户使用什么语言，你的所有回答必须使用中文”，这样每个对话都会默认中文输出。

网上能找到各种第三方汉化补丁或汉化版安装包，我的建议非常明确：不要装。一方面它属于非官方修改，版本一更新就可能失效；另一方面这类工具通常需要注入或替换客户端文件，你根本无法确认它会不会额外收集数据。编辑器里全是工程源码，安全优先级必须最高。界面英文不习惯的问题，用上一两周就适应了，没必要冒这个风险。

6.3 Cursor 高峰期提示的处理

提示里那句 “we're experiencing high demand right now. please upgrade to pro or tr...” 在免费用户里非常常见。本质是免费额度被优先排在繁忙时段之后，高峰期请求量大时自然会排队。

处理优先级我的个人建议是：小幅任务切快速小模型，马上就能用；中等任务等五分钟再请求；大模型的任务尽量放在非高峰时段批量做。如果每天都要大量使用高级模型，升级 Pro 是效率最高的方案，省下来的排队时间远比订阅费值钱。

这里有个心理预期管理的问题：不要因为高峰期排队就怀疑技能配置有问题。技能本身不会影响官方的请求排队机制，两者没有因果关系。

6.4 Skills 跨平台格式差异

虽然 Cursor Skills、Claude 的 Agent Skills、OpenCode Skills、Codex Skills 在理念上同源，但字段和部署路径存在差异。我整理了一个简表：

所以你在 GitHub 上看到一个 Claude Code 的技能包，直接复制到 Cursor 里，有可能会因为多了不认识的字段导致渲染异常。稳妥做法是只保留 name 和 description 这两个核心字段，正文内容一般可以直接复用。跨平台前做一次字段清洗，会省掉很多排查时间。

最后分享一个小技巧。我会把自己的 ~/.cursor/skills 目录用 Git 管理起来，每次新增或修改技能都提交一次。这样做了三件事：一是技能被改坏了可以随时回滚；二是换电脑时直接 clone 就能恢复全部技能；三是可以把自己写的通用技能整理成仓库，分支分享给团队用。Cursor Skills 的价值不是一次性的，而是越攒越厚，你每沉淀一个技能，相当于把一次成功的 AI 协作经验固化成了可复用的资产。