Cursor Skills 实战指南：从配置到避坑，让 AI 编程更可控

这两年 AI 编程工具卷得厉害Cursor 从最初的“带补全的编辑器”一路进化到内置 Agent 模式已经不只是“写代码快一点”这么简单了。但很多人用 Agent 的时候其实有个困惑它确实能跑可总是差点意思——你要的代码风格它记不住、项目的特殊约定它不懂、测试用例写出来跟模板一样。问题的根源不是模型不够聪明而是你根本没用“Skill”去约束它。我玩了几个月 Cursor Skills把前端、测试用例、文档生成这些场景都封装成了技能包今天这篇指南就是想把整个上手过程、踩过的坑、还有一套可以直接抄的配置一次性讲清楚。这篇内容适合三类人刚装好 Cursor 想系统学会 Skills 的新手已经在用 Agent 模式但觉得输出不可控的中级玩家以及想在团队里统一 AI 协作规范的人。我不会只讲概念会直接给你能落地的目录结构、文件模板、触发策略和避坑清单你照着做马上能看到效果。1. 先搞明白Cursor Skills 到底是给 AI 加“岗位说明书”很多人第一次接触 Skills第一反应是“这不就是 Prompt 模板吗”我最初也这么想用了几天之后才意识到它的价值远不止“把 Prompt 存起来再调用”这么简单。1.1 它和普通 Prompt 的本质区别普通 Prompt 是你一次性告诉 AI“你要干什么”这个指令随着对话的进行会被稀释聊了几轮之后模型可能早忘了开头的要求。而 Skill 是一个常驻能力包它由目录结构、描述文件、规则文本组成平时不占用对话上下文只有当 AI 判定当前任务命中你的 Skill 描述时它才会加载对应指令。你可以把它理解为给 AI 招了个有明确岗位职责的员工入职时你已经把工作职责、红线、交付标准全写在岗位说明书里了不用每天重复嘱咐。这个机制解决了一个很实际的问题AI 的公司知识不可持续。你在一个项目里反复强调“我们前端要用 Vue3 组合式 API”“接口定义要带 ts 类型”“新增文件必须注册路由”如果每次都要靠对话记住你根本不敢开新会话。有了 Skills这些约束被固化在项目仓库里任何人、任何会话只要在这个项目里开着 CursorAI 就会自动遵守。1.2 一个 Skill 的目录结构与触发逻辑Cursor Skills 的规则其实很简单你创建一个文件夹里面放一个SKILL.md文件这个文件就是技能的“说明书”。my-skill/ └── SKILL.mdSKILL.md的开头是 YAML front matter里面至少要写清楚name和description。name是技能的名字description是触发引擎读取的关键——它描述这个技能适合做什么、由谁来触发。Agent 会结合你当前的任务上下文从所有已注册的 Skill 里挑匹配度最高的加载。这带来一个很反直觉的点决定一个 Skill 好不好用的不是正文写得多少而是 description 写得准不准。因为模型喂给 Agent 的输入里技能列表通常是一堆“名字 描述”的摘要如果描述写得含混、什么都像、什么都能干触发概率就会显著下降。1.3 Skills 支持在哪些层级注册Cursor 里 Skill 有两个存放位置作用和覆盖范围完全不同存放路径适用场景生效范围~/.cursor/skills个人通用技能你机器上所有项目项目根目录/.cursor/skills项目专属技能只对当前项目生效我的习惯是通用规范代码风格、提交信息模板、文档写法放全局业务相关数据模型约定、接口调用范式、测试数据生成规则放项目级。这样既保证了跨项目的个人一致性又不会让团队仓库里出现一堆和你个人习惯绑定的“私货”。2. 环境准备从安装到中文化再到规划 Skills 目录写 Skills 之前你至少要保证 Cursor 本身处于一个顺手的状态。这里我把安装、汉化、目录规划放在一起说每一步都是我自己踩过之后确认没问题的路径。2.1 版本检查不是所有旧版本都支持 SkillsSkills 是跟着 Agent 功能一起上线的早期版本对 SKILL.md 的识别能力很弱。如果你升级之后怎么搞都不生效先看一眼版本号。我的建议是直接用最新稳定版不要停留在旧版本等插件兼容Cursor 的迭代速度很快Skills 相关的 bug 修复都集中在近几个版本里。如果你公司网络环境比较特殊安装包下载慢那就等网络条件好的时候再装这属于环境问题和 Skill 本身无关。总之用新版就对了。2.2 界面中文化设置里的语言选项最干净很多国内用户热衷于找各种汉化包、补丁其实 Cursor 本身已经内置了界面语言切换不需要额外折腾。进入设置面板在 General 区域能找到语言Language选项切换为中文后重启编辑器即可。注意这里的“中文”指的是编辑器界面按钮、菜单、设置项的文案不影响你项目里的代码内容也不会影响 AI 回复的语言。AI 回复用什么语言取决于你在 Agent 的 Prompt 里或项目规则里怎么要求它跟界面语言完全是两回事。很多人的误区是“我界面设置成中文AI 是不是就只能说中文了”并不是它还默认跟着你提问的语言走你想让它稳定输出中文最好在 Skill 里显式声明。提示如果你在设置里找不到语言选项先确认版本已更新到最新。部分早期汉化包还会反向干扰插件启动卸载干净再切内置语言别两种方案同时用。2.3 全局 Skills 目录的初始化动作环境装好之后我建议先把全局 Skills 目录建好因为之后创建的任何 Skill 都要往这里放。命令行执行mkdir -p ~/.cursor/skills如果你所在的工作区套了一层自定的目录结构也可以把这行命令写进初始化脚本里。目录本身不存在不影响 Cursor 启动但你在界面上可能看不出来该把技能文件放哪儿。建好之后打开 Cursor 的命令面板搜索 “Skills”正常能看到当前已加载的技能列表一开始是空的这说明你的环境已经就绪。想验证得更彻底一点可以手动建一个临时 Skillmkdir ~/.cursor/skills/ping-check cat ~/.cursor/skills/ping-check/SKILL.md EOF --- name: ping-check description: 当用户要求做环境连通性检查或者输出ping技能测试时使用本技能。 --- 回复技能加载成功并列出当前目录。 EOF然后随便开个对话输入“ping技能测试”如果它能给出“技能加载成功”以及当前目录列表说明整套链路是通的可以正式开始写正式技能了。3. 动手写一个可用的 Skill以“前端开发 Skills”为例网上搜“前端开发 skills”能看到各种五花八门的技能包但说实话很多都写得太大、太泛效果反而不理想。我以自己常用的一个“Vue3 前端开发助手”为例把整个 Skill 的骨肉拆开给你看你直接改一改就能用在 React、小程序或者其他框架上。3.1 先写 SKILL.md 的“识别头”“识别头”就是 front matter 里的 name description。我初版写的是“处理所有前端相关任务”后来发现这个描述在技能列表里毫无辨识度任何写代码相关的请求都可能先触发它导致 AI 动不动加载一个并不合适的技能。改到第三版我才悟了description 要具体到你希望它被命中的场景而不是它的全部能力范围。合理的写法是--- name: vue3-frontend-dev description: 用于开发或修改 Vue3 项目中的页面与组件。 当用户要求新增页面、实现组件、修改模板结构、 调整样式布局、编写组合式 API 逻辑时触发。 不要用于处理 Node.js 后端服务问题。 ---注意我加了最后一句“不要用于处理 Node.js 后端服务问题”这种负向约束看起来很笨实际上很有用——它能帮 Agent 在相似任务里做排除减少误加载。3.2 正文里的几个核心模块目标、约束、流程、范例front matter 下面的 Markdown 正文就是技能的主体。以我做前端技能的思路正文一定包含四个模块目标一句话说清这个技能存在的意义让 Agent 知道自己该往哪个方向努力。约束列出绝对不能做的事比如不要修改公共样式、不要使用内联 style、不要破坏响应式布局。流程Agent 接到任务后的执行步骤比如先改逻辑再写样式最后自测。范例给一份符合要求的代码格式或输出模板让 Agent 有样学样。以 Vue3 技能为例我会在“约束”里写明“优先使用组合式 API避免选项式写法样式统一使用 scoped涉及状态管理时优先使用 Pinia”。在“流程”里写明“第一步梳理现有组件结构第二步确认接口字段第三步实现逻辑第四步补充样式第五步检查类型声明”。有了这些Agent 的输出就不再是“随缘发挥”而像一个熟悉你团队代码风格的老手。3.3 一个可以直接抄的完整 SKILL.md下面是我目前项目里在用的前端技能简化版覆盖面适合中小型项目你可以按需增删--- name: vue3-frontend-dev description: 用于 Vue3 TypeScript Vite 项目的页面开发与组件维护。 当用户要求新增页面、新增组件、修改模板、调整样式、 实现状态逻辑、补充接口调用时触发。 如果是后端服务、数据库脚本、CI 配置问题请勿使用本技能。 --- # Vue3 前端开发规范 ## 目标 在现有项目结构内产出符合团队风格、类型安全、可维护的 Vue3 代码。 ## 硬性约束 1. 使用 script setup 组合式 API禁止选项式 API 新代码。 2. 所有样式写在 style scoped 内禁止全局污染禁止无关键路径使用内联 style。 3. 组件目录统一src/components 下按模块分文件夹每个组件一个目录包含 .vue、types.ts、index.ts。 4. 接口定义必须显式写 interface 或 type禁止隐式 any。 5. 路由注册页面组件必须在 src/router 路由配置中显式注册禁止直接通过文件路径自动推断。 6. 状态管理使用 Pinia禁止在组件内保存跨页面共享的业务状态。 ## 执行流程 1. 阅读用户需求定位相关文件梳理依赖关系。 2. 如果涉及接口先确认请求和响应类型再决定如何封装。 3. 按“模板结构 - 逻辑 - 样式 - 类型检查”的顺序完成实现。 4. 完成代码后检查是否存在未使用的 import、遗留 console.log、明显坏味道。 5. 输出变更文件清单并说明每个文件的改动点。 ## 范例 组件结构示例 src/components/UserCard/ ├── index.ts ├── types.ts └── UserCard.vue这个SKILL.md写好之后放到项目根目录/.cursor/skills/vue3-frontend-dev/SKILL.md新建一个对话让 Agent 帮你写个卡片组件你就能看到它会主动往目录结构、类型断言、样式 scoped 这些方向靠。3.4 测试触发新建对话 指定任务很多教程会建议你“让 AI 列出当前可用的 skills”这确实是验证加载的最快方式。你可以在对话里直接问你现在加载了哪些 skills如果它列出vue3-frontend-dev说明触发成功。我再补充一个更严格的测试方法偏离触发词场景。比如你故意问一个后端任务然后要求它不要用前端技能如果它能正确区分、不加载 Vue3 技能说明 description 的边界写得到位。我见过大量技能“过度触发”的问题都是在这一步暴露出来的。4. Skills 进阶玩法把外部能力通过 MCP 接进来Skills 解决的问题是“让 AI 知道项目规则”但要让它真正变成能操作外部系统的“手”还得配合MCPModel Context Protocol模型上下文协议。热搜词里很多人都在搜“skills 如何调用 mcp 工具”这确实是进阶的关键点。4.1 为什么要给 Skill 绑 MCP默认情况下Cursor 的 Agent 只能读取文件、写代码、跑命令。可真实场景里你可能希望它根据项目里的接口文档自动生成测试用例读取数据库表结构生成对应的模型文件操作浏览器的调试协议抓取页面上实际渲染的 DOM 状态把生成的变更记录自动同步到项目管理工具。这些事情无法通过文件读写完成必须借助外部工具而 MCP 就是那个“外部工具的标准化插座”。Skill 负责描述“什么时候做、按什么规范做”MCP 负责提供“能不能做、具体怎么操作”的能力两者是互补关系。4.2 Cursor 里配置 MCP 的两种方式在 Cursor 的 MCP 设置面板里你可以添加两种类型的服务本地命令型比如npx启动的本地服务适合连数据库、读本地浏览器远程 HTTP 型适合连你自己部署的后端服务或团队内部的工具平台。添加完成之后再新建对话Agent 就会在合适时机主动选择调用对应的 MCP Tool。这里有个关键经验一个 Skill 不需要主动宣告“我要用某某 MCP”只要相关 MCP 已经配置好Agent 在解决实际问题时会自动判断是否调用。你硬要在 SKILL.md 里指定工具名称反而可能在工具没配置时报错。4.3 实战案例用“测试用例生成 Skill”调度数据库 MCP我做过一个“测试用例生成”的 Skill负责把项目里的接口定义转成测试数据。它在 SKILL.md 里约定好用例模板、字段命名规则、边界值覆盖策略。真正执行的时候Agent 会读取接口定义文件调用数据库 MCP 查询表结构和已有数据分布按 Skill 里的模板生成一批贴近真实分布的测试用例把用例写入指定目录。如果没有 MCPAgent 只能靠猜字段范围和可选值生成的用例跟玩具一样没什么执行价值。一旦接上数据库 MCP它能从information_schema里拿枚举值、默认值、允许空的关键信息用例质量就完全不一样了。关于“MCP 会不会很复杂”我的回答是如果你只是想在本地接一个数据库或文件系统按官方文档跑一条npx命令五分钟能搞定难点主要在你自己对业务的理解而不是协议本身。5. 踩坑实录我把 Skills 跑崩又救回来的全过程有段时间我的 Cursor 经常不加载新的 Skill有的能触发有的不能我一度以为是功能有 bug后来一条一条排查才发现大多数是我自己的问题。下面这些坑我打包票你也会碰到。5.1 文件名大小写和路径放错导致的静默失败Cursor 加载 Skill 的规则是文件夹名和 SKILL.md 名称大小写相关的。我遇到过把SKILL.md写成skill.md、把文件夹放到.cursor根目录而不是.cursor/skills下面的情况结果就是界面里完全看不到这个技能。排查方法很简单看一眼命令面板里的 Skills 列表如果没有就是路径或命名不对。还有个小概率是缓存问题不说了直接重启一次 Cursor 最干净。5.2 front matter 格式错误整个技能被跳过YAML 的缩进要求很严格我一开始写 description 时用 Tab 缩进结果解析失败技能静默跳过连报错都没有。这类错误在调试上没有日志提示非常恶心。教训就是写完 SKILL.md 之后先用 YAML 解析工具校验一遍别偷懒。5.3 触发词写太宽技能互相打架账号里有多个 Skill 之后我就发现了“触发竞争”的问题。比如我有一个“接口文档生成”技能又有一个“测试代码生成”技能结果我让 AI “生成接口测试代码”两个技能都可能命中。AI 选哪个就看 description 谁描述得更贴近上下文但结果不一定是你想要的。解法不是改正文而是调整 description 的互斥边界。我给“接口文档生成”加了一句“当重点是书写接口说明文档时使用”给“测试代码生成”加了一句“当重点是构造测试数据和断言逻辑时使用”。这样描述更精确误触发概率明显下降。5.4 技能正文过长反而压制了 Agent 的发挥我早期写技能恨不能把团队所有规范都写进去一个 SKILL.md 文件写五六百行。结果 Agent 每次全量加载这些内容既占 token又容易“信息过载”该注意的关键约束反而被淹没了。后来我把一个巨型技能拆成三个小技能每个最多几十行只保留最高频的几条规则。这个改动让我体感上的输出质量提升了一大截。注意Skills 的正文不是越多越好写清楚“最高频的约束 流程 范例”就够了。过于琐碎的内容会让模型无所适从甚至开始自我矛盾。5.5 版本更新后出现行为变化Cursor 小版本更新有时会调整 Skill 的加载策略。常见的变化是之前能自动触发的新版本里 description 匹配更严格。我的对策是升级后第一件事用“你现在加载了哪些 skills”做一次回归测试重点检查自己最常用的三五个技能是否能正常命中。如果发现技能不加载了先别急着重写旧版本和新版本的差异往往是缓存或索引问题重启几次、删掉.cursor目录下索引缓存重建多数能恢复。6. 实际生产配置我当前使用的 Skill 清单与后续扩展方向前面把原理、操作、避坑都讲完了最后分享一下我现在真正在生产环境里跑着的这套配置。这不是“标准答案”但你可以当做一个起点来改造。6.1 我工作区里的 Skill 清单我当前常驻的 Skill 有六个分三层Skill 名称层级职责关键描述词repo-rules项目级仓库通用约束分支、提交格式、文件命名提交代码、分支管理、文件命名规范vue3-frontend-dev项目级Vue3 页面和组件开发新增页面、实现组件、样式调整api-doc-writer全局接口文档撰写和更新书写接口说明、整理字段含义test-case-gen全局测试用例生成边界值、正常路径、异常路径debug-guide全局配合运行时错误排查报错分析、堆栈信息、定位问题release-notes全局生成版本更新日志变更记录、版本号、更新日志这套配置比较均衡项目级负责业务全局级负责工程习惯。我换新项目时只需要复制repo-rules和vue3-frontend-dev这两份到对方仓库再微调里头的命名约定就能快速让 AI 对齐团队风格。6.2 团队协作时Skills 如何进入版本库一个人玩 Skill 很爽但在团队里统一 AI 行为才是更大的价值。我的做法是把.cursor/skills放进 Git 仓库让团队所有成员自动拉到同一套规则。这里有个提醒不要在里面写个人偏好比如“代码注释用中文”这种如果团队本身用英文注释会引发一阵混乱。团队级 Skill 建议规定每个 Skill 必须写明适用场景、触发边界、负责人。一旦规则过时负责人直接改仓库提交大家 pull 到最新就能生效。这比动不动在群里贴“大家以后让 AI 这样写”的通知靠谱多了。6.3 与 Claude Code Skills 的兼容性经验很多人搜“claude code skills 官方文档”其实是在对比 Cursor 和 Claude Code 两套 Skills 的写法。我的经验是同一份 SKILL.md在两个工具里基本可以混用因为它们都采用 SKILL.md front matter 的机制。唯一的差异是触发策略和 description 长度限制。团队里如果有同事用 Claude Code 而领导让统一 Skill你可以先验证一遍跨工具加载是否正常再决定要不要维护两套模板。现在我的工作习惯是所有项目的通用约束都沉淀在 Skill 文件里任何成员打开项目就等于“带了一个懂项目规则的程序员”。它减少了大量重复沟通成本也让 AI 的输出更稳定、更可控。如果你只用 Cursor 但还没碰过 Skills建议今天就把最简单的那个ping-check建出来试过一次之后你应该就回不去了。