Cursor 这个编辑器最近两年在 AI 编程圈子里几乎是绕不开的名字。很多人已经习惯了用它补全代码、跨文件重构、甚至直接对话生成整个功能模块。但 Skill 这个功能说实话真正自己动手写过的人不多。大部分人要么在用官方预设要么从社区里抄现成的真正自己从零写一个贴合自己工作流的 Skill体验完全不一样。这个教程就是写给那些已经不满足于“用 Cursor”的人。你不需要成为 prompt 工程师也不需要精通某种特定语言只要清楚自己平时写代码的痛点就能把重复性的流程、规则、惯用套路固化成一个 Skill让 Cursor 在接到指令时按你的方式来执行而不是每次都靠临场发挥。我最初接触 Skill 也是因为一个很具体的场景项目里有一类数据迁移脚本流程固定、步骤繁琐每次对话都得反复交代上下文、约束条件、命名规范很浪费时间。后来花了半天时间把一个完整的流程封装成 Skill之后只需要一句话Cursor 就能按部就班地把整个迁移脚本生成好包括注释风格、错误处理、日志输出全都符合项目规范。那之后我才真正感受到Skill 的核心不是“教 Cursor 一个新技能”而是“把你自己做事的标准固化成交互流程”。下面我把整套流程拆开来讲从设计思路到具体文件结构再到调试技巧尽量做到手把手级别。1. 整体设计与思路拆解1.1 初次上手Skill 到底是什么Skill 在 Cursor 里本质上是一个包含指令、上下文和可选脚本的“规则包”。它和单纯的 Custom Instructions 不同——后者更像是写在系统提示词里的全局规则而 Skill 是一种按需加载的模块化指令集。你可以把 Skill 理解成给 Cursor 装的一个“专用插件”需要的时候通过特定描述触发不需要的时候它完全不干扰其他对话。这样说可能有点抽象拿我们平时干活来类比。你带过一个新人没有你跟他讲“这个项目我们一般这么写接口、这么处理错误、这么命名变量”这些规则如果每次写代码前都重复一遍效率太低。Skill 就是把这些规则、流程、示例打包好然后在合适的时机“一键调用”。熟悉 Cursor 的规则Rules功能和 MCPModel Context Protocol的读者可以把 Skill 理解成一个更聚焦的、面向具体任务的规则包。它的粒度比 Rules 更细比 MCP 更轻。Rules 是全局常驻的Skill 是按需触发的MCP 是外部工具扩展Skill 更像内部行为约束。1.2 拆解需求什么样的任务值得写成 Skill不是所有任务都值得做成 Skill。我在动手之前会先判断这个任务是否满足下面几个条件重复性高每个月至少会遇到几次同类任务或者团队里多个人都在做同一类事。流程固定任务步骤清晰、顺序基本不变比如“生成一个带标准注释的 REST API 控制器”。规则明确有硬性的代码规范、命名约定、文件组织方式。上下文复杂不提前交代清楚模型很容易跑偏但你每次都懒得重新交代一遍。比如我给自己写过几个 Skill分别处理“新增一个数据模型及迁移脚本”、“按照团队规范创建前端页面组件”、“生成某类批处理任务的代码骨架”。这三种都属于固定流程 明确规则的场景。反过来如果你只是偶尔写一段一次性脚本或者任务本身非常发散、没有标准答案那就不适合做成 Skill反而会把流程搞复杂。1.3 方案选型基于 Common Markdown 的轻量结构Cursor 的 Skill 使用的是 Common Markdown 格式这比什么自研 DSL 或者 JSON 配置要友好得多。它的好处在于可读性高任何 Markdown 编辑器都能打开查看不需要专门工具。支持分级标题天然适合结构化指令。可以嵌入 YAML frontmatter 做元数据声明让 Cursor 知道这个 Skill 何时生效。我在实际使用中强烈建议把 Skill 当成一个“完整的微项目”来组织既有说明文件SKILL.md也可以附带辅助脚本和示例文件。而不是把所有内容都塞进一个超大的 Markdown 文件里。这个思路在后面讲文件结构时会看得更清楚。2. 核心文件结构与搭建步骤2.1 目录结构每个 Skill 都是一个独立文件夹Cursor 的 Skill 在文件系统里的组织方式非常直观——每个 Skill 就是一个文件夹。以我常用的一个数据迁移类 Skill 为例目录结构大概是这样的my-skill/ ├── SKILL.md ├── scripts/ │ ├── generate_migration.py │ └── validate_migration.py └── examples/ ├── sample_migration.py └── sample_model.pySKILL.md是灵魂文件scripts/存辅助脚本可选examples/放示例代码强烈推荐。Cursor 在加载 Skill 时重点读取的是SKILL.md但你在指令中引用的辅助脚本、示例文件它也能按路径找到并读取。安装位置方面有两种常见选择全局位置所有项目都能用适合个人通用工作流。项目级目录.cursor/skills/只对当前项目生效适合团队共享、项目定制的 Skill。实际操作时我自己倾向于先在项目级目录里开发和调试稳定之后再同步到全局目录。这样避免在调试阶段污染所有项目的对话上下文。2.2 SKILL.md 的完整结构解析SKILL.md是整个 Skill 的核心结构上大体分两部分YAML frontmatter 和正文指令。先看一个完整示例再逐段解释--- name:>mkdir -p ~/.cursor/skills/code-review-assistant/scripts mkdir -p ~/.cursor/skills/code-review-assistant/examples cd ~/.cursor/skills/code-review-assistant第二步编写SKILL.md--- name: code-review-assistant description: 对用户提供的代码片段或代码变更进行结构化评审覆盖正确性、性能、可读性、安全性、测试充分性五个维度。适合在提交 PR 前自查代码或在代码评审会议中快速生成评审要点。 allowed-tools: Read, Edit --- # 代码评审助手 ## 目标 帮助用户发现代码中的潜在问题输出结构化评审意见。评审需要结合上下文文件理解代码意图而不是只看孤立片段。 ## 工作流程 1. 获取用户提供的代码片段、文件路径或变更范围 2. 读取相关上下文文件理解代码在项目中的位置和用途 3. 按五个维度逐项分析 - 正确性逻辑是否正确边界条件是否覆盖 - 性能是否存在明显的性能瓶颈或不必要的计算 - 可读性命名、结构、注释是否清晰 - 安全性是否存在注入、敏感数据泄露等典型风险 - 测试充分性关键分支是否缺少测试覆盖 4. 输出评审报告按严重程度分级阻塞 / 建议 / 可选 ## 评审报告格式 每个问题条目必须包含 - 文件路径和行号如果可定位 - 问题描述 - 严重程度 - 修改建议 ## 禁止事项 - 禁止只评价“代码风格”而忽略逻辑正确性 - 禁止在未读取上下文文件的情况下直接下结论 - 禁止输出空洞的表扬每个结论都要有依据第三步写一个辅助脚本用于统计代码文件的行数和复杂度作为评审辅助数据#!/usr/bin/env python3 import ast import sys from pathlib import Path def analyze_file(filepath): path Path(filepath) if not path.exists(): return {error: f文件不存在: {filepath}} content path.read_text(encodingutf-8) tree ast.parse(content) function_count sum(1 for node in ast.walk(tree) if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef))) class_count sum(1 for node in ast.walk(tree) if isinstance(node, ast.ClassDef)) line_count len(content.splitlines()) return { file: filepath, lines: line_count, functions: function_count, classes: class_count, } if __name__ __main__: for arg in sys.argv[1:]: result analyze_file(arg) print(result)第四步放一个示例文件examples/review_snippet.py不需要放真实项目代码放一段简单的、有明显问题的示例即可。这样模型在评审时可以参考输出格式。第五步在 Cursor 里测试。新建一个对话粘贴一段代码输入“用 review-skill 帮我评审一下这段代码”看看输出是否符合预期。3.2 核心语法与指令编写技巧这部分是最容易踩坑的多花点篇幅说清楚。关于 Description 的写法description是触发 Skill 的关键。Cursor 会把用户当前输入和你所有 Skill 的description做语义匹配。写得太笼统比如“代码评审”它的触发阈值就会很高容易在需要的时候没被触发。写得太具体比如“评审 Python Django 项目中 views.py 里的函数”那它在遇到其他语言、其他文件的评审请求时就不会触发。我的经验是description 里写清楚“做什么”和“在什么场景下用”但不要写“怎么做”。比如“对用户提供的代码片段或代码变更进行结构化评审覆盖五个维度。适合在提交 PR 前自查代码或在代码评审会议中快速生成评审要点。”这就够了。关于工作流程的描述工作流程这部分其实是在做“任务拆解”。你需要把自己平时手工操作的步骤拆解到模型能理解的程度。注意我这里说的是“模型能理解”不是“人能理解”。有一个常见的误区人的工作流里有很多“隐性步骤”这些步骤你自己都没意识到但模型没有这些隐性知识就会跳过。比如“评审代码”人会自动先找到相关的上下文文件但模型如果不明确指导很可能只看你给它粘贴的这段代码就开始评审了。所以在工作流程里我会特意加一步“读取相关上下文文件理解代码在项目中的位置和用途”这个在人工评审时几乎是无意识的但对模型非常重要。但也要注意不要过度拆解。一个 Skill 的工作流程控制在 4~8 步之间比较合适。步骤太多模型反而会因为指令过长而在执行时“忘记”前面的步骤。关于禁止事项的写法禁止事项是对模型行为的负向约束它和正向指令配合使用效果更好。我在写禁止事项时通常会回忆一下自己在手写这些任务时最不能容忍模型出现的错误然后一条一条列出来。比如代码评审 Skill 里我写“禁止输出空洞的表扬每个结论都要有依据”——这是因为 AI 天然倾向于说好话如果没有这个约束它给的评审报告大多会流于“这段代码逻辑清晰、结构合理”之类的废话完全失去使用价值。工具调用的边界在allowed-tools字段里要做权衡。完全不给工具权限模型就只能基于现有上下文做分析无法读取新文件给太多权限比如 Terminal模型可能在评审时突然给你执行一段命令容易出险情。我的建议是默认允许Read和Edit只有在确实需要生成代码、批量修改文件的时候才加上Write。Terminal权限尽量不给除非这个 Skill 的核心用途就是执行某类命令。3.3 参数传递与上下文引用一个容易被低估的细节是Skill 在执行时如何获取你正在编辑的文件内容。在最简单的情况下你可以在对话中手动提供代码片段或文件路径。Skill 的指令里写“读取用户提供的文件路径”即可。但更常见的情况是你希望 Cursor 主动感知当前活动文件。这种场景下你需要在指令中明确写出“读取当前活动文件”并告诉 Cursor 如何找到它。我在实际测试中发现一个取舍如果 Skill 的每条指令都要求“读取当前活动文件”那么在项目经理人之下执行会比较自然但如果用户在对话中已经明确说了“不要动当前文件只看我粘贴的这段”Skill 的工作流程里就要有这个判断分支。所以我在 Skill 指令的开头加了一行## 输入确定 - 如果用户提供了文件路径则优先读取对应文件 - 如果用户只提供了代码片段则仅基于该片段和对话上下文进行分析 - 如果用户没有提供任何代码询问用户需要评审的对象是什么这个“输入确定”小节看似废话实际作用非常大。它帮模型在动手前先搞清楚边界条件避免“瞎猜”造成误操作。4. 调试流程与常见问题排查实录4.1 调试 Skill 的正确姿势写 Skill 和写代码一样几乎不可能一遍过。我在调试时有一套固定的流程分享出来供参考。第一步先测触发在 Cursor 的对话栏里输入测试语句看看你的 Skill 是否会被触发。只有在触发成功的前提下后续调试才有意义。触发测试说起来简单实际经常卡住。我遇到过的情况是明明在对话里提到了和 Skill description 高度相关的关键词但 Skill 就是没被触发。排查下来发现原因是用户在对话里没有使用英文关键词而 Cursor 的语义匹配对中文支持不如英文稳定。解决方案有两种一是把 description 里加上中英文双语关键词二是在对话时主动用“用 xxx-skill 来做”这种句式显式点名 Skill 名称。有经验的用户会主动在描述description里携带技能名和多个同义触发词这个习惯能让 Skill 的命中率提升一个台阶。第二步单步验证指令触发成功后不要直接扔一个复杂任务进去。先给一个简化版输入看看 Skill 的基本流程是否被执行。比如测试代码评审 Skill 时给一段带有明显 bug 的短代码观察输出报告是否包含五个维度。如果五个维度不完整大概率是工作流程的描述不够结构化模型在执行时忽略了你写的步骤。第三步验证边界情况给 Skill 一个“不好处理”的输入看看它会怎么应对。比如故意不给文件路径只给代码片段或者给多个文件路径看它会不会逐个读取并分别评审。这些边界情况如果不提前测等真用的时候踩坑再改就麻烦得多。第四步模拟真实场景最后一步我会把 Skill 放到真实项目里跑一遍用实际代码来验证产出质量。这时候重点看两个东西一是生成的内容是否符合团队规范二是生成过程中模型的提问是否合理——如果模型在关键步骤频繁向你确认“我这样做对吗”多半是 Skill 指令里的约束还不够明确。4.2 高频问题的排查技巧这里把我在实际使用中遇到的问题整理一下每条都附了排查思路。问题现象可能原因排查与解决办法Skill 从未触发description 写得太泛或触发的语境和描述不匹配改写 description加入更明确的场景词和触发词对话中主动点名 Skill 名称Skill 触发了但行为完全不对工作流程描述不清晰或者正文太长模型丢失了上下文精简指令正文把最重要的约束放在靠前的位置把详细规则挪到辅助文档中引用指令里的步骤被部分执行步骤描述太抽象模型不知道如何“落地”把步骤改成“行为指令”明确每一步要做什么、使用什么工具、产生什么输出生成了不符合规范的文件没有提供足够具体的“规范定义”在 SKILL.md 中增加“代码规范”小节并附上参考示例文件辅助脚本无法执行路径写错了或用的是绝对路径导致文件夹移动后失效检查脚本路径引用统一改成相对路径修改 SKILL.md 后行为没变化Cursor 缓存了旧的 Skill 内容重新加载窗口或在对话中输入重新加载/继续执行的指令第一条里那个“主动点名 Skill 名称”的办法虽然看起来不够“智能”但实际体验反而最稳定。Cursor 的语义匹配本身就有一定随机性与其依赖它猜不如直接告诉它“用这个 Skill”。4.3 版本管理与多环境同步Skill 文件本身就是文本天然适合纳入版本管理。我的习惯是每个 Skill 单独建一个仓库或者在一个仓库下按目录区分。这样每次改完都能看到 diff回滚也方便。多环境同步方面要注意全局目录和项目目录的优先级问题。如果同一个 Skill 在全局和项目都存在项目级目录会覆盖全局。这个特性可以用来做团队定制项目目录里放加了团队特殊规则的 Skill 副本全局目录放自己的通用版互不干扰。我自己经历过一次比较惨痛的教训在某公司项目里项目级目录放了一份 Skill 改动后来项目合并时这份改动被误提交到了代码仓库直接影响了同事们的 Cursor 行为。后来我学乖了所有 Skill 改动都先在自己全局目录下测试确认稳定后再同步到项目目录并且在.gitignore里把.cursor/skills明确排除掉。5. 内容深化与场景扩展5.1 不只是代码生成Skill 的更多使用场景Skill 的应用领域比很多人想象得宽。除了代码生成和评审我目前用到的还有几类效果都很不错。第一类是文档生成类。写接口文档这件事多数人不爱做但流程特别固定——读代码、提取入参出参、生成 Markdown 表格。我写了一个api-doc-generatorSkill包含生成文档时必须遵守的模板格式和字段说明规则。触发之后只需要告诉我要给哪个接口生成文档它就能自己读代码、整理参数、输出标准格式的文档比我手工写快得多。第二类是项目初始化类。每次新建一个微服务模块都要经历建目录、搭配置、写最小可运行代码这一套流程。这些步骤的重复率接近百分之百而且细节多、容易漏。做成 Skill 后一条指令就能产出标准骨架。第三类是测试用例生成类。给一个函数或接口Skill 会按照团队习惯批量生成边界测试、异常测试、性能测试的桩代码。这类 Skill 的关键点是“禁止事项”要写得特别细否则模型生成的测试用例容易脱离项目实际。这些非编码类场景有一个共同特点输出物的格式和规范比内容本身更难约束。所以写这类 Skill 时重点不是教模型“怎么写代码”而是教它“怎么按照模板输出”模板实际上比思维链更有约束力。5.2 进阶技巧Skill 与 MCP 工具的协同当你需要 Skill 不止“指导模型”还要让它“执行动作”时就得考虑和 MCP 工具协同了。比如我写过一个deploy-helperSkill它的作用是指导模型按团队规范完成部署前检查。部署前要跑一遍测试、检查配置、确认依赖版本。这些动作如果只靠对话指导模型在没有实际执行权限的情况下只能“建议”不能“做”。配合 MCP 工具后Skill 的工作流程可以变成这样第一步读取部署配置第二步调用 MCP 的测试执行工具跑测试第三步根据测试结果决定是继续还是停止。这种“Skill 定策略、MCP 做执行”的组合才真正把 Cursor 从一个聊天助手变成了自动化流程引擎。这里要提醒一句给 Skill 配上工具权限时一定要克制。MCP 工具的权限比单纯的文件读写大得多一旦 Skill 的指令中没有把边界写清楚模型执行时很容易做出超出预期的行为。我在写配合 MCP 的 Skill 时会在允许工具列表中精确列出需要的工具并且在工作流程里明确“只有在哪些条件下才调用工具”。5.3 分享与复用社区协作的实用建议写好了 Skill不只是自己用。我身边不少同事都在互相交换各自写的 Skill这确实能省掉大量重复造轮子的时间。分享时我一般会注意三点把 Skill 里的项目定制内容剥离出来。比如我在某项目的 Skill 里写了该项目的日志规范分享出去别人用不上还会造成误解。通用版本和定制版本分开维护。写一个简短的 README说明这个 Skill 适合什么场景、不适合什么场景。这个帮助别人决策的信息比我自己的 SKILL.md 正文还有价值。附上测试用例或示例输入。一套 Skill 的示例输入和预期输出是别人理解它行为的最佳途径。从社区里获取 Skill 时不要盲目相信高星项目。先把 SKILL.md 打开读一遍确认它的指令逻辑对你是否友好。有些 Skill 为了追求覆盖度指令写得极其冗长实际使用时反而因为上下文被占满而表现不佳。我个人的评判标准很简单这个 Skill 的工作流程我平时手工做会不会这么做如果连我自己都不会按这个流程走那它给我带来的帮助也有限。写 Skill 时踩过的坑最后分享几个我在实际写 Skill 的过程中踩过比较深的坑每一个都花了不少时间才绕出来。第一个坑把 Skill 当成万能工具。什么任务都想做成 Skill写完才发现根本不会用几次。判断值不值得写标准就是我前面说的那四条——重复性、流程固定、规则明确、上下文复杂。至少满足三条再动手。第二个坑一次想把所有规则都写全。SKILL.md 里恨不能把项目里的所有编码规范都放进去结果模型在执行时被超长指令搞晕了该遵守的根本遵守不住。后来我把 SKILL.md 的正文控制在 150 行以内长规范放到单独的docs/子目录里用“如果需要详细规则先阅读 docs/coding-standards.md 再开始”来引导。实测效果比把规则全堆在主文件里好得多。第三个坑忽视模型能力边界。有一个 Skill 需要模型在处理大量配置后做数值计算结果模型经常算错。后来把数值计算部分改成调用 Python 脚本模型只负责解析输入和整理输出准确率直接拉满。Skill 的职责是“分配任务”不是“所有事情都自己干”。凡是确定性强的逻辑统统交给脚本。第四个坑改了 Skill 文件却不重启验证。有时候我改了 SKILL.md发现行为没变化开始怀疑 Cursor 是不是有 bug。后面才知道需要重新加载窗口让 Cursor 重新读取 Skill 目录。现在养成了习惯每次改动后先重开一个对话测试避免旧上下文干扰判断。Skill 这个功能最吸引我的地方在于它让 Cursor 从“一个通用的 AI 编程助手”变成了“一个懂你工作习惯的私人员工”。你不再需要向它交代那些你已经重复过很多遍的背景和规范它自己就知道该用什么方式来做你的事。而且这个适应过程完全掌握在你手里文件就是纯文本随时可以改随时可以回滚。如果你手上正好有一件已经重复过很多次、流程固定到闭着眼睛都能做的事照着上面的结构写一个 Skill 试试大概率会发现原来那些烦人的重复工作真的可以几句对话就结束。