写 Cursor 教程写到第三篇前面已经聊过 Cursor 的基础配置和 Rules 的玩法。今天这篇专门讲 Cursor Skills 的安装属于那种“文档里写得很简单实际折腾起来全是小坑”的模块。我先说结论如果你已经习惯用 Cursor 写代码但总觉得 Agent 不够“懂你”想要的工作流那 Skills 就是补齐这块短板的工具。它能让 Cursor 在特定任务里自动加载你预设的指令、模板、脚本和上下文比如代码审查、项目初始化、测试生成、文档规范一次配好后面反复用。这篇文章适合两类人一类是刚接触 Cursor 没多久想搞清楚 Skills 和其他配置到底有什么区别的新手另一类是已经写了大量 Rules但发现 Rules 管得住“行为”却管不住“流程”想知道怎么把重复工作变成可复用技能包的老手。下面我会从原理、安装方式、实操步骤、使用场景到最后的问题排查完整走一遍。1. Cursor Skills 到底是什么先别急着装1.1 Skills 和 Rules 的核心区别很多人一上来就在 Cursor 的设置里找“Skills 安装按钮”找了半天没找到然后跑来问为什么。这其实是因为 Skills 在 Cursor 里的形态并不是一个独立面板而是一套约定好的文件结构配合模型在后台加载。它和 Rules 最容易混淆我花点时间说清楚。Rules 的定位是“约束”。你告诉 Cursor 不许用某个库、代码必须写注释、变量命名要遵循什么风格这些属于静态规则任何时候对话都生效。它更像你给模型立下的规矩。而 Skills 的定位是“能力包”。它可以包含一套完整的操作流程例如拿到一个需求之后先分析技术栈再生成目录结构再写接口定义最后产出测试用例。这套流程涉及数十条指令、几个模板文件甚至要调用外部脚本。如果把这些都塞进 Rules上下文会被撑爆而且每次对话都加载成本太高。Skills 真正聪明的地方在于按需加载。Cursor 会读取每个 Skill 文件中的描述信息当你的对话内容与描述匹配时模型才把对应的完整指令拼接到上下文里。这就像一个工具箱平时放在墙角不占地方你说“我要拧螺丝”它才把螺丝刀递过来。1.2 Skills 的标准目录结构一个最基本的 Cursor Skill 长这样.cursor/ ├── skills/ │ ├── code-review/ │ │ └── SKILL.md │ ├── project-init/ │ │ ├── SKILL.md │ │ └── templates/ │ │ └── readme-template.md │ └── test-generator/ │ └── SKILL.md最关键的文件是每个技能目录下的SKILL.md。Cursor 会扫描.cursor/skills目录读取所有SKILL.md解析文件头部的 YAML 元信息然后根据元信息中的描述来决定何时加载整个文件。SKILL.md的头部信息一般长这样--- name: code-review description: 当用户要求审查代码、检查 bug、评估代码质量时使用此技能。 --- # 代码审查流程 ...name是技能的名字description是触发的关键。Cursor 模型会拿你的对话内容去和所有description做匹配匹配到了才会加载对应的技能。所以 description 写得好不好直接决定这个技能会被“想不起来用”。从安装角度来说你只需要做两件事把写好的SKILL.md放在正确目录下然后让 Cursor 重新加载。没有复杂的注册流程没有命令行工具也不需要在设置中心勾选什么。这个设计思路和 Claude Skills 很接近好处是跨项目、跨设备迁移极其方便坏处是有不少人把文件放错位置或者格式写错导致技能一直没生效。2. 安装前的准备版本、路径和技能来源2.1 先确认你的 Cursor 版本支持 SkillsCursor Skills 是相对较新的功能旧版本的客户端可能根本不识别.cursor/skills目录。如果你按教程操作后完全没有反应第一件事就是升级。我建议直接打开 Cursor 设置里的About或者Update页面检查是否有可用更新。实测下来当前主流的稳定版本都完整支持 Skills个别小版本可能只支持在项目级目录读取用户级目录的支持还不完善。最稳妥的办法是升级到最新版本然后用下面这个简单方法测试在任意项目里创建一个.cursor/skills/test/SKILL.md内容随意然后在对话中输入“列出当前可用的 skills”。如果模型能准确说出 test 这个技能说明版本支持路径也对了。2.2 项目级安装和用户级安装怎么选Skills 可以安装在两个层级用途完全不同。项目级安装就是把.cursor/skills放在当前项目的根目录下跟随项目仓库一起提交。这样一来同一个项目组的同事克隆代码后skills 自动生效不需要各自配置。适合放那些和项目强相关的技能比如这个项目专用的代码生成规范、数据库迁移模板、API 文档生成流程。好处是共享方便坏处是如果你换了别的项目这些技能就不会加载了。用户级安装则是把 skills 放到用户目录下Windows 一般在C:\Users\你的用户名\.cursor\skillsmacOS 在~/.cursor/skills。这个目录下的技能对所有项目全局生效适合放通用的工作流比如代码审查、通用测试生成、文档格式化这些和具体业务无关的技能。我的做法是通用技能放用户级项目私有技能放项目级。两者可以共存同名技能会优先使用项目级的。如果项目里没有同名技能就走用户级的。这个优先级规则很实用我一开始不知道结果项目里放了一个自定义的 code-review 技能却总是被用户级的同名技能覆盖排查了很久才找到原因。2.3 从哪找现成的 Skills 资源安装技能最省力的方式是直接用别人写好的。目前主流渠道有这么几个官方社区和 GitHub搜索cursor skills或awesome cursor skills能找到大量网友维护的技能仓库通常一个仓库包含几十个 skill 目录直接克隆下来放入.cursor/skills即可。第三方技能市场网站cursor.directory、cursorlist 这类站点收集了热门 Rules 和 Skills提供在线预览和一键下载。从 Claude 的技能体系迁移Claude Skills 的SKILL.md格式与 Cursor 的非常接近大部分可以直接复制过来用只要把 frontmatter 里的字段微调一下。需要注意的一点是下载现成技能时一定要先打开SKILL.md全文通读一遍。因为技能本质上就是“喂给模型的提示词”里面写得不好或者带着原作者个人偏好的约束直接影响最终效果。我有一次从网上下载了一个代码生成技能里面硬性规定所有 API 必须使用某个特定框架的写法和项目实际技术栈完全不搭结果 AI 生成的代码风格特别奇怪花了不少时间才排查出是这个技能在作怪。3. 手动安装 Skills 完整实操一步步建出自己的技能3.1 创建目录和第一个 SKILL.md先拿一个最简单的技能练手比如“git 提交信息生成器”。这个技能的目标是当用户要求生成 git commit message 时Cursor 自动加载一套预设的规范按照指定格式输出提交信息。第一步在项目根目录下创建目录结构mkdir -p .cursor/skills/git-commit注意目录名最好不要带空格和特殊字符全小写加连字符是最稳妥的命名方式。然后创建SKILL.mdtouch .cursor/skills/git-commit/SKILL.md第二步用任意编辑器打开这个文件写入以下内容--- name: git-commit description: 当用户要求生成 git 提交信息、commit message、提交说明时使用这个技能。也适用于用户粘贴了 git diff 并要求总结变更。 --- # Git 提交信息生成规范 遵循 Conventional Commits 规范生成提交信息。 ## 格式 type(scope): subject ## type 类型 - feat: 新功能 - fix: 修复 bug - docs: 文档变更 - style: 格式调整 - refactor: 重构 - test: 测试相关 - chore: 构建或辅助工具变更 ## 要求 1. subject 不超过 72 个字符 2. 使用祈使语气比如 fix login bug 而不是 fixed login bug 3. 如果用户粘贴了 diff需要根据变更内容推断 type 和 scope 4. 直接输出提交信息不要添加额外解释第三步重启 Cursor或者在对话窗口中输入“列出当前可用的 skills”看看模型能不能识别出git-commit这个技能。如果可以说明基础安装已经成功。这个流程看起来简单但你会在实际中遇到各种问题比如description写得太大白话模型在对话中无法建立关联或者 frontmatter 的格式少了一个冒号导致整个文件解析失败。这类问题的排查方法我放在后面专门的小节里写。3.2 frontmatter 里最关键的两个字段SKILL.md头部固定用 YAML 格式有三个字段比较常用name、description、allowed-tools。name是技能的唯一标识不要和其他技能重名命名尽量简洁。description是最重要的字段决定了技能什么时候被触发。Cursor 的机制是每次对话时系统把所有技能的name和description拿去做语义匹配匹配到之后才把完整的技能正文加载进上下文。所以 description 要写得具体一点把可能触发这个技能的对话场景都列出来。比如 git-commit 技能如果只写“生成提交信息”很多时候模型会直接忽略因为它觉得这不算一个需要特殊技能的任务。但如果写上“当用户粘贴了 git diff 并要求总结变更”触发概率会显著提升。allowed-tools是可选字段用来控制技能运行期间是否允许调用某些工具比如 bash 命令、文件读写等。如果你写了一个技能希望它只能读取文件不能修改文件可以在这里限制。不过普通使用场景下这个字段不写也行保持简单更重要。3.3 一个更复杂的示例代码审查技能学会了基础格式可以尝试写一个真正有使用价值的技能。我以代码审查技能为例演示如何把多步骤流程写进一个技能里。在.cursor/skills/code-review/SKILL.md写入--- name: code-review description: 当用户要求进行代码审查、找 bug、评估代码质量、检查安全性时使用。当用户说“帮我 review 代码”“这个代码有什么问题”时也要主动使用此技能。 --- # 代码审查流程 ## 第一步理解变更范围 如果用户没有指定具体文件先使用工具列出工作区中最近修改的文件确定审查范围。 ## 第二步逐文件审查 对每个文件检查以下维度 1. 逻辑正确性是否存在边界条件未处理、空指针、死循环等问题 2. 安全性是否存在注入风险、敏感信息硬编码、不安全的反序列化 3. 性能是否存在不必要的循环、重复查询、内存泄漏风险 4. 可维护性命名是否清晰、函数是否过长、是否存在重复代码 ## 第三步输出审查报告 按以下格式输出 - 问题列表按严重程度排序 - [严重/一般/建议] 描述问题标注文件路径和行号 - 优点列表值得保留的好设计 - 修改建议摘要 ## 约束 - 只审查用户要求的代码不要擅自修改代码 - 先输出报告再询问是否需要直接修改这个技能和简单的 git-commit 不同它包含了一个完整的流程定义模型加载后会按步骤执行。这里的关键是“步骤要写得足够清楚”不要让模型自己去猜。说得直白一点你不告诉它先看什么再看什么它就很容易只挑最简单的问题输出漏掉深层次的逻辑问题。3.4 如何让团队共享技能配置如果你是在团队环境工作项目级 skills 的最佳实践是随代码仓库一起提交。在.gitignore里确认没有忽略.cursor/skills目录然后把整个目录纳入版本控制。团队协作中有两个容易踩的坑。第一个坑是有人把 skills 安装到了用户级目录导致团队其他人拉代码后技能不生效。解决办法很简单所有需要共用的技能一律放项目级目录并且写在 README 里强调这一点。第二个坑是技能里面写了本机绝对路径比如某个技能需要读取/Users/xxx/scripts/build.py换一台电脑这个路径就不存在了。解决办法是技能内部尽量使用相对路径或者通过环境变量动态获取路径。4. 安装完成后的验证与调优技巧4.1 怎么验证技能真的被加载了安装完成不等于万事大吉。我发现很多人重启 Cursor 之后直接就开始干活也不确认技能是否生效一旦感觉 AI 行为不对又开始怀疑各种其他因素。这里分享一个快速的验证方法。打开 Cursor 的对话窗口输入列出你当前已经加载的所有 skills或者你现在知道哪些 skills。如果模型能准确列出你创建的技能名字就说明加载成功。如果模型说“不知道”先检查以下几点目录位置是否正确项目级必须放在项目根目录/.cursor/skills/技能名/SKILL.md注意技能名目录下是SKILL.md文件不是.md文件嵌套多层。文件内容格式是否正确前置的---前后不能有多余空格name和description字段必须有值。是否重启过 Cursor某些版本需要完全退出程序重新打开才能重新扫描 skills 目录。另外还有一个进阶验证方法。在一个新对话里不看任何代码直接用自然语言描述任务场景看模型会不会主动提到或使用某个技能。比如创建了一个api-doc-generator的技能然后输入“帮我把这个接口生成文档”观察模型是否按技能里定义的模板输出。如果它输出的是通用格式说明技能没触发需要检查 description 的匹配情况。4.2 调优触发效果description 是核心如果你的技能没有被自动触发八成是description写得不到位。这里有两类问题写得太宽和写得太窄。写得太宽是指 description 用了太多通用词汇比如“帮助用户完成任务”“提供帮助”这类描述和任何对话都可能匹配反而让模型无法判断。写得太窄是指只写了主场景没写变体比如“当用户要求生成测试时使用”但实际对话里用户可能说“给我补一下单元测试”“帮我写几个测试用例”“这个功能没测过怎么办”这些说法在语义上相近但措辞不同模型可能匹配不上。调优思路是穷举用户可能的表达方式把高频说法全部写进 description。比如description: 当用户要求编写单元测试、集成测试、测试用例或提到测试覆盖率、测试框架、jest、pytest、unittest 时使用此技能。参考用法是先把常见说法列出来再往外扩展一圈。同时注意description 不要写情绪化词汇比如“极其重要”“务必使用”模型并不关心这些只关心语义匹配。4.3 把 Rules 和 Skills 组合起来用安装 Skills 只是第一步真正好用的是把 Rules 和 Skills 组合成一套完整工作流。我的习惯是Rules 里面定义项目不可违背的硬性规范比如“禁止使用 any 类型”“所有函数必须写 JSDoc”Skills 里面定义复杂任务的执行流程比如“新页面开发从路由到组件到样式怎么一步步做”。举个例子如果项目里有一个frontend-page技能内容是生成新页面的完整流程那么可以在 Rules 里加一条“当开始开发新页面时必须调用 frontend-page 技能。” 这样既保证了流程被使用又能让 Skills 专注于具体执行细节两者不冲突。我这里还要特别提醒不要在一开始写太复杂的技能。一个技能只做一件事流程步骤控制在五步以内文本长度控制在能一眼看完的范围内。我看到很多新手上来就想做一个“一键完成全项目脚手架”的巨型技能几十个步骤塞进去一堆模板和脚本结果模型上下文加载得很吃力执行还经常漏步骤。踏踏实实从小的技能开始跑通了再慢慢扩。5. 常见问题与排查技巧实录5.1 技能不生效路径、格式和缓存三大坑我收集了这半年来自己碰到和帮别人解决的问题最集中的就是技能不生效。可以按以下顺序排查症状可能原因解决办法模型完全不知道技能存在目录或文件路径不对检查是否放在.cursor/skills/技能名/SKILL.md模型能列出技能但不调用description 写得不好匹配不到重写 description补充更多触发说法文件打开是乱码或解析失败YAML 格式错误检查 frontmatter确保name和description键值之间冒号后有空格改完技能后没生效Cursor 缓存了旧配置完全退出 Cursor 重新打开而不是刷新窗口其他人拉代码后技能失效技能安装到了用户级目录将技能迁移到项目级目录并提交这里重点说下 YAML 格式问题。很多人复制网上教程时粘贴过程中缩进被破坏或者引号被转义导致 frontmatter 解析失败。我建议写完SKILL.md后用一个在线 YAML 校验工具跑一遍确认没报错再放到.cursor/skills下。5.2 技能内容虽然加载了但回答质量没有提升这种情况很常见技能能被列出也能被触发但模型输出效果和没有技能时差不多。问题往往出在技能正文写得不够有约束力。比如一个代码生成技能里面写“生成高质量的代码”“注意代码规范”这种话太虚了模型不知道该干什么。真正的技能正文应该像操作手册一样写清楚先看什么文件用什么命名方式输出什么结构避免用什么语法。举个例子“生成接口代码”技能里应该写## 接口代码生成步骤 1. 先从 src/api/modules/ 下查找是否已有同模块文件 2. 新接口统一放在该模块文件末尾不要新建文件 3. 参数校验使用 zod错误信息使用中文 4. 返回类型定义放在 src/api/types/ 下并导出把这些细节补齐模型才知道你要什么。技能不是魔法它本质上还是提示词的组织形式写的越具体效果越好。5.3 技能升级和版本管理的习惯最后说下版本管理。Skills 虽然是配置文件但很多团队没有把它当代码管理导致升级和回滚特别混乱。我的建议是项目级 skills 目录一定要纳入版本控制每次改动提交时在 commit message 里标明技能变更点。如果你在使用过程中发现某个技能执行结果不稳定不要反复在对话里纠正而是直接把修正内容写进SKILL.md。这样可以积累出越来越准确的技能版本。再来一个小技巧给每个技能文件头部加一个version字段比如version: 1.2.0当模型加载时就知道自己用的是哪个版本。如果你调整了 description 或正文就把版本号往上抬一下。这种方式在小团队里足够用而且不需要引入额外工具。Cursor Skills 的功能扩展价值很大但它的能力上限取决于你往里面放的流程质量。我自己也是从最简单的 git-commit 技能开始一点一点积累到现在十几套技能。每次把一类重复工作沉淀成技能后续再遇到类似任务时效率提升都是肉眼可见的。这篇文章讲的是安装和基础用法希望你能从一个小技能入手把 Cursor 变成真正顺手的样子。