1. 为什么 Skills 值得每个开发者认真对待第一次接触 Skills 这个概念是在给一个中型前端团队做工程效率优化的时候。当时团队里每个人都在用 Cursor 和 Claude Code 写代码但效率差距大得离谱——有人一天能推三个功能分支有人光调提示词就耗掉半天。问题不在于模型能力而在于每个人都在重复造轮子同样的代码审查逻辑、同样的组件生成规范、同样的提交信息格式每个人都要重新写一遍提示词而且写得参差不齐。Skills 解决的正是这个问题。你可以把它理解成给 AI 编程助手准备的“技能包”——一个SKILL.md文件加上若干辅助资源就能把一套标准化的操作流程固化下来让 Cursor、Claude Code、VS Code 里的 AI 助手在特定场景下自动调用。它不是什么高深的技术本质上就是结构化的提示词工程 可复用的工作流封装。这篇文章适合三类人看第一类是完全没接触过 Skills、但已经在用 Cursor 或 Claude Code 的开发者想搞清楚这东西到底能帮自己省多少事第二类是已经听说过SKILL.md但不知道怎么下手写、怎么接入自己常用编辑器的第三类是团队技术负责人想给团队统一一套 AI 辅助开发规范但不知道从哪切入的。我会从实际使用角度出发把 8 类真正值得装的 Skills 拆开讲清楚再把接入 Cursor、Claude Code、VS Code 的完整流程走一遍包括我踩过的坑和实测有效的配置。先给一个最直观的认知一个写得好的 Skill能让 AI 助手在特定任务上的输出质量从“勉强能用”提升到“基本不用改”。这个提升幅度比换一个更强的模型还要明显。因为模型能力是通用的而 Skill 是把通用能力约束到你的项目规范里。2. Skills 到底是什么从 SKILL.md 的结构说起2.1 一个 Skill 的最小构成很多人第一次看到SKILL.md会以为是什么新出的配置文件格式其实它就是 Markdown。一个 Skill 的核心就是一个目录里面至少包含一个SKILL.md文件这个文件用 YAML frontmatter 声明元信息用 Markdown 正文描述技能的具体内容。最小可用的SKILL.md长这样--- name: react-component-generator description: 按照团队规范生成 React 函数组件包含 TypeScript 类型定义和样式模块 --- # React 组件生成规范 当用户要求创建新的 React 组件时按照以下规范执行 1. 使用函数组件 TypeScript不使用 class 组件 2. 组件文件命名为 PascalCase如 UserProfile.tsx 3. 样式使用 CSS Modules文件名与组件同名 4. Props 接口命名为 [组件名]Props必须导出 5. 默认导出组件本身命名导出 Props 接口就这么简单。name是技能标识description是给 AI 看的触发条件——当用户的请求匹配到这个描述时AI 就会加载这个 Skill 的完整内容并按照里面的规范执行。2.2 Skills 和普通提示词的本质区别你可能会问这不就是把提示词写进文件里吗和我直接在对话里粘贴一段规范有什么区别区别在三个地方。第一是持久化提示词粘贴是一次性的关掉对话就没了Skill 是存在项目目录或全局配置里的每次相关任务都会自动生效。第二是结构化Skill 可以包含多个文件——除了SKILL.md还可以放模板文件、示例代码、参考文档AI 在需要时会读取这些辅助资源。第三是可组合一个项目可以装多个 SkillAI 会根据任务类型自动选择加载哪个不需要你手动切换。我实测下来最明显的感受是以前每次让 AI 写组件都要先粘贴一遍规范现在装好 Skill 之后直接说“帮我写个用户卡片组件”出来的代码直接符合团队规范连 import 顺序都是对的。2.3 为什么现在值得投入时间学 SkillsCursor 和 Claude Code 这类工具的能力边界很大程度上取决于你给它的上下文质量。Skills 是目前把项目上下文标准化注入 AI 工作流的最轻量方案。它不需要你搭建 RAG 系统不需要微调模型不需要写复杂的 Agent 编排逻辑就是一个 Markdown 文件的事。而且这个生态正在快速成型。GitHub 上已经有不少开源的 Skills 集合覆盖前端开发、代码审查、文档生成、测试编写等场景。你不需要从零写每一个 Skill很多通用场景直接拿现成的改改就能用。这也是为什么我觉得现在是把 Skills 纳入日常开发流程的好时机——投入产出比很高学习曲线很平。3. 8 类真正值得装的 Skills 详解3.1 代码规范类让 AI 写出符合团队风格的代码这是最基础也最刚需的一类。每个团队都有自己的代码风格——缩进用几个空格、组件怎么组织、命名用什么约定、注释写不写、写多少。这些规范写在文档里没人看但写成 Skill 之后 AI 会严格执行。我给自己团队写的第一个 Skill 就是代码规范类的核心内容包括文件命名和目录结构约定导入顺序规则第三方库、内部模块、相对路径、样式文件组件内部结构顺序类型定义、常量、组件主体、样式错误处理和日志规范注释密度要求这类 Skill 的关键在于具体。不要写“遵循良好的代码风格”这种废话要写“函数参数超过 3 个时必须使用对象参数”这种可执行的规则。AI 对模糊描述的执行力很差但对具体规则执行得很到位。注意代码规范类 Skill 不要写太长。超过 200 行的规范文件AI 加载后反而容易遗漏细节。建议拆成多个小 Skill比如“组件规范”“工具函数规范”“API 调用规范”分开写。3.2 项目脚手架类新模块创建一键完成每次新建一个页面或模块都要手动创建一堆文件、配置路由、写样板代码——这种事最适合交给 Skill。我写了一个“新页面生成”的 Skill描述里写清楚当用户说“创建一个 XX 页面”时AI 需要在指定目录下创建页面组件文件创建对应的样式文件在路由配置文件中添加路由条目创建对应的测试文件骨架更新导航菜单配置这个 Skill 帮我省掉了大量重复劳动。以前新建一个页面要 5 分钟现在一句话 10 秒钟搞定而且不会漏掉任何步骤。3.3 代码审查类提交前自动过一遍质量关代码审查 Skill 是我用得最频繁的之一。它的触发场景是“帮我审查这段代码”或“检查这个 PR”执行逻辑包括检查是否有未处理的 Promise rejection检查是否有硬编码的敏感信息检查是否有未使用的变量和导入检查边界条件处理检查是否有性能隐患如循环内创建函数我实测下来这类 Skill 能抓住大约 70% 的常见问题剩下的 30% 需要人工判断。但即便如此它已经把代码审查的效率提升了一大截——至少不用再手动去查那些低级问题了。3.4 测试生成类单元测试不再靠自觉写测试这件事大家都知道重要但真正自觉写的人不多。测试生成类 Skill 的思路是当你写完一个函数或组件后直接说“给这个函数生成测试”AI 会按照团队约定的测试框架和断言风格生成完整的测试用例。这类 Skill 需要包含的信息包括测试框架Jest/Vitest/Mocha、断言库偏好、测试文件命名和位置约定、mock 策略、覆盖率要求。写得越细生成的测试越可用。3.5 文档生成类注释和 README 自动维护文档类 Skill 解决的是“代码写了但没人知道怎么用”的问题。我配置了两个文档 Skill一个是“函数注释生成”当用户要求给某个函数加注释时按照 JSDoc 规范生成包含参数说明、返回值说明、示例用法的完整注释另一个是“README 更新”当项目结构发生变化时自动更新 README 中的目录说明和快速开始部分。3.6 Git 工作流类提交信息和分支管理规范化Git 提交信息写得随意是很多团队的通病。Git 工作流类 Skill 可以在你执行提交操作时根据变更内容自动生成符合 Conventional Commits 规范的提交信息。我用的这个 Skill 还会检查当前分支命名是否符合规范如果不符合会提示重命名。3.7 调试辅助类报错信息快速定位调试类 Skill 的触发场景是“这个报错怎么解决”或“帮我看看这段代码为什么报错”。它的核心逻辑是先分析报错类型和堆栈信息然后按照常见原因逐一排查最后给出修复建议。我把自己经常遇到的报错类型和解决方案都写进了这个 Skill现在遇到类似问题基本不用去搜索引擎了。3.8 学习解释类复杂代码的通俗解读最后一类可能被很多人忽略但实际很有用——学习解释类 Skill。当你接手一个陌生项目或看到一段看不懂的代码时直接说“解释一下这段代码”AI 会按照你预设的解释风格先讲整体逻辑再拆解关键步骤最后补充背景知识来输出。我给自己配的这个 Skill 要求 AI 用生活化类比来解释复杂概念效果比默认的解释方式好很多。下面这张表总结了 8 类 Skill 的核心信息方便你按需选择技能类型核心作用触发场景建议优先级代码规范类统一代码风格写新代码时最高项目脚手架类快速创建模块新建页面/组件时高代码审查类提前发现问题提交代码前最高测试生成类自动写测试完成函数/组件后高文档生成类维护注释文档代码变更后中Git 工作流类规范提交管理执行 Git 操作时中调试辅助类快速定位问题遇到报错时高学习解释类理解复杂代码阅读陌生代码时中4. 接入 Cursor 的完整流程与实操细节4.1 Cursor 中 Skills 的存放位置Cursor 对 Skills 的支持是通过项目根目录下的.cursor/skills/文件夹实现的。每个 Skill 一个子目录目录名就是技能标识里面放SKILL.md和辅助文件。目录结构如下项目根目录/ ├── .cursor/ │ └── skills/ │ ├── code-review/ │ │ └── SKILL.md │ ├── component-generator/ │ │ ├── SKILL.md │ │ └── templates/ │ │ └── component-template.tsx │ └── test-generator/ │ └── SKILL.md如果你想让某个 Skill 在所有项目中都生效可以放到用户主目录下的.cursor/skills/里。我个人的做法是通用规范类 Skill 放全局项目特定的 Skill 放项目目录。4.2 在 Cursor 中触发 Skill 的几种方式Cursor 识别 Skill 的方式有两种。一种是自动匹配当你的对话内容与某个 Skill 的description匹配时Cursor 会自动加载该 Skill 并在回答中应用。另一种是手动指定在对话中直接说“使用 code-review 技能来检查这段代码”Cursor 会强制加载指定的 Skill。实测下来自动匹配的准确率取决于description写得好不好。我的经验是description里要包含明确的触发关键词比如“当用户要求审查代码时”“当用户创建新组件时”这样匹配准确率会高很多。4.3 Cursor 中文设置与 Skills 的配合很多人在搜“cursor 中文怎么设置”或“cursor 设置中文”其实 Cursor 的界面语言和 Skill 的语言是两回事。界面语言在设置里改但 Skill 的内容语言完全由你自己决定。我建议SKILL.md用中文写因为这样你在对话中描述需求时更容易和 Skill 内容对应上。但name字段建议用英文避免某些版本对非 ASCII 字符处理不一致的问题。4.4 实测有效的 Cursor Skill 配置示例下面是我实际在用的一个代码审查 Skill 的完整内容你可以直接复制修改--- name: code-review description: 当用户要求审查代码、检查代码质量、或提交前检查时使用此技能 --- # 代码审查规范 审查代码时按照以下清单逐项检查 ## 必须检查项 1. 所有 Promise 是否有 .catch 或 try/catch 处理 2. 是否有硬编码的 API 地址、密钥、token 3. 是否有未使用的变量、导入、函数参数 4. 数组和对象访问是否有边界检查 5. 循环内是否创建了不必要的函数或对象 ## 建议检查项 1. 函数是否超过 50 行超过建议拆分 2. 是否有重复代码块超过 5 行相同逻辑 3. 命名是否清晰表达意图 4. 注释是否与代码逻辑一致 ## 输出格式 按照严重程度分级输出 - 严重必须修复才能提交 - 警告建议修复 - 提示可选优化这个 Skill 我用了三个月抓出来的问题比我预期多得多。特别是硬编码密钥这一项已经帮我避免了两次潜在的安全事故。5. 接入 Claude Code 的完整流程与实操细节5.1 Claude Code 中 Skills 的安装位置Claude Code 的 Skills 存放路径和 Cursor 不同。它读取的是项目根目录下的.claude/skills/文件夹结构跟 Cursor 类似项目根目录/ ├── .claude/ │ └── skills/ │ ├── code-review/ │ │ └── SKILL.md │ └── test-generator/ │ └── SKILL.md全局 Skill 放在~/.claude/skills/下。Claude Code 对 Skill 的加载逻辑是启动时扫描所有 Skill 的description在对话过程中根据上下文自动判断是否需要加载完整内容。5.2 从 GitHub 手动安装 Skills 的方法很多人搜“claude code 怎么手动装 github 上的 skills”流程其实很简单在 GitHub 上找到你想要的 Skill 仓库克隆或下载到本地把包含SKILL.md的目录复制到.claude/skills/下重启 Claude Code 或执行重新加载命令需要注意的是有些 Skill 仓库的结构是repo-name/skills/skill-name/SKILL.md你需要把skill-name这一层目录复制过去而不是整个仓库。我一开始就犯过这个错误把整个仓库扔进去结果 Claude Code 找不到SKILL.md。5.3 Claude Code 中 Skill 的触发与调试Claude Code 触发 Skill 的方式比 Cursor 更“隐式”——它不会明确告诉你“我正在使用 XX 技能”而是直接在回答中体现 Skill 的内容。如果你想确认某个 Skill 是否被加载了可以在对话中问“你现在加载了哪些技能”它会列出当前可用的 Skill 列表。调试 Skill 时最有用的一招是故意给一个应该触发 Skill 的请求然后看输出是否符合 Skill 中定义的规范。如果不符合说明description写得不够明确或者 Skill 内容有歧义。5.4 Claude Code 安装与基础配置要点搜“claude code 安装”和“claude code 使用教程”的人很多这里只说和 Skills 相关的配置要点。Claude Code 安装完成后建议先做三件事第一在项目根目录创建.claude/skills/目录第二写一个最简单的测试 Skill 验证加载是否正常第三把常用的全局 Skill 放到~/.claude/skills/下。在 Ubuntu 上安装 Claude Code 的流程和 macOS 基本一致主要是确保 Node.js 版本在 18 以上。安装完成后用claude --version确认版本然后在项目目录下运行claude启动交互界面。6. VS Code 中配置 Skills 与 AI 助手的协同6.1 VS Code 中 Skills 的存放与识别VS Code 本身不直接支持 Skills但通过 Claude Code for VS Code 扩展或类似的 AI 编程插件可以间接使用 Skills。存放位置取决于你用的扩展——Claude Code 扩展读取的还是.claude/skills/目录和命令行版本一致。如果你在 VS Code 里用 Cursor 的插件那读取的就是.cursor/skills/。所以最省事的做法是在项目根目录同时创建.cursor/skills/和.claude/skills/把同一套 Skill 放两份。虽然有点冗余但能保证不管用哪个工具都能生效。6.2 VS Code 连接 AI 模型的配置思路搜“vs code 连接 ai 模型”和“vs code 配置 claude code”的人不少核心配置点在于扩展的设置项。以 Claude Code 扩展为例安装后需要在设置中配置 API 密钥和模型选择。配置完成后在 VS Code 的集成终端里运行claude命令就能在编辑器内使用 Claude Code 的全部功能包括 Skills。我实测下来VS Code 里用 Claude Code 的体验和命令行版本基本一致但多了一个好处可以直接在编辑器里选中代码片段然后让 AI 基于选中的代码执行 Skill。比如选中一个函数然后说“给这个函数生成测试”测试生成 Skill 就会基于选中的代码工作。6.3 多工具协同的 Skill 管理策略如果你同时用 Cursor、Claude Code 和 VS CodeSkill 管理会变得有点复杂。我的策略是通用规范类 Skill在三个工具的全局目录各放一份内容保持一致项目特定 Skill只放在项目目录下通过符号链接让不同工具都能访问实验性 Skill只放在一个工具里测试稳定后再同步到其他工具符号链接在 macOS/Linux 上用ln -s命令创建Windows 上用mklink /D。这样你只需要维护一份 Skill 文件所有工具都能读取到最新版本。7. 常见问题与排查技巧实录7.1 Skill 不生效的排查思路Skill 写了但 AI 不按规范执行这是最常见的问题。排查顺序如下排查项检查方法常见原因文件位置确认SKILL.md在正确目录下放错层级如多了一层目录文件格式检查 YAML frontmatter 是否合法缺少---分隔符或缩进错误description看是否包含明确的触发关键词描述太模糊AI 无法匹配内容长度检查SKILL.md是否过长超过 500 行后 AI 容易遗漏工具版本确认工具版本支持 Skills旧版本可能不支持我遇到最多的问题是 YAML frontmatter 格式错误。name和description必须用---包裹而且冒号后面要有空格。这种小错误肉眼很难发现但会导致整个 Skill 被忽略。7.2 Skill 冲突与优先级处理当多个 Skill 的description都能匹配当前请求时AI 可能会加载错误的 Skill 或者同时加载多个导致输出混乱。解决方法有两个一是让每个 Skill 的description尽可能独特避免关键词重叠二是在对话中明确指定“使用 XX 技能”。如果两个 Skill 的内容有冲突比如一个要求用分号一个要求不用AI 通常会遵循后加载的那个。所以建议把更重要的 Skill 放在目录列表靠前的位置或者用更具体的description来确保它被优先匹配。7.3 性能与上下文窗口的平衡每个 Skill 被加载时都会占用上下文窗口。如果你装了 20 个 Skill每个 200 行那就是 4000 行的上下文消耗。这会导致两个问题一是响应变慢二是留给实际代码的上下文变少。我的经验是同时激活的 Skill 不要超过 5 个。把不常用的 Skill 从项目目录移到备份目录需要时再放回来。另外SKILL.md的内容要精炼能一句话说清楚的就不要写一段。7.4 独家避坑技巧汇总Skill 命名用英文小写加连字符避免空格和特殊字符导致路径问题每个 Skill 只做一件事功能越单一触发越准确维护越容易定期清理不再使用的 Skill每季度检查一次删掉过时的Skill 内容要版本化用 Git 管理.cursor/skills/和.claude/skills/目录方便回滚新 Skill 先在小范围测试不要一上来就全团队推广先自己用一周description 里写清楚“不适用场景”比如“此技能不适用于 Vue 项目”减少误触发8. 从零写一个高质量 Skill 的实操演示8.1 需求分析与结构设计假设我要写一个“API 接口生成”Skill需求是当用户提供接口描述时自动生成符合团队规范的 API 调用函数。先分析这个 Skill 需要包含哪些信息接口函数的命名规范请求方法的处理逻辑错误处理的统一格式类型定义的生成规则请求参数和响应数据的类型映射结构上SKILL.md负责描述规范templates/目录放一个示例文件供 AI 参考。8.2 编写 SKILL.md 的完整过程--- name: api-generator description: 当用户要求创建 API 接口函数、生成请求代码、或添加新的后端接口调用时使用此技能 --- # API 接口生成规范 ## 文件位置 所有 API 函数放在 src/api/ 目录下按模块分文件。 ## 函数命名 - 使用 camelCase以动词开头getUserInfo、createOrder、updateProfile - 禁止使用 fetch、request 等泛化命名 ## 请求方法 - GET参数通过 params 传递 - POST/PUT参数通过 data 传递 - DELETE参数通过 params 传递 ## 错误处理 所有 API 函数必须包含 try/catch错误统一抛出 ApiError 类型。 ## 类型定义 - 请求参数类型命名为 [函数名]Params - 响应数据类型命名为 [函数名]Response - 类型定义放在同文件的顶部 ## 示例 参考 templates/api-example.ts 中的写法。8.3 测试与迭代优化写完之后不要直接投入使用先做三轮测试第一轮给一个简单的接口描述看生成的代码是否符合规范。第二轮给一个带复杂参数的接口描述看类型定义是否正确。第三轮故意给一个模糊的描述看 AI 是否会要求澄清而不是瞎猜。根据测试结果调整SKILL.md的内容。我通常会迭代 3-5 版才能达到稳定可用的状态。迭代的重点通常是补充遗漏的规范、删除冗余的描述、调整description的触发关键词。9. 团队协作中的 Skills 管理与推广9.1 建立团队 Skill 仓库当团队超过 3 个人用 AI 编程工具时就需要一个统一的 Skill 仓库了。我的做法是在 Git 上建一个team-skills仓库目录结构如下team-skills/ ├── frontend/ │ ├── component-generator/ │ ├── code-review/ │ └── test-generator/ ├── backend/ │ ├── api-generator/ │ └── db-migration/ └── shared/ ├── git-workflow/ └── doc-generator/每个人通过 Git submodule 或直接复制的方式把需要的 Skill 放到自己项目的.cursor/skills/或.claude/skills/下。9.2 Skill 的版本管理与更新流程Skill 也是代码需要版本管理。我建议的流程是任何人修改 Skill 都要提 PRPR 中必须说明修改原因和测试结果至少一个人 review 通过后才能合并合并后打 tag方便回滚听起来有点重但实际执行下来并不麻烦。关键是让团队意识到 Skill 的质量直接影响 AI 输出的质量值得认真对待。9.3 推广落地的实操建议推广 Skills 最大的阻力不是技术是习惯。我的经验是先做 demo在团队会议上现场演示一个 Skill 的效果比讲十页 PPT 都有用从痛点切入先解决团队最头疼的问题比如代码审查或测试生成降低门槛提供现成的 Skill 模板让每个人改改就能用收集反馈每周花 10 分钟收集使用中的问题持续优化我带的团队从零到全员使用 Skills 大概花了三周时间。第一周只有两三个人在用第二周 demo 之后增加到七八个第三周基本全覆盖了。关键转折点就是那次 demo——当大家看到 AI 按照团队规范自动生成代码时接受度一下子就上来了。10. 我个人的一些使用体会Skills 这个东西刚接触的时候容易陷入两个极端要么觉得太简单不屑于用要么觉得太复杂不知道从哪开始。我的体会是从一个小痛点开始写一个最简单的 Skill用一周然后再决定要不要继续。我写的第一个 Skill 只有 15 行就是规定 AI 生成代码时必须用单引号而不是双引号。就这么一个小东西让我省掉了每次手动改引号的麻烦。后来慢慢扩展到代码审查、测试生成、API 生成现在我的.cursor/skills/目录下有 12 个 Skill覆盖了日常开发的大部分场景。还有一个体会是Skill 的质量比数量重要得多。我见过有人装了 50 个 Skill结果 AI 每次回答都要加载一大堆无关内容输出质量反而下降了。与其追求数量不如把最常用的三五个 Skill 打磨到极致。最后分享一个我最近在用的技巧把 Skill 和项目的README.md关联起来。在SKILL.md里写“详细规范参见项目 README 的 XX 章节”这样 AI 在需要时会去读取 README 中的相关内容相当于给 Skill 增加了一个动态扩展的上下文来源。这个技巧特别适合规范经常变动的项目——你只需要更新 READMESkill 不用改。
