1. 为什么装技能这件事值得单独写一篇指南最近半年AI 编程助手的能力边界被一个叫 Skills 的机制彻底改写了。如果你还在用打开对话框、贴代码、等回答这种最原始的方式跟 Cursor 或 Claude Code 打交道那你大概只发挥了它们三成的功力。Skills 的本质是把一套可复用的工作流、领域知识和操作规范打包成 AI 能主动识别并调用的技能包。装上一个好技能相当于给你的 AI 助手请了一位专项教练——它不再只会泛泛而谈而是知道在什么场景下该用什么方法、该遵守什么规范、该输出什么格式。我最初接触 Skills 是因为一个很具体的痛点每次让 AI 帮我写数据库迁移脚本它总是忘记加事务回滚也总是忽略我们团队特定的命名约定。每次都要在提示词里重复交代一遍烦不胜烦。后来我把这些规范写进一个 SKILL.md 文件放进项目的技能目录问题一次性解决。从那以后我开始系统性地研究 Skills 的机制、生态和最佳实践陆续装了二十多个技能踩了不少坑也总结出一套自己的选型逻辑。这篇内容面向三类人一是刚听说 Skills 但不知道从哪下手的开发者二是已经装了技能但感觉没什么用的中级用户三是想自己写技能但不知道怎么写才规范的人。我会先讲清楚 Skills 的底层机制再给出 8 类经过实测值得装的技能清单然后手把手带你走完 Cursor 和 Claude Code 的接入全流程最后分享一些只有实际用过才会知道的坑和技巧。全文基于我自己的使用经验涉及具体操作的地方都会给出可复现的步骤。需要提前说明的是Skills 生态还在快速演进中不同工具对技能的支持程度和加载方式有差异。我会尽量区分通用机制和工具特定行为但你在实际操作时还是要以自己所用工具的官方文档为准。另外技能文件本身是纯文本的 Markdown这意味着你可以用任何编辑器写、用 Git 管理、在团队内共享这一点比很多封闭的插件体系要友好得多。2. Skills 到底是怎么工作的从 SKILL.md 到自动调用2.1 一个技能文件的最小结构很多人以为 Skills 是什么高深的技术其实拆开看非常简单。一个技能就是一个文件夹里面至少有一个SKILL.md文件。这个文件用 Markdown 写成顶部有一段 YAML 格式的元信息frontmatter下面是给 AI 看的正文指令。最小结构长这样--- name: database-migration description: 当用户需要编写或审查数据库迁移脚本时使用此技能确保包含事务回滚和命名规范 --- # 数据库迁移规范 ## 命名约定 - 迁移文件名格式YYYYMMDDHHMMSS_动词_对象.sql - 动词限定为create、alter、drop、add、remove ## 强制要求 1. 每个迁移脚本必须包含 up 和 down 两个方向 2. 所有 DDL 操作必须包裹在事务中 3. 涉及数据变更的必须提供回滚方案关键在description这一行。AI 在决定是否调用某个技能时主要依据就是这段描述。它相当于技能的广告语要精准告诉 AI什么场景下该用我。描述写得太宽泛比如帮助写代码AI 会在不相关的场景乱调用写得太窄又会在该用的时候想不起来。2.2 渐进式加载为什么技能不会撑爆上下文这是 Skills 设计里最精妙的一点。你装了几十个技能AI 并不会把每个技能的全文都塞进上下文窗口——那样 token 早就爆了。实际机制是分层的第一层AI 只加载所有技能的name和description这部分非常短几十个技能加起来也就几百 token。第二层当 AI 判断某个技能与当前任务相关时才把该技能的SKILL.md正文读进来。第三层如果技能文件夹里还有额外的参考文档、脚本、模板AI 会在需要时按需读取。这个机制叫渐进式披露progressive disclosure。理解它的意义在于你可以放心地装很多技能不用担心性能问题但同时description的质量直接决定了技能会不会被正确触发。我见过太多人技能写得很好但描述一句话带过结果 AI 从来不调用然后抱怨Skills 没用。2.3 技能、提示词、规则三者的边界新手最容易混淆的是技能和系统提示词、项目规则比如 Cursor 的 Rules、Claude Code 的 CLAUDE.md有什么区别我的理解是这样系统提示词全局生效定义 AI 的基本人格和行为准则你一般改不了或不该频繁改。项目规则针对某个项目生效定义这个项目的技术栈、代码风格、目录结构等始终成立的约束。技能按需触发定义在特定任务场景下才需要遵守的流程和知识。举个例子这个项目用 TypeScript 严格模式是项目规则因为它始终成立写 React 组件时要先检查是否已有同类组件可复用是技能因为它只在写组件的场景下才相关。把该做成技能的东西塞进项目规则会让规则文件臃肿且拖慢每次对话把该做成规则的东西写成技能又会导致 AI 在该遵守的时候想不起来。2.4 技能能调用脚本这才是真正的杀手锏纯文本指令只能约束 AI 的思考方式但技能文件夹里可以放可执行脚本。当技能被触发时AI 可以运行这些脚本把确定性的工作交给代码把需要判断的工作留给自己。比如一个生成 API 文档的技能可以附带一个解析代码注释的 Python 脚本AI 负责理解业务语义脚本负责提取结构化信息。这个能力让 Skills 从提示词模板升级成了轻量级自动化框架。我有个技能专门用来检查提交信息是否符合规范里面放了一个正则校验脚本AI 在准备提交前会调用它不通过就打回重写。这种AI 脚本的组合比纯靠 AI 判断可靠得多。3. 八类实测值得装的技能以及各自的适用边界市面上的技能越来越多但真正高频有用的其实就那么几类。下面这八类是我自己装了之后持续在用、并且推荐给团队成员的。每一类我都会说清楚它解决什么问题、什么场景下值得装、以及我踩过的坑。3.1 代码规范类把团队约定变成 AI 的肌肉记忆这类技能解决的是AI 写的代码风格跟团队不一致的问题。典型内容包括命名约定、目录结构规范、错误处理模式、日志格式、注释风格。我装的那个叫team-conventions里面把我们前端团队的规则写得清清楚楚组件文件用 PascalCase、工具函数用 camelCase、所有异步操作必须 try-catch 并上报错误、禁止使用any。装之前AI 生成的代码我平均要改 5 处才能合入装之后基本一次过。这里的关键是规则要具体到可执行。写代码要清晰没用写函数超过 40 行必须拆分才有用。我建议你把团队 Code Review 里最常打回的几条意见整理出来那就是这个技能的核心内容。注意不要把 ESLint 能管的规则写进技能。技能管的是机器难判断、需要语义理解的规范比如这个抽象是否过度这个命名是否准确表达意图。格式问题交给格式化工具。3.2 框架专项类React、Vue、后端框架的深度知识通用 AI 对框架的理解往往停留在能用层面但每个团队对框架的使用都有自己的一套模式。比如 React 团队可能约定所有状态提升到最近的公共祖先副作用统一用自定义 Hook 封装禁止在渲染函数里做数据转换。这些模式写成技能后AI 生成的组件会天然符合你的架构。我装了一个react-patterns技能里面记录了我们团队积累的十几个组件模式受控表单怎么封装、列表虚拟化怎么接、错误边界怎么放。效果是 AI 写出来的组件跟我自己写的几乎看不出差别。这类技能的价值随团队规模增长而增长——人越多约定越重要技能越值钱。3.3 测试生成类让 AI 写出真正有用的测试AI 写测试的通病是只测 happy path、断言写得敷衍、mock 用得过度。一个专门的测试技能可以纠正这些。我的test-standards技能里规定了每个函数至少一个边界用例、一个异常用例mock 只用于外部依赖内部模块不 mock断言必须验证具体值而非只验证被调用过。装了之后最明显的变化是覆盖率。之前 AI 生成的测试覆盖率大概 40%现在能到 75% 以上而且测试的可维护性好了很多。这里有个技巧在技能里放几个优秀测试的范例AI 会模仿范例的风格。范例比抽象规则有效得多。3.4 文档与注释类把写文档从负担变成自动动作这类技能处理的是函数注释、API 文档、README、变更日志。我装了一个doc-generator规定所有导出函数必须有 JSDoc包含param、returns、throws并且描述要写为什么而不只是是什么。比如不要写返回用户列表要写返回当前租户下所有活跃用户用于权限校验场景。这个技能还附带了一个脚本能从代码里提取所有导出符号检查哪些缺文档。AI 在提交前会跑一遍缺的就补上。这套组合下来我们项目的文档覆盖率从基本没有变成了核心模块全覆盖。3.5 调试与排错类让 AI 像老手一样定位问题这是我觉得最被低估的一类技能。大多数人的 AI 用法是报错了贴给它但一个调试技能可以让 AI 系统性地排查。我的debug-playbook技能规定了排查顺序先看错误类型和堆栈、再确认最近改动、然后二分定位、最后验证假设。每一步都有具体的检查清单。装了之后AI 不再是猜一个可能的原因而是会主动问你最近改了什么这个错误在什么条件下必现。它甚至会建议你加日志、写最小复现。这种结构化的排查方式比漫无目的地试错高效太多。3.6 提交与协作类规范 Git 工作流这类技能管的是提交信息格式、分支命名、PR 描述模板、Code Review 检查项。我装了一个git-workflow规定提交信息用 Conventional Commits 格式PR 描述必须包含改了什么为什么改怎么验证三部分。配合前面提到的校验脚本AI 在准备提交时会自动检查格式不合格就重写。这个技能对团队协作的价值特别大——它让每个人的提交都整齐划一回溯历史时清爽很多。3.7 领域知识类把业务规则喂给 AI这类技能是最定制的也是最难被替代的。它装的是你所在领域的专业知识金融系统的对账规则、电商的库存扣减逻辑、医疗系统的数据脱敏要求。这些知识通用 AI 不可能知道但又是你日常开发绕不开的。我做过一个电商项目装了一个inventory-rules技能把库存扣减的时序、超卖防护、回滚逻辑写得明明白白。之后 AI 写任何涉及库存的代码都会自动考虑这些边界省了我大量 review 时间。这类技能的投入产出比最高但需要你先把领域知识梳理清楚——梳理的过程本身就是有价值的。3.8 元技能类管理技能本身的技能最后一类有点特别它是用来管理其他技能的。比如一个skill-auditor规定当新增技能时检查是否与已有技能重叠定期审查技能的 description 是否仍然准确。我装这个是因为技能装多了之后会出现触发冲突——两个技能都觉得自己该管某件事AI 就懵了。这个元技能帮我定期清理冗余、合并重叠、修正描述。它不直接产出代码但让整个技能体系保持健康。如果你打算长期用 Skills这类技能迟早要装。4. 接入 Cursor 的完整流程与实测细节4.1 技能目录放哪里Cursor 对 Skills 的支持是通过项目内的特定目录实现的。通用做法是在项目根目录下建一个.cursor/skills/目录每个技能一个子文件夹。结构如下项目根目录/ ├── .cursor/ │ └── skills/ │ ├── database-migration/ │ │ └── SKILL.md │ ├── react-patterns/ │ │ ├── SKILL.md │ │ └── examples/ │ │ └── good-component.tsx │ └── test-standards/ │ └── SKILL.md注意技能文件夹名和SKILL.md里的name字段最好保持一致避免混淆。我一开始没注意这点结果排查问题时找半天。4.2 让 Cursor 识别并加载技能放好文件后Cursor 不会自动就认识它们。你需要在对话中明确告诉它去读技能目录或者在项目的规则文件里加一句技能位于.cursor/skills/请在相关任务中主动查阅。我实测下来最稳的做法是在项目规则里写清楚技能目录的位置和加载时机。有个细节Cursor 的技能加载是按需的它不会在每次对话都扫描所有技能。所以description的准确性至关重要。我建议你装完技能后用几个典型任务测试一下看 AI 有没有正确调用。如果没调用八成是描述写得不够精准。4.3 验证技能是否生效的三种方法怎么确认技能真的起作用了我用这三种方法第一种直接问 AI你现在有哪些可用的技能它会列出它识别到的技能清单。第二种给一个应该触发技能的任务观察它的输出是否符合技能里的规范。第三种在技能里临时加一句显眼的标记比如输出时请以【已应用XX技能】开头测试完再删掉。第三种方法最直接但记得测完清理。我有次忘了删结果正式环境里 AI 每条回复都带个奇怪的标记尴尬了好一阵。4.4 Cursor 特有的注意事项Cursor 的 Skills 支持和它的 Rules 系统是并存的两者容易打架。我的经验是Rules 管始终成立的约束Skills 管按需触发的流程。如果一条规则只在特定场景需要就把它挪进技能别放 Rules 里。另外Cursor 不同版本对技能的支持程度有差异。如果你发现技能死活不生效先确认版本再看官方文档有没有更新说明。我踩过一次坑某个版本对 frontmatter 的解析有 bugdescription里的中文会导致解析失败换成英文就好了。这种问题只能靠实测发现。5. 接入 Claude Code 的完整流程与差异点5.1 Claude Code 的技能加载机制Claude Code 对 Skills 的支持更原生一些。它会在几个固定位置查找技能项目级的.claude/skills/、用户级的~/.claude/skills/。项目级的优先级更高适合放团队共享的技能用户级的适合放你个人的通用技能。这个分层设计很实用。我把团队规范放项目级把我个人的写作偏好我常用的调试套路放用户级。这样换项目时个人技能跟着走团队技能随项目走。5.2 手动安装 GitHub 上的技能很多人问怎么装 GitHub 上别人分享的技能。流程其实很简单# 克隆技能仓库到临时目录 git clone https://github.com/某作者/某技能仓库.git /tmp/skill-repo # 找到技能文件夹复制到你的技能目录 cp -r /tmp/skill-repo/skills/某技能 ~/.claude/skills/ # 验证 SKILL.md 存在且格式正确 cat ~/.claude/skills/某技能/SKILL.md关键是复制前先看一眼SKILL.md的内容。我见过有人直接复制了一堆技能结果里面有些描述写得含糊导致 AI 频繁误触发。装第三方技能前务必读一遍它的描述和指令确认符合你的使用习惯。5.3 项目级与用户级技能的选择策略什么技能放项目级、什么放用户级我的划分标准是技能类型建议层级理由团队代码规范项目级随项目走团队成员共享框架使用模式项目级与项目技术栈绑定领域业务规则项目级项目特有知识个人写作偏好用户级跨项目通用通用调试套路用户级与具体项目无关元技能技能管理用户级管理所有项目的技能这个划分不是绝对的但遵循跟项目绑定的放项目级跟人绑定的放用户级这个原则基本不会错。5.4 Claude Code 与 Cursor 的技能互通好消息是SKILL.md的格式是通用的同一个技能文件理论上可以同时被 Cursor 和 Claude Code 使用。你只需要在两个工具各自的目录里放一份或者用软链接指向同一份。我用软链接的方式管理改一处两边都生效# 假设技能源文件在 ~/my-skills/ ln -s ~/my-skills/react-patterns ~/.claude/skills/react-patterns ln -s ~/my-skills/react-patterns 项目/.cursor/skills/react-patterns这样维护成本最低。但要注意两个工具对 frontmatter 字段的支持可能有细微差异跨工具使用前最好都测一遍。6. 写一个高质量 SKILL.md 的实战要点6.1 description 的写法决定技能生死前面反复强调描述的重要性这里给几个具体的写法对比差的描述好的描述帮助写代码当用户需要编写 React 函数组件时使用确保符合团队的组件模式和 Hook 使用规范测试相关当用户需要为现有函数生成单元测试时使用确保覆盖边界和异常场景数据库当用户需要编写或修改数据库迁移脚本时使用确保包含回滚和事务好描述的共同点说清楚什么场景when和保证什么what。AI 靠这两个信息判断该不该调用。6.2 指令要写成检查清单而非散文AI 对结构化指令的遵循度远高于散文。把技能正文写成检查清单每条都是可验证的动作。比如不要写注意代码质量要写[ ] 所有导出函数有 JSDoc[ ] 异步操作有错误处理[ ] 没有使用 any 类型[ ] 函数不超过 40 行这种清单式写法AI 会逐条对照执行效果比笼统描述好得多。6.3 用范例代替抽象规则如果一条规则很难用文字说清就放一个范例。AI 模仿范例的能力很强。我的react-patterns技能里放了三个标准组件的完整代码AI 生成的组件风格跟范例高度一致。范例要选那种典型且正确的别放边缘案例。6.4 技能的粒度控制一个技能管太多事会导致触发不精准管太少又会有太多技能要维护。我的经验是一个技能对应一类任务场景。比如写组件是一个技能写测试是另一个提交代码又是一个。别把前端开发规范做成一个大杂烩技能拆成组件、样式、状态管理几个独立技能触发更准。7. 那些只有实际用过才会知道的坑7.1 技能冲突两个技能抢着管同一件事这是最常见的坑。我装了一个代码规范技能和一个React 模式技能结果写 React 组件时两个都被触发给出的建议还互相矛盾。解决办法是明确边界代码规范管通用规则React 模式管框架特定模式在描述里写清楚各自的适用范围。如果冲突已经发生用元技能定期审查或者干脆合并成一个技能。我现在的做法是宁可少装几个也不要让技能之间打架。7.2 描述过宽导致的误触发有个技能我描述写的是当用户需要处理数据时使用结果 AI 在任何涉及数据的场景都调用它包括简单的数组排序。后来改成当用户需要编写数据清洗或转换管道时使用误触发就没了。描述里的场景词要具体别用处理相关涉及这种模糊词。7.3 技能文件里的路径问题如果技能附带脚本脚本里的路径要用相对路径或环境变量别写死绝对路径。我有个技能里的脚本写死了/Users/我的名字/...分享给同事后直接报错。用$(dirname $0)或者技能目录的相对路径才靠谱。7.4 更新技能后 AI 还在用旧版本技能文件改了但 AI 好像还在按旧的来。这通常是缓存问题。解决办法是重启对话或者在对话里明确说请重新读取技能目录。不同工具的缓存策略不一样遇到这种情况先重启试试。7.5 别把技能当银弹最后说个心态问题。Skills 能大幅提升 AI 的输出质量但它不能替代你的判断。AI 调用技能后给出的结果你还是要 review。我见过有人装了技能就完全放手结果 AI 按技能规范生成了代码但技能规范本身有漏洞问题照样出。技能是工具不是保险。8. 技能体系的长期维护思路技能装到一定数量后维护就成了问题。我的做法是每个月花半小时做一次技能体检看看哪些技能最近没被触发过可能描述有问题或场景已过时、哪些技能的建议跟当前实践脱节了、有没有新出现的重复场景需要合并。体检的具体操作翻一遍最近的对话记录统计每个技能被调用的次数。调用次数为零的技能要么删掉要么重写描述。调用频繁但效果不好的重点优化。这个习惯让我的技能库始终保持精简有效而不是越堆越多最后变成负担。另外技能是团队资产应该纳入版本管理。我把项目级技能放在 Git 仓库里跟代码一起 review、一起迭代。新人入职时克隆仓库就自动获得了全套技能上手速度快很多。这比写一堆文档让人去读要有效得多——技能是活的文档AI 会主动执行它。如果你刚开始接触 Skills我的建议是从一个技能开始就选你日常最烦、最重复的那个场景。把它写清楚用起来感受一下效果。有了正反馈再逐步扩展。别一上来就装几十个那样只会让你陷入技能冲突和误触发的泥潭。技能体系是长出来的不是堆出来的。 AI编程助手Skills实战指南：从SKILL.md机制到Cursor与Claude Code接入全流程
1. 为什么装技能这件事值得单独写一篇指南最近半年AI 编程助手的能力边界被一个叫 Skills 的机制彻底改写了。如果你还在用打开对话框、贴代码、等回答这种最原始的方式跟 Cursor 或 Claude Code 打交道那你大概只发挥了它们三成的功力。Skills 的本质是把一套可复用的工作流、领域知识和操作规范打包成 AI 能主动识别并调用的技能包。装上一个好技能相当于给你的 AI 助手请了一位专项教练——它不再只会泛泛而谈而是知道在什么场景下该用什么方法、该遵守什么规范、该输出什么格式。我最初接触 Skills 是因为一个很具体的痛点每次让 AI 帮我写数据库迁移脚本它总是忘记加事务回滚也总是忽略我们团队特定的命名约定。每次都要在提示词里重复交代一遍烦不胜烦。后来我把这些规范写进一个 SKILL.md 文件放进项目的技能目录问题一次性解决。从那以后我开始系统性地研究 Skills 的机制、生态和最佳实践陆续装了二十多个技能踩了不少坑也总结出一套自己的选型逻辑。这篇内容面向三类人一是刚听说 Skills 但不知道从哪下手的开发者二是已经装了技能但感觉没什么用的中级用户三是想自己写技能但不知道怎么写才规范的人。我会先讲清楚 Skills 的底层机制再给出 8 类经过实测值得装的技能清单然后手把手带你走完 Cursor 和 Claude Code 的接入全流程最后分享一些只有实际用过才会知道的坑和技巧。全文基于我自己的使用经验涉及具体操作的地方都会给出可复现的步骤。需要提前说明的是Skills 生态还在快速演进中不同工具对技能的支持程度和加载方式有差异。我会尽量区分通用机制和工具特定行为但你在实际操作时还是要以自己所用工具的官方文档为准。另外技能文件本身是纯文本的 Markdown这意味着你可以用任何编辑器写、用 Git 管理、在团队内共享这一点比很多封闭的插件体系要友好得多。2. Skills 到底是怎么工作的从 SKILL.md 到自动调用2.1 一个技能文件的最小结构很多人以为 Skills 是什么高深的技术其实拆开看非常简单。一个技能就是一个文件夹里面至少有一个SKILL.md文件。这个文件用 Markdown 写成顶部有一段 YAML 格式的元信息frontmatter下面是给 AI 看的正文指令。最小结构长这样--- name: database-migration description: 当用户需要编写或审查数据库迁移脚本时使用此技能确保包含事务回滚和命名规范 --- # 数据库迁移规范 ## 命名约定 - 迁移文件名格式YYYYMMDDHHMMSS_动词_对象.sql - 动词限定为create、alter、drop、add、remove ## 强制要求 1. 每个迁移脚本必须包含 up 和 down 两个方向 2. 所有 DDL 操作必须包裹在事务中 3. 涉及数据变更的必须提供回滚方案关键在description这一行。AI 在决定是否调用某个技能时主要依据就是这段描述。它相当于技能的广告语要精准告诉 AI什么场景下该用我。描述写得太宽泛比如帮助写代码AI 会在不相关的场景乱调用写得太窄又会在该用的时候想不起来。2.2 渐进式加载为什么技能不会撑爆上下文这是 Skills 设计里最精妙的一点。你装了几十个技能AI 并不会把每个技能的全文都塞进上下文窗口——那样 token 早就爆了。实际机制是分层的第一层AI 只加载所有技能的name和description这部分非常短几十个技能加起来也就几百 token。第二层当 AI 判断某个技能与当前任务相关时才把该技能的SKILL.md正文读进来。第三层如果技能文件夹里还有额外的参考文档、脚本、模板AI 会在需要时按需读取。这个机制叫渐进式披露progressive disclosure。理解它的意义在于你可以放心地装很多技能不用担心性能问题但同时description的质量直接决定了技能会不会被正确触发。我见过太多人技能写得很好但描述一句话带过结果 AI 从来不调用然后抱怨Skills 没用。2.3 技能、提示词、规则三者的边界新手最容易混淆的是技能和系统提示词、项目规则比如 Cursor 的 Rules、Claude Code 的 CLAUDE.md有什么区别我的理解是这样系统提示词全局生效定义 AI 的基本人格和行为准则你一般改不了或不该频繁改。项目规则针对某个项目生效定义这个项目的技术栈、代码风格、目录结构等始终成立的约束。技能按需触发定义在特定任务场景下才需要遵守的流程和知识。举个例子这个项目用 TypeScript 严格模式是项目规则因为它始终成立写 React 组件时要先检查是否已有同类组件可复用是技能因为它只在写组件的场景下才相关。把该做成技能的东西塞进项目规则会让规则文件臃肿且拖慢每次对话把该做成规则的东西写成技能又会导致 AI 在该遵守的时候想不起来。2.4 技能能调用脚本这才是真正的杀手锏纯文本指令只能约束 AI 的思考方式但技能文件夹里可以放可执行脚本。当技能被触发时AI 可以运行这些脚本把确定性的工作交给代码把需要判断的工作留给自己。比如一个生成 API 文档的技能可以附带一个解析代码注释的 Python 脚本AI 负责理解业务语义脚本负责提取结构化信息。这个能力让 Skills 从提示词模板升级成了轻量级自动化框架。我有个技能专门用来检查提交信息是否符合规范里面放了一个正则校验脚本AI 在准备提交前会调用它不通过就打回重写。这种AI 脚本的组合比纯靠 AI 判断可靠得多。3. 八类实测值得装的技能以及各自的适用边界市面上的技能越来越多但真正高频有用的其实就那么几类。下面这八类是我自己装了之后持续在用、并且推荐给团队成员的。每一类我都会说清楚它解决什么问题、什么场景下值得装、以及我踩过的坑。3.1 代码规范类把团队约定变成 AI 的肌肉记忆这类技能解决的是AI 写的代码风格跟团队不一致的问题。典型内容包括命名约定、目录结构规范、错误处理模式、日志格式、注释风格。我装的那个叫team-conventions里面把我们前端团队的规则写得清清楚楚组件文件用 PascalCase、工具函数用 camelCase、所有异步操作必须 try-catch 并上报错误、禁止使用any。装之前AI 生成的代码我平均要改 5 处才能合入装之后基本一次过。这里的关键是规则要具体到可执行。写代码要清晰没用写函数超过 40 行必须拆分才有用。我建议你把团队 Code Review 里最常打回的几条意见整理出来那就是这个技能的核心内容。注意不要把 ESLint 能管的规则写进技能。技能管的是机器难判断、需要语义理解的规范比如这个抽象是否过度这个命名是否准确表达意图。格式问题交给格式化工具。3.2 框架专项类React、Vue、后端框架的深度知识通用 AI 对框架的理解往往停留在能用层面但每个团队对框架的使用都有自己的一套模式。比如 React 团队可能约定所有状态提升到最近的公共祖先副作用统一用自定义 Hook 封装禁止在渲染函数里做数据转换。这些模式写成技能后AI 生成的组件会天然符合你的架构。我装了一个react-patterns技能里面记录了我们团队积累的十几个组件模式受控表单怎么封装、列表虚拟化怎么接、错误边界怎么放。效果是 AI 写出来的组件跟我自己写的几乎看不出差别。这类技能的价值随团队规模增长而增长——人越多约定越重要技能越值钱。3.3 测试生成类让 AI 写出真正有用的测试AI 写测试的通病是只测 happy path、断言写得敷衍、mock 用得过度。一个专门的测试技能可以纠正这些。我的test-standards技能里规定了每个函数至少一个边界用例、一个异常用例mock 只用于外部依赖内部模块不 mock断言必须验证具体值而非只验证被调用过。装了之后最明显的变化是覆盖率。之前 AI 生成的测试覆盖率大概 40%现在能到 75% 以上而且测试的可维护性好了很多。这里有个技巧在技能里放几个优秀测试的范例AI 会模仿范例的风格。范例比抽象规则有效得多。3.4 文档与注释类把写文档从负担变成自动动作这类技能处理的是函数注释、API 文档、README、变更日志。我装了一个doc-generator规定所有导出函数必须有 JSDoc包含param、returns、throws并且描述要写为什么而不只是是什么。比如不要写返回用户列表要写返回当前租户下所有活跃用户用于权限校验场景。这个技能还附带了一个脚本能从代码里提取所有导出符号检查哪些缺文档。AI 在提交前会跑一遍缺的就补上。这套组合下来我们项目的文档覆盖率从基本没有变成了核心模块全覆盖。3.5 调试与排错类让 AI 像老手一样定位问题这是我觉得最被低估的一类技能。大多数人的 AI 用法是报错了贴给它但一个调试技能可以让 AI 系统性地排查。我的debug-playbook技能规定了排查顺序先看错误类型和堆栈、再确认最近改动、然后二分定位、最后验证假设。每一步都有具体的检查清单。装了之后AI 不再是猜一个可能的原因而是会主动问你最近改了什么这个错误在什么条件下必现。它甚至会建议你加日志、写最小复现。这种结构化的排查方式比漫无目的地试错高效太多。3.6 提交与协作类规范 Git 工作流这类技能管的是提交信息格式、分支命名、PR 描述模板、Code Review 检查项。我装了一个git-workflow规定提交信息用 Conventional Commits 格式PR 描述必须包含改了什么为什么改怎么验证三部分。配合前面提到的校验脚本AI 在准备提交时会自动检查格式不合格就重写。这个技能对团队协作的价值特别大——它让每个人的提交都整齐划一回溯历史时清爽很多。3.7 领域知识类把业务规则喂给 AI这类技能是最定制的也是最难被替代的。它装的是你所在领域的专业知识金融系统的对账规则、电商的库存扣减逻辑、医疗系统的数据脱敏要求。这些知识通用 AI 不可能知道但又是你日常开发绕不开的。我做过一个电商项目装了一个inventory-rules技能把库存扣减的时序、超卖防护、回滚逻辑写得明明白白。之后 AI 写任何涉及库存的代码都会自动考虑这些边界省了我大量 review 时间。这类技能的投入产出比最高但需要你先把领域知识梳理清楚——梳理的过程本身就是有价值的。3.8 元技能类管理技能本身的技能最后一类有点特别它是用来管理其他技能的。比如一个skill-auditor规定当新增技能时检查是否与已有技能重叠定期审查技能的 description 是否仍然准确。我装这个是因为技能装多了之后会出现触发冲突——两个技能都觉得自己该管某件事AI 就懵了。这个元技能帮我定期清理冗余、合并重叠、修正描述。它不直接产出代码但让整个技能体系保持健康。如果你打算长期用 Skills这类技能迟早要装。4. 接入 Cursor 的完整流程与实测细节4.1 技能目录放哪里Cursor 对 Skills 的支持是通过项目内的特定目录实现的。通用做法是在项目根目录下建一个.cursor/skills/目录每个技能一个子文件夹。结构如下项目根目录/ ├── .cursor/ │ └── skills/ │ ├── database-migration/ │ │ └── SKILL.md │ ├── react-patterns/ │ │ ├── SKILL.md │ │ └── examples/ │ │ └── good-component.tsx │ └── test-standards/ │ └── SKILL.md注意技能文件夹名和SKILL.md里的name字段最好保持一致避免混淆。我一开始没注意这点结果排查问题时找半天。4.2 让 Cursor 识别并加载技能放好文件后Cursor 不会自动就认识它们。你需要在对话中明确告诉它去读技能目录或者在项目的规则文件里加一句技能位于.cursor/skills/请在相关任务中主动查阅。我实测下来最稳的做法是在项目规则里写清楚技能目录的位置和加载时机。有个细节Cursor 的技能加载是按需的它不会在每次对话都扫描所有技能。所以description的准确性至关重要。我建议你装完技能后用几个典型任务测试一下看 AI 有没有正确调用。如果没调用八成是描述写得不够精准。4.3 验证技能是否生效的三种方法怎么确认技能真的起作用了我用这三种方法第一种直接问 AI你现在有哪些可用的技能它会列出它识别到的技能清单。第二种给一个应该触发技能的任务观察它的输出是否符合技能里的规范。第三种在技能里临时加一句显眼的标记比如输出时请以【已应用XX技能】开头测试完再删掉。第三种方法最直接但记得测完清理。我有次忘了删结果正式环境里 AI 每条回复都带个奇怪的标记尴尬了好一阵。4.4 Cursor 特有的注意事项Cursor 的 Skills 支持和它的 Rules 系统是并存的两者容易打架。我的经验是Rules 管始终成立的约束Skills 管按需触发的流程。如果一条规则只在特定场景需要就把它挪进技能别放 Rules 里。另外Cursor 不同版本对技能的支持程度有差异。如果你发现技能死活不生效先确认版本再看官方文档有没有更新说明。我踩过一次坑某个版本对 frontmatter 的解析有 bugdescription里的中文会导致解析失败换成英文就好了。这种问题只能靠实测发现。5. 接入 Claude Code 的完整流程与差异点5.1 Claude Code 的技能加载机制Claude Code 对 Skills 的支持更原生一些。它会在几个固定位置查找技能项目级的.claude/skills/、用户级的~/.claude/skills/。项目级的优先级更高适合放团队共享的技能用户级的适合放你个人的通用技能。这个分层设计很实用。我把团队规范放项目级把我个人的写作偏好我常用的调试套路放用户级。这样换项目时个人技能跟着走团队技能随项目走。5.2 手动安装 GitHub 上的技能很多人问怎么装 GitHub 上别人分享的技能。流程其实很简单# 克隆技能仓库到临时目录 git clone https://github.com/某作者/某技能仓库.git /tmp/skill-repo # 找到技能文件夹复制到你的技能目录 cp -r /tmp/skill-repo/skills/某技能 ~/.claude/skills/ # 验证 SKILL.md 存在且格式正确 cat ~/.claude/skills/某技能/SKILL.md关键是复制前先看一眼SKILL.md的内容。我见过有人直接复制了一堆技能结果里面有些描述写得含糊导致 AI 频繁误触发。装第三方技能前务必读一遍它的描述和指令确认符合你的使用习惯。5.3 项目级与用户级技能的选择策略什么技能放项目级、什么放用户级我的划分标准是技能类型建议层级理由团队代码规范项目级随项目走团队成员共享框架使用模式项目级与项目技术栈绑定领域业务规则项目级项目特有知识个人写作偏好用户级跨项目通用通用调试套路用户级与具体项目无关元技能技能管理用户级管理所有项目的技能这个划分不是绝对的但遵循跟项目绑定的放项目级跟人绑定的放用户级这个原则基本不会错。5.4 Claude Code 与 Cursor 的技能互通好消息是SKILL.md的格式是通用的同一个技能文件理论上可以同时被 Cursor 和 Claude Code 使用。你只需要在两个工具各自的目录里放一份或者用软链接指向同一份。我用软链接的方式管理改一处两边都生效# 假设技能源文件在 ~/my-skills/ ln -s ~/my-skills/react-patterns ~/.claude/skills/react-patterns ln -s ~/my-skills/react-patterns 项目/.cursor/skills/react-patterns这样维护成本最低。但要注意两个工具对 frontmatter 字段的支持可能有细微差异跨工具使用前最好都测一遍。6. 写一个高质量 SKILL.md 的实战要点6.1 description 的写法决定技能生死前面反复强调描述的重要性这里给几个具体的写法对比差的描述好的描述帮助写代码当用户需要编写 React 函数组件时使用确保符合团队的组件模式和 Hook 使用规范测试相关当用户需要为现有函数生成单元测试时使用确保覆盖边界和异常场景数据库当用户需要编写或修改数据库迁移脚本时使用确保包含回滚和事务好描述的共同点说清楚什么场景when和保证什么what。AI 靠这两个信息判断该不该调用。6.2 指令要写成检查清单而非散文AI 对结构化指令的遵循度远高于散文。把技能正文写成检查清单每条都是可验证的动作。比如不要写注意代码质量要写[ ] 所有导出函数有 JSDoc[ ] 异步操作有错误处理[ ] 没有使用 any 类型[ ] 函数不超过 40 行这种清单式写法AI 会逐条对照执行效果比笼统描述好得多。6.3 用范例代替抽象规则如果一条规则很难用文字说清就放一个范例。AI 模仿范例的能力很强。我的react-patterns技能里放了三个标准组件的完整代码AI 生成的组件风格跟范例高度一致。范例要选那种典型且正确的别放边缘案例。6.4 技能的粒度控制一个技能管太多事会导致触发不精准管太少又会有太多技能要维护。我的经验是一个技能对应一类任务场景。比如写组件是一个技能写测试是另一个提交代码又是一个。别把前端开发规范做成一个大杂烩技能拆成组件、样式、状态管理几个独立技能触发更准。7. 那些只有实际用过才会知道的坑7.1 技能冲突两个技能抢着管同一件事这是最常见的坑。我装了一个代码规范技能和一个React 模式技能结果写 React 组件时两个都被触发给出的建议还互相矛盾。解决办法是明确边界代码规范管通用规则React 模式管框架特定模式在描述里写清楚各自的适用范围。如果冲突已经发生用元技能定期审查或者干脆合并成一个技能。我现在的做法是宁可少装几个也不要让技能之间打架。7.2 描述过宽导致的误触发有个技能我描述写的是当用户需要处理数据时使用结果 AI 在任何涉及数据的场景都调用它包括简单的数组排序。后来改成当用户需要编写数据清洗或转换管道时使用误触发就没了。描述里的场景词要具体别用处理相关涉及这种模糊词。7.3 技能文件里的路径问题如果技能附带脚本脚本里的路径要用相对路径或环境变量别写死绝对路径。我有个技能里的脚本写死了/Users/我的名字/...分享给同事后直接报错。用$(dirname $0)或者技能目录的相对路径才靠谱。7.4 更新技能后 AI 还在用旧版本技能文件改了但 AI 好像还在按旧的来。这通常是缓存问题。解决办法是重启对话或者在对话里明确说请重新读取技能目录。不同工具的缓存策略不一样遇到这种情况先重启试试。7.5 别把技能当银弹最后说个心态问题。Skills 能大幅提升 AI 的输出质量但它不能替代你的判断。AI 调用技能后给出的结果你还是要 review。我见过有人装了技能就完全放手结果 AI 按技能规范生成了代码但技能规范本身有漏洞问题照样出。技能是工具不是保险。8. 技能体系的长期维护思路技能装到一定数量后维护就成了问题。我的做法是每个月花半小时做一次技能体检看看哪些技能最近没被触发过可能描述有问题或场景已过时、哪些技能的建议跟当前实践脱节了、有没有新出现的重复场景需要合并。体检的具体操作翻一遍最近的对话记录统计每个技能被调用的次数。调用次数为零的技能要么删掉要么重写描述。调用频繁但效果不好的重点优化。这个习惯让我的技能库始终保持精简有效而不是越堆越多最后变成负担。另外技能是团队资产应该纳入版本管理。我把项目级技能放在 Git 仓库里跟代码一起 review、一起迭代。新人入职时克隆仓库就自动获得了全套技能上手速度快很多。这比写一堆文档让人去读要有效得多——技能是活的文档AI 会主动执行它。如果你刚开始接触 Skills我的建议是从一个技能开始就选你日常最烦、最重复的那个场景。把它写清楚用起来感受一下效果。有了正反馈再逐步扩展。别一上来就装几十个那样只会让你陷入技能冲突和误触发的泥潭。技能体系是长出来的不是堆出来的。