1. 为什么技能包正在取代提示词收藏夹前两年大家聊 AI 编程聊的都是提示词工程——收藏一堆咒语用的时候翻出来粘贴。但真在项目里跑过几轮的人都知道这套玩法有个致命问题提示词是无状态的。你这次让它按团队规范写单测下次开新会话它又忘了。你得反复贴、反复调最后干脆放弃回到能跑就行的状态。Skills 这套机制解决的正是这个问题。它把怎么做某件事从一次性的对话里抽出来固化成一个带元数据的文件——通常叫SKILL.md——放在约定的目录下。AI 编程工具在需要的时候自动读取、按需加载不需要你每次手动喂。你可以把它理解成给 AI 装的插件只不过这个插件不是代码而是结构化的操作说明。我最初接触这个概念是在 Cursor 和 Claude Code 上。当时团队里有个痛点新人写的接口层代码风格五花八门有人用async/await有人用 Promise 链错误处理有的抛异常有的返回{code, msg}。我们试过写 ESLint 规则但规则只能管语法管不了这个场景该用哪种模式。后来把团队约定写成 Skill让 AI 在生成代码前先读一遍风格统一度肉眼可见地提升了。这篇内容适合三类人一是刚听说 Skills 但不知道从哪下手的开发者二是已经在用 Cursor 或 Claude Code但还在靠复制粘贴提示词的人三是想自己写 Skill 分享给团队或社区的人。我会把装什么怎么装装完怎么验证这三件事讲透中间穿插我自己踩过的坑。提示Skills 不是万能的。它擅长的是流程性、重复性、有明确规范的任务。如果你的需求是帮我随便想个创意那 Skill 帮不上忙那是模型本身的能力范畴。2. 八类真正值得装的 Skills以及它们各自解决什么问题市面上的 Skill 仓库已经不少了但大部分是玩具。我按实际项目里能不能省时间这个标准筛出八类真正值得装的。每一类我都会说清楚它解决什么痛点、适合什么场景、装之前要注意什么。2.1 代码规范与风格统一类这是最刚需的一类。典型场景是团队有一套内部规范但 ESLint/Prettier 覆盖不到比如service 层必须返回统一的 Result 对象日志必须带 traceId数据库查询必须走 repository 层不能直接调 ORM。这类 Skill 的核心是把隐性的团队约定显性化。写的时候要注意不要写成要写高质量代码这种废话而要写成可判定的规则。比如## 错误处理规范 - 所有对外接口的异常必须捕获转换为 Result.fail(code, msg) - 禁止在 controller 层直接 throw必须走全局异常处理器 - 日志使用 logger.error禁止 console.log我装过的一个坑是规则写太细细到变量名必须用驼峰且不超过 20 字符结果 AI 每次生成代码都要纠结命名反而拖慢速度。后来我把这类交给 ESLintSkill 里只留业务语义层面的约定效果好很多。2.2 测试生成与用例补全类写单测是很多人的噩梦。这类 Skill 的价值在于让 AI 按你项目的测试框架、断言风格、mock 方式来生成用例而不是生成一堆跑不起来的样板。关键点在于告诉 AI 你的测试基础设施。比如你用 Jest 还是 Vitest用jest.mock还是vi.mock断言用expect().toBe()还是assert.equal()。这些不写清楚生成的测试十有八九要手改。我自己的做法是在 Skill 里附一个参考测试文件的路径让 AI 先读那个文件再生成。这招比写一堆文字描述管用得多因为模型对代码示例的理解远好于对自然语言规则的理解。2.3 提交信息与变更日志类Conventional Commits 规范大家都知道但真正每次都写对的人不多。这类 Skill 让 AI 在git commit前帮你生成符合规范的 message还能顺带更新 CHANGELOG。我实测下来这类 Skill 的准确率和你的 diff 质量强相关。如果一次提交改了 20 个文件、跨了三个模块AI 也很难总结出一句话。所以我的建议是小步提交每次提交聚焦一件事Skill 才能发挥价值。2.4 代码审查与安全扫描类这类 Skill 相当于给 AI 装了一双审查眼。它会按你定义的检查项过一遍代码有没有硬编码密钥、有没有 SQL 拼接、有没有未处理的 Promise rejection、有没有越权风险。要注意的是这类 Skill 容易产生误报。比如它看到eval就报警但你的场景是解析配置文件其实安全。所以我在 Skill 里加了一条如果判断为误报说明理由并跳过避免每次审查都刷一屏无用告警。2.5 文档生成与注释补全类老项目最缺的就是文档。这类 Skill 能读代码生成 API 文档、补全 JSDoc、画模块依赖关系。我拿它处理过一个三年没维护的 Node 服务生成的接口文档虽然不能直接用但至少让我快速摸清了有哪些路由、参数是什么。这里有个技巧让 AI 生成文档时标注置信度。对于它读得懂的代码标高对于动态拼接、反射调用的部分标低需人工确认。这样你 review 的时候知道哪些要重点看。2.6 数据库与迁移脚本类涉及数据库变更时这类 Skill 能帮你生成迁移脚本、回滚脚本、以及对应的实体类。它解决的是改表容易忘同步代码的问题。我踩过的坑是AI 生成的迁移脚本没有考虑大表加字段的锁表风险。后来我在 Skill 里明确写了超过百万行的表加字段必须用 online DDL 或分步迁移才避免了一次生产事故。2.7 前端组件与样式规范类前端场景下这类 Skill 管的是组件结构、样式方案CSS Modules / Tailwind / styled-components、状态管理约定。比如所有列表组件必须处理 loading、empty、error 三态。前端 Skills 的难点在于框架版本差异大。React 18 和 19 的写法不同Vue 2 和 3 差异更大。所以装之前一定要确认 Skill 声明的版本和你项目一致否则生成的代码可能跑不起来。2.8 项目脚手架与初始化类新项目启动时这类 Skill 能按你的技术栈生成目录结构、配置文件、CI 模板。它省的是每次开新项目都要重新配一遍的时间。我的经验是这类 Skill 要定期更新。因为依赖版本、构建工具、CI 平台都在变半年前写的脚手架 Skill 可能已经过时了。我一般每季度过一遍把废弃的配置删掉。Skill 类别核心价值最容易踩的坑代码规范统一团队风格规则写太细拖慢生成测试生成减少样板代码没说明测试框架生成跑不通提交信息规范 commit大提交难以总结代码审查提前发现问题误报多需加豁免机制文档生成补历史债动态代码置信度低数据库迁移代码表结构同步忽略大表锁风险前端组件三态处理规范框架版本不匹配项目脚手架快速初始化依赖过时3. 从零接入 Cursor目录放哪、怎么触发、怎么验证Cursor 对 Skills 的支持相对直接但目录位置和触发方式有几个容易搞错的点。我按实际操作顺序讲一遍。3.1 目录结构全局还是项目级Cursor 读取 Skill 的位置有两个层级项目级放在项目根目录下的.cursor/skills/里。只对当前项目生效适合团队共享。全局级放在用户目录下的.cursor/skills/macOS/Linux 是~/.cursor/skills/Windows 是%USERPROFILE%\.cursor\skills\。对所有项目生效适合个人通用规范。我的建议是团队规范放项目级个人习惯放全局级。项目级的可以提交到 Git新人 clone 下来就自动生效全局级的放自己机器上不污染团队仓库。每个 Skill 是一个独立文件夹里面至少有一个SKILL.md。文件夹名就是 Skill 名建议用英文短横线命名比如api-error-handling、test-generation。.cursor/ skills/ api-error-handling/ SKILL.md test-generation/ SKILL.md reference-test.ts # 可选参考文件3.2 SKILL.md 的头部元数据怎么写SKILL.md开头有一段 YAML frontmatter这是给工具读的不是给人读的。格式大概是这样--- name: api-error-handling description: 统一 API 层的错误处理规范适用于 controller 和 service 层 --- ## 规范内容 ...name和description是关键。description写得好不好直接决定 AI 能不能在正确的时机触发这个 Skill。我见过有人写description: 代码规范太笼统AI 根本不知道什么时候该用。好的写法是说清楚适用场景比如当生成或修改 controller、service 层代码时使用。3.3 触发方式自动还是手动Cursor 里 Skill 的触发有两种自动触发AI 根据description判断当前任务是否匹配匹配就自动加载。这是默认行为。手动引用在对话里用skill-name显式引用。适合你明确知道要用哪个 Skill 的场景。我实测下来自动触发的准确率大概七成。有时候你明明在改 controller它却没加载错误处理 Skill。这时候手动一下更稳。所以我的习惯是关键任务手动引用日常任务靠自动。3.4 验证 Skill 是否真的生效装完 Skill 别急着信先验证。方法很简单开一个新会话让它做一件 Skill 覆盖范围内的事然后看输出是否符合规范。比如你装了错误处理规范Skill就让它写一个查询用户的接口。如果它返回的是Result.fail()而不是直接 throw说明生效了。如果还是老样子检查三件事SKILL.md的 frontmatter 格式对不对有没有多余空格或缩进错误。description是否足够具体能不能让 AI 判断出适用场景。文件是不是放在了正确的目录层级。注意Cursor 不同版本对 Skills 的支持程度不一样。如果你用的是较老版本可能需要在设置里手动开启相关选项。升级到最新版通常能省掉这些麻烦。4. Claude Code 的 Skills 接入和 Cursor 的差异在哪Claude Code 是命令行工具Skills 的接入逻辑和 Cursor 有相似之处但细节差异不小。如果你两个都用这部分要重点看。4.1 安装与目录约定Claude Code 的 Skill 目录通常在~/.claude/skills/全局和项目根目录的.claude/skills/项目级。结构和 Cursor 基本一致也是每个 Skill 一个文件夹加一个SKILL.md。但 Claude Code 有个额外机制它支持从 GitHub 仓库直接安装 Skill。如果你看到别人分享的 Skill 仓库可以用命令直接拉下来不用手动复制文件。具体命令各版本略有不同建议以官方文档为准。我手动装过 GitHub 上的 Skill流程是clone 仓库找到里面的skills目录把需要的文件夹复制到.claude/skills/下。听起来简单但有个坑有些仓库的 Skill 依赖额外的脚本或资源文件只复制SKILL.md会缺东西。所以复制前先看一眼文件夹里还有什么。4.2 Claude Code 的 Skill 加载时机Claude Code 在启动时会扫描 Skill 目录但不会一次性全部加载到上下文里。它是按需加载的——当你的任务匹配某个 Skill 的description时才把内容读进来。这个设计很聪明避免了上下文被一堆用不上的 Skill 占满。这也意味着description的质量在 Claude Code 里更加关键。因为它是唯一的触发依据。我建议description里同时包含动作和对象比如生成数据库迁移脚本时使用而不是数据库相关。4.3 和 VS Code 配合使用的场景很多人是在 VS Code 里用 Claude Code 的。这种组合下Skill 的目录位置不变但触发方式可能受 VS Code 插件影响。我的经验是在 VS Code 集成终端里跑 Claude CodeSkill 行为和纯命令行一致。如果你用的是图形化插件注意看它有没有自己的 Skill 配置入口别配了两套。VS Code 本身也有 AI 相关扩展但它们和 Claude Code 的 Skills 是两套体系不要混为一谈。Skill 是 Claude Code 的能力VS Code 只是承载它的编辑器。4.4 两个工具共用 Skill 的可行性如果你 Cursor 和 Claude Code 都用会想能不能共用一套 Skill。答案是可以但要处理格式差异。两者的 frontmatter 字段基本兼容但触发机制和加载逻辑不同所以同一个SKILL.md在两个工具里的表现可能不一样。我的做法是维护一份源 Skill放在独立仓库里然后用脚本同步到两个工具的目录。这样改一处两边都更新。如果懒得搞脚本至少保证description写得足够通用两边都能识别。对比项CursorClaude Code全局目录~/.cursor/skills/~/.claude/skills/项目目录.cursor/skills/.claude/skills/触发方式自动 手动主要靠 description 自动加载策略按需按需远程安装手动复制为主支持从仓库安装共用可行性可共用需注意格式兼容同左5. 自己写一个 Skill从需求到落地的完整过程装别人的 Skill 只能解决通用问题真正贴合你项目的还得自己写。我拿一个真实案例走一遍给一个 Node Express 项目写接口错误处理Skill。5.1 先想清楚这个 Skill 要解决什么具体问题不要一上来就写。先回答三个问题现在不做这件事会出什么问题我们的情况是新人写的接口有的返回{code: 0, data}有的返回{success: true, result}前端对接时经常搞错。这个问题出现的频率高吗高。每个新接口都可能踩。AI 能帮上忙吗能。只要告诉它统一格式它生成代码时就会遵守。三个问题都过了才值得写 Skill。如果只是偶发问题写个文档提醒一下就行没必要上 Skill。5.2 把隐性知识拆成可执行的规则这一步最难。团队老手觉得这不是常识吗的东西恰恰是新人最容易错的。我的方法是翻最近的 code review 记录把被反复指出的问题列出来那就是 Skill 要覆盖的内容。针对错误处理我列出的规则是所有 controller 方法必须用 try/catch 包裹catch 里统一调用next(error)交给全局错误中间件全局中间件把错误转换为{code, message, data: null}格式业务错误用自定义BizError带错误码系统错误记录完整堆栈业务错误只记 message这些规则写进SKILL.md配上正例和反例代码AI 就能照着执行。5.3 写 description 的技巧让 AI 在对的时候想起来description是 Skill 的广告语要同时满足两个条件AI 能判断适用场景人能看懂这是干嘛的。我最初的写法是description: 错误处理规范结果 AI 很少触发。改成description: 当生成或修改 Express controller、service 层代码或处理接口异常时使用统一错误返回格式之后触发率明显上升。关键是把触发条件写进去。AI 判断是否加载 Skill靠的就是这段描述和当前任务的匹配度。描述里包含的动作词越多匹配机会越大。5.4 正例反例对照比纯文字规则有效十倍我试过纯文字规则AI 遵守率一般。加上代码对照后遵守率大幅提升。因为模型对代码模式的学习能力远强于对抽象规则的理解。// 反例直接返回格式不统一 app.get(/user/:id, async (req, res) { const user await db.findUser(req.params.id); res.json({ success: true, result: user }); }); // 正例统一走错误中间件 app.get(/user/:id, async (req, res, next) { try { const user await db.findUser(req.params.id); if (!user) throw new BizError(40401, 用户不存在); res.json({ code: 0, message: ok, data: user }); } catch (err) { next(err); } });正例反例不用多每个规则配一组就够。多了反而让 Skill 文件臃肿加载时占用上下文。5.5 测试与迭代怎么知道 Skill 写得好不好写完不是结束要测。我的测试方法是开三个新会话分别让它写一个查询接口、一个创建接口、一个删除接口看输出是否符合规范。三个都过基本可用有一个不过回去改 Skill。迭代时重点看两类问题一是规则没覆盖到的场景补进去二是规则被误解的场景改表述。我那个错误处理 Skill 迭代了三版第一版漏了参数校验失败的处理第二版补上后又发现 AI 把校验错误也当系统错误记堆栈了第三版才把两类错误分开。6. 装了一堆 Skill 之后我踩过的那些坑Skill 装多了问题也跟着来。这部分讲几个真实踩过的坑都是文档里不会写的。6.1 Skill 之间规则打架我同时装了代码规范和快速原型两个 Skill。前者要求所有函数必须写 JSDoc后者要求原型阶段省略注释保持简洁。结果 AI 生成代码时一会儿加注释一会儿不加非常混乱。解决办法是给 Skill 划分明确的适用边界。在description里写清楚仅在正式代码中使用或仅在原型验证阶段使用。如果两个 Skill 场景重叠就合并成一个用条件分支处理。6.2 上下文被 Skill 挤占Claude Code 的上下文窗口有限。如果一次加载了五六个 Skill每个几百行留给实际代码的空间就少了。我遇到过加载太多 Skill 后AI 开始忘记前面的对话内容。对策是精简 Skill 内容。规则能一句话说清就别写三段正例反例各一个就够。另外不常用的 Skill 及时从目录里移走别让它有机会被加载。6.3 Skill 过期导致的错误建议我有个数据库迁移 Skill是半年前写的里面推荐的迁移工具已经换了 API。结果 AI 按旧 API 生成脚本跑起来直接报错。这件事之后我养成了习惯每个 Skill 标注最后更新日期超过三个月的过一遍。特别是涉及第三方库、框架版本的 Skill过期风险最高。6.4 团队共享时的路径问题把项目级 Skill 提交到 Git 后同事 clone 下来发现不生效。排查半天发现是.cursor目录被.gitignore忽略了。很多项目的 gitignore 模板里默认忽略.cursor和.claude需要手动加白名单。# .gitignore 里加上 !.cursor/skills/ !.claude/skills/这个坑很隐蔽因为本地测试时 Skill 是生效的只有别人 clone 才暴露。6.5 过度依赖 Skill 导致的能力退化这个坑比较主观但我觉得值得说。有段时间我什么任务都想让 Skill 代劳连这个函数该叫什么名都要问 AI。结果是自己对代码的掌控感变弱了review 时也看不出问题。后来我调整了策略Skill 处理重复性、规范性任务创造性、决策性任务自己来。比如架构设计、技术选型这些不该交给 Skill。Skill 是工具不是替你把活干完的保姆。7. 让 Skills 真正融入日常开发流的几个习惯装好 Skill 只是开始用起来才有价值。分享几个我坚持下来的习惯。7.1 新项目初始化时先配 Skill我现在开新项目第一件事不是写代码而是把团队通用的 Skill 复制进去。这样从第一个 commit 开始代码风格就是统一的省得后期再改。具体做法是维护一个Skill 模板仓库新项目 clone 下来后把skills目录复制到项目里改一下项目相关的配置比如框架版本就能用。7.2 把 code review 的高频问题沉淀成 Skill每次 code review 发现重复问题我就问自己这个问题能不能写成 Skill能就写不能就写进团队文档。坚持几个月后review 里指出的问题明显减少因为 AI 在生成阶段就规避了。这个习惯的关键是及时。review 完当场记下来别攒着。攒着就忘了或者记的时候已经想不起具体场景。7.3 定期清理和更新 Skill 库我每个月花半小时过一遍 Skill 目录做三件事删掉不再用的、更新过期的、合并重复的。听起来麻烦但比让一堆失效 Skill 拖慢 AI 响应强。清理时我会看每个 Skill 的最后触发时间如果工具支持的话超过两个月没触发的基本可以删了。说明要么场景不匹配要么有更好的替代。7.4 和团队同步 Skill 的使用情况Skill 是团队资产不是个人玩具。我会在团队周会上花五分钟同步这周新增了什么 Skill、哪个 Skill 效果好、哪个有问题。这样大家能互相借鉴避免重复造轮子。同步时重点讲效果不讲原理。比如这个测试生成 Skill 让写单测的时间少了一半比这个 Skill 用了什么机制更能引起兴趣。8. 关于 Skill 选型和自建的几点个人判断最后聊几个我自己的判断不一定对但都是实际用下来形成的观点。第一Skill 不在多在精。我见过有人装了三十多个 Skill结果 AI 响应变慢还经常触发错误的 Skill。我现在稳定在用的就六七个覆盖规范、测试、提交、审查四类核心场景够用了。第二优先装约束型Skill谨慎装生成型Skill。约束型比如规范、审查是告诉 AI不要做什么风险低生成型比如脚手架、文档是让 AI创造什么质量参差。生成型的装之前一定先小范围试用。第三自建 Skill 的投入产出比取决于你的项目有多特殊。如果你的项目就是标准 CRUD用社区 Skill 就行如果有一堆内部约定、自研框架那自建才划算。判断标准很简单社区 Skill 生成的代码你需要改多少才能用。改得少就用社区的改得多就自己写。第四Skill 的维护成本被严重低估。写一个 Skill 可能只要一小时但维护它要持续投入。依赖变了要改、团队规范变了要改、工具版本升级了要改。所以别贪多写之前想清楚能不能坚持维护。第五别指望 Skill 解决人的问题。如果团队本身没有统一规范写 Skill 也没用因为你自己都不知道该让 AI 遵守什么。Skill 是规范的载体不是规范的替代品。先把规范定下来再考虑用 Skill 落地。我在实际使用中最深的一个体会是Skill 真正的价值不在于让 AI 多干活而在于让 AI 按你的方式干活。前者是效率问题后者是质量问题。效率提升有限但质量提升是复利的——每次生成的代码都符合规范长期下来省下的返工时间远超预期。如果你刚开始接触我的建议是从一个 Skill 开始就用你最痛的那个场景。跑通一遍完整流程——写、装、测、迭代——你就理解这套机制了。剩下的就是复制这个流程慢慢积累自己的 Skill 库。