1. 为什么“技能包”正在成为开发者的新基建第一次接触 Skills 这个概念是在一个前端群里看到有人发截图他在 Cursor 里敲了一行/commit编辑器自动读了一遍暂存区的 diff生成了一条符合团队规范的提交信息还顺手把关联的 issue 编号补上了。当时我以为是什么插件追问之后才知道这就是一个放在项目目录里的SKILL.md文件在起作用。Skills 说白了就是把“你反复教 AI 做同一件事”的过程固化成一个可复用的说明书。它不是什么高深的技术本质就是一份结构化的 Markdown 文档告诉 AI 在什么场景下该做什么、按什么顺序做、输出成什么格式。但就是这么个朴素的东西解决了一个非常真实的痛点每次开新会话你都得重新解释一遍项目规范、代码风格、目录结构AI 还经常记岔。这套机制最早在 Claude Code 里成型后来 Cursor、VS Code 配合各类 AI 插件也陆续支持了类似的加载逻辑。现在社区里管它叫 agent skills、codex skills、superpower skills名字五花八门但内核是一致的用文件的形式给 AI 注入可持久化的领域知识和工作流。这篇文章适合三类人看。第一类是刚上手 Cursor 或 Claude Code、还在摸索怎么让 AI 听话的新手第二类是已经用了一阵子、但每次都要重复写提示词、想提效的中级用户第三类是想给团队做 AI 工作流标准化、需要一套可落地规范的负责人。我会把 8 类值得装的技能拆开讲清楚再把接入 Cursor 和 Claude Code 的全流程走一遍包括那些文档里不会写的坑。2. Skills 到底是什么从 SKILL.md 的结构说起2.1 一份 SKILL.md 的最小构成很多人第一次看到SKILL.md会懵不知道里面该写什么。其实它的结构非常自由没有强制的 schema但社区沉淀下来一套约定俗成的写法基本包含这么几块元信息区技能名称、触发条件、适用场景。这部分决定了 AI 什么时候会主动加载这个技能。上下文说明这个技能解决什么问题涉及哪些技术栈有哪些前置假设。执行步骤按顺序列出 AI 应该做的事越具体越好。输出规范最终产物长什么样格式、命名、存放位置。边界与禁忌什么情况下不要用这个技能哪些操作绝对不能做。我见过有人把 SKILL.md 写成几百行的巨型文档也见过只写二十行就很好用的。关键不在于长度而在于触发条件是否清晰和步骤是否可执行。一份好的技能文档读起来应该像给一个新同事写的操作手册而不是像产品需求文档。2.2 触发机制AI 是怎么“想起”某个技能的这是最容易被误解的地方。很多人以为装了技能AI 就会自动用。实际上技能的加载依赖两个条件一是技能文件放在 AI 能扫描到的目录里二是当前对话的上下文命中了技能的触发描述。以 Claude Code 为例它会在项目根目录和用户配置目录下扫描技能文件把每个技能的元信息读进上下文。当你的提问或当前操作匹配到某个技能的触发词时AI 才会把完整的技能内容加载进来。所以触发描述写得准不准直接决定了技能会不会被用上。我踩过的一个坑是早期写了个“生成单元测试”的技能触发条件写的是“当需要测试时”。结果 AI 几乎从不主动加载它因为“需要测试”这个描述太模糊了。后来改成“当用户提到 test、spec、覆盖率、断言或修改了 src 目录下的 .ts 文件时”命中率立刻上来了。提示触发条件尽量用具体的动词和名词组合避免“需要”“相关”“适当”这类模糊词。宁可写得多一点也不要让 AI 猜。2.3 Skills 和传统提示词模板的区别有人会问这不就是提示词模板吗我存个 txt 不也一样区别在于三点。第一是加载时机。提示词模板需要你手动粘贴技能是 AI 根据上下文自动判断是否加载。第二是作用域。技能可以绑定到项目、用户、甚至某个子目录不同项目用不同技能互不干扰。第三是可组合性。多个技能可以叠加使用比如一个负责代码风格一个负责提交规范一个负责文档生成它们在同一轮对话里协同工作。这三点加起来让 Skills 从“一次性工具”变成了“可积累的资产”。你写得越多AI 越懂你的项目边际收益是递增的。3. 8 类值得装的技能按优先级排给你3.1 代码规范类让 AI 写出符合团队风格的代码这是最刚需的一类。每个团队都有自己的命名习惯、目录约定、错误处理方式但 AI 默认输出的是“通用最佳实践”往往和你的项目格格不入。这类技能要写清楚变量和函数的命名规则驼峰还是下划线、文件组织方式、注释密度、错误处理模式、日志格式。我建议直接把你团队 code review 里最常提的意见整理进去那些就是 AI 最容易犯的错。举个例子我们团队规定所有异步函数必须显式处理错误不允许裸await。这条写进技能后AI 生成的代码里再也没出现过未捕获的 Promise。这种收益是立竿见影的。3.2 提交与版本管理类告别手写 commit message前面提到的/commit就是这类。它要做的事很明确读暂存区 diff按约定式提交规范生成 message关联 issue 编号必要时拆分提交。写这类技能的关键是把团队的提交规范写死。比如我们用的是type(scope): subject格式type 限定在 feat、fix、refactor、docs、test、chore 六种scope 必须是模块名。这些约束写进技能后AI 生成的提交信息基本不用改。进阶玩法是让技能自动判断该不该拆分提交。比如检测到 diff 里同时有功能改动和格式化改动就提示你先分开提交。这个逻辑用自然语言描述清楚AI 是能执行的。3.3 测试生成类从“写测试好烦”到“顺手就写了”测试是很多人抵触的环节正好适合交给 AI。但直接让 AI 写测试它经常写出断言很弱的测试或者 mock 得乱七八糟。这类技能要规定测试文件的命名和存放位置、使用的测试框架和断言库、mock 的策略哪些该 mock哪些用真实依赖、覆盖率要求、边界用例的枚举方式。我还会要求 AI 在生成测试后自己跑一遍并报告结果跑不通就自己修。实测下来把“必须覆盖空值、边界值、异常路径”这条写进技能后测试质量提升非常明显。以前 AI 写的测试只能覆盖 happy path现在会主动考虑各种边界情况。3.4 文档与注释类让代码自己会说话这类技能负责生成 README、API 文档、函数注释、变更日志。核心是统一格式和控制粒度。格式上我们规定 README 必须包含项目简介、快速开始、目录结构、核心模块说明、常见问题五个部分。注释上只要求对导出函数和复杂逻辑写注释内部简单函数不写避免注释噪音。有个细节值得注意让 AI 写文档时一定要给它足够的上下文否则它会编造不存在的功能。我的做法是让技能先扫描相关源文件再基于实际代码生成文档而不是凭标题瞎写。3.5 重构与代码审查类把 review 意见变成自动化检查这类技能模拟一个严格的 reviewer检查代码里的坏味道重复代码、过长函数、深层嵌套、魔法数字、未使用的变量。写这类技能时我建议把检查项分级error 级别的问题必须修warning 级别的提示但不强制info 级别的仅记录。这样 AI 输出时会有优先级不会一股脑抛出一堆问题让人无从下手。实际用下来这类技能最适合在提交前跑一遍。相当于有个不知疲倦的同事帮你做 pre-review能挡掉大部分低级问题。3.6 项目脚手架类新项目不再从零开始每次开新项目都要配 tsconfig、eslint、prettier、目录结构、CI 配置重复劳动。这类技能把这些固化下来一句话就能生成整套骨架。关键是把技术栈组合和配置细节写清楚。比如“React TypeScript Vite Tailwind”这套组合对应的依赖版本、配置文件内容、目录结构都写进技能。AI 生成后直接能用省掉大量查文档的时间。我还会在技能里加上“生成后自动安装依赖并跑一次构建”的步骤确保脚手架是能跑通的而不是生成一堆跑不起来的文件。3.7 调试与排查类把排错经验沉淀下来这类技能最有价值因为它沉淀的是你踩过的坑。比如“遇到 CORS 错误先检查什么”“构建失败时按什么顺序排查”“内存泄漏的常见原因有哪些”。写这类技能时用“症状 → 可能原因 → 排查步骤 → 解决方案”的结构最有效。AI 拿到这个结构后能根据你描述的症状快速定位到对应的排查路径。我把自己过去一年遇到的典型 bug 都整理进了这个技能现在遇到类似问题AI 能直接给出排查方向省掉大量搜索时间。3.8 领域知识类把业务规则喂给 AI最后一类是针对特定业务领域的。比如电商项目要懂订单状态机、支付流程、库存扣减规则金融项目要懂对账逻辑、风控规则。这类技能的价值在于减少 AI 的业务理解成本。新来的同事要花一周才能搞懂的业务规则写进技能后 AI 立刻就能用。而且业务规则变更时改技能文件比改代码注释更集中、更好维护。4. 接入 Cursor 的全流程与实操细节4.1 环境准备与目录约定Cursor 对 Skills 的支持是通过项目根目录下的特定文件夹实现的。常见做法是在项目根建一个.cursor/skills/目录每个技能一个子文件夹里面放SKILL.md。目录结构大概长这样项目根/ ├── .cursor/ │ └── skills/ │ ├── commit/ │ │ └── SKILL.md │ ├── test-gen/ │ │ └── SKILL.md │ └── code-style/ │ └── SKILL.md ├── src/ └── package.json为什么用子文件夹而不是平铺因为一个技能可能附带辅助文件比如模板、示例、配置片段。子文件夹结构更清晰也方便单独启用或禁用某个技能。4.2 编写第一个技能并验证加载拿提交规范技能举例SKILL.md内容大致如下--- name: commit description: 当用户要求提交代码、生成 commit message、或提到 git commit 时触发 --- ## 目标 根据暂存区的改动生成符合团队规范的提交信息。 ## 步骤 1. 执行 git diff --staged 查看暂存内容 2. 分析改动类型判断是 feat/fix/refactor/docs/test/chore 3. 提取改动涉及的模块作为 scope 4. 按 type(scope): subject 格式生成 message 5. subject 用中文不超过 50 字动词开头 ## 输出 仅输出 commit message 本身不要额外解释。写完后在 Cursor 里打开对话输入“帮我提交一下”观察 AI 是否加载了这个技能。如果没反应检查两点一是文件路径是否正确二是 description 里的触发词是否命中。4.3 Cursor 中文设置与常见配置很多人关心 Cursor 中文怎么设置。在设置里搜索 “language”把显示语言改成简体中文即可。但要注意界面语言和 AI 输出语言是两回事。界面改成中文后AI 默认还是用英文回复需要在技能或对话里明确要求用中文。我的做法是在全局技能里加一条“所有输出使用简体中文”这样不用每次单独交代。另外Cursor 的提示词泄露问题社区讨论很多我的建议是不要把敏感信息写进技能文件技能里只放工作流和规范不放密钥、内部地址这类内容。4.4 技能组合与优先级处理当多个技能同时命中时Cursor 会按加载顺序叠加。这里有个坑如果两个技能对同一件事有冲突的规定AI 可能无所适从。解决办法是明确优先级。我会在技能里写清楚“本技能优先级高于通用规范”或者在全局配置里指定加载顺序。另一个做法是把通用规范抽成一个基础技能其他技能继承它避免重复定义。5. 接入 Claude Code 的全流程与实操细节5.1 安装与初始化Claude Code 的安装方式取决于你的系统。在 macOS 和 Linux 上通常通过包管理器安装Windows 用户建议在 WSL 环境下操作体验更顺畅。安装完成后在项目根目录执行初始化命令它会引导你创建配置文件和技能目录。初始化时会问你几个问题项目类型、主要语言、是否启用默认技能。我的建议是先启用默认技能跑通流程后再自定义。默认技能里已经包含了提交规范、代码审查这些常用功能能帮你快速建立体感。5.2 技能目录结构与加载顺序Claude Code 扫描技能的位置比 Cursor 多一些包括项目级、用户级、全局级三个层次。加载顺序是项目级优先于用户级用户级优先于全局级。这个设计很合理项目特有的规范覆盖通用规范。目录结构上Claude Code 用的是.claude/skills/和 Cursor 的.cursor/skills/类似。如果你同时用两个工具可以把技能文件放在一个共享目录然后用软链接分别指向避免维护两份。5.3 在 VS Code 中配置 Claude Code很多人习惯在 VS Code 里工作希望把 Claude Code 集成进去。做法是安装对应的扩展然后在设置里配置 Claude Code 的可执行文件路径。配置完成后可以在 VS Code 的命令面板里直接调用 Claude Code 的功能。这里有个细节VS Code 的工作区设置和用户设置要分清。技能相关的配置建议放在工作区设置里这样不同项目可以用不同的技能组合不会互相干扰。5.4 技能调试与日志查看技能不生效时第一步是看日志。Claude Code 会记录每次对话加载了哪些技能、命中了哪些触发条件。通过日志能快速定位问题是技能没被扫描到还是触发了但内容没加载还是加载了但 AI 没执行。我常用的排查顺序是先确认文件路径和命名再看触发描述是否命中最后看技能内容是否有歧义。大部分问题出在第二步触发描述写得太窄或太宽都会导致命中率低。6. 常见问题与排查技巧实录6.1 技能不生效的六种典型原因症状可能原因排查方法AI 完全不提技能文件路径错误检查目录名和文件名拼写偶尔生效偶尔不生效触发描述太窄补充同义词和场景词加载了但不执行步骤描述模糊把步骤改成可执行的动作多个技能冲突优先级未定义在技能里声明优先级输出格式不对输出规范不具体给出格式示例技能内容被截断文件过长拆分或精简内容这张表是我踩坑踩出来的基本覆盖了九成以上的问题。遇到技能不生效按这个顺序排查通常几分钟就能定位。6.2 触发词设计的经验法则触发词设计是技能能否被用上的关键。我的经验是宁可多写不可少写。把用户可能用的各种说法都列进去包括同义词、缩写、中英文混用。比如提交技能触发词可以写“提交、commit、git commit、生成提交信息、写 commit message、暂存区”。这样无论用户怎么说都能命中。代价是技能可能被过度触发但过度触发比不触发好因为不触发等于技能白写。另一个技巧是用文件类型和操作作为触发条件。比如“当修改了 .test.ts 文件时”或“当执行了 git add 后”这类条件比纯文本匹配更精准。6.3 技能维护与版本管理技能文件应该和代码一起进版本库这样团队成员共享同一套规范。但要注意技能里的内容可能涉及内部约定公开仓库要谨慎。我的做法是通用技能放公开仓库项目特有技能放私有仓库敏感信息用环境变量注入不写死在技能里。技能变更时走正常的 code review 流程确保改动经过审核。6.4 性能与上下文占用的权衡技能不是越多越好。每个技能都会占用上下文窗口技能太多会导致 AI 注意力分散反而降低效果。我的建议是常驻技能控制在 5 个以内其他技能按需加载。判断标准很简单如果一个技能一周都用不上一次就把它从常驻列表里移出去需要时再手动加载。这样能保证 AI 的注意力集中在最常用的规范上。7. 我个人的实操心得与后续扩展方向用了一年多 Skills最大的体会是技能的质量取决于你对自身工作流的理解深度。如果你自己都说不清楚“为什么这么做”写出来的技能也是模糊的AI 执行起来自然打折扣。另一个心得是从小处着手。不要一上来就写一个包罗万象的巨型技能先从“提交规范”这种边界清晰的小技能开始跑通了再逐步扩展。每加一个技能观察一周确认它真的提升了效率再固化下来。后续可以扩展的方向有几个。一是技能的市场化共享社区里已经有人在分享常用技能包可以直接拿来改。二是技能的自动化测试给技能写测试用例确保改动不会破坏原有行为。三是跨工具的技能同步让同一套技能在 Cursor、Claude Code、VS Code 里通用减少重复维护。最后分享一个小技巧写技能时把自己想象成在给一个聪明但完全不了解你项目的新人写交接文档。这个心态能帮你写出更清晰、更可执行的技能。那些你觉得“这还用说”的细节恰恰是 AI 最需要知道的。