1. 为什么 Skills 值得开发者花时间研究1.1 从一个真实场景说起上个月帮朋友排查一个前端项目的问题打开他的 Cursor 发现每次对话都要重新粘贴一遍项目规范、目录结构说明、代码风格要求。我问他为什么不把这些固化成 Skills他反问我“Skills 是什么跟提示词有什么区别”这个对话让我意识到虽然 Skills 这个概念在开发者圈子里已经热了大半年但真正把它用起来、用对的人并不多。大部分人还停留在“每次对话手动喂上下文”的阶段效率低不说输出质量还极不稳定。Skills 本质上是一套可复用的能力封装机制。你可以把它理解成给 AI 编程助手写的“岗位说明书”——告诉它在这个项目里应该遵循什么规范、调用什么工具、按什么流程干活。跟传统提示词最大的区别在于提示词是临时的、一次性的而 Skills 是持久化的、结构化的、可以被多个会话共享的。1.2 Skills 到底解决了什么问题我总结下来Skills 主要解决三类痛点第一类是上下文重复问题。每次开新会话都要重新交代项目背景、技术栈、代码规范这些信息不变但每次都要重复输入纯属浪费。第二类是能力标准化问题。团队里每个人用 AI 的方式不一样有人写得好有人写得差输出质量参差不齐。Skills 可以把最佳实践固化下来让所有人都能调用同一套标准。第三类是工具集成问题。很多操作需要调用外部工具或脚本比如生成图片、查询数据库、执行特定命令。Skills 可以把这些工具调用封装成标准接口AI 直接调用就行。提示Skills 不是万能的它更适合那些重复性高、流程固定、需要标准化的场景。如果你的任务每次都不一样硬套 Skills 反而会增加维护成本。1.3 适合谁来学这篇文章主要面向三类读者个人开发者想让 AI 助手更懂自己的项目减少重复沟通成本团队技术负责人想统一团队的 AI 使用规范提升协作效率工具链爱好者喜欢折腾各种开发工具想第一时间体验新能力不管你用的是 Cursor、Claude Code 还是 VS Code 配合其他 AI 插件Skills 的核心逻辑是相通的。下面我会从设计思路讲到具体实操尽量让不同基础的读者都能跟上。2. 八类值得装的 Skills 深度拆解2.1 代码规范类 Skills让 AI 写出符合团队风格的代码这类 Skills 是我认为优先级最高的。原因很简单代码规范是团队协作的基础但也是最容易被 AI 忽略的部分。你不告诉它它就按自己的习惯来生成的代码风格五花八门。一个完整的代码规范 Skill 应该包含这些内容命名约定变量用驼峰还是下划线常量全大写还是帕斯卡文件命名用中划线还是下划线目录结构组件放哪、工具函数放哪、类型定义放哪导入顺序第三方库在前还是本地模块在前是否需要分组注释规范什么情况必须写注释注释用什么语言错误处理统一用 try-catch 还是错误边界错误信息格式是什么我自己的做法是把 ESLint 配置和 Prettier 配置直接嵌到 Skill 里这样 AI 生成代码时会自动对齐这些规则。实测下来代码 review 时因为风格问题打回的次数减少了大概七成。注意规范类 Skill 不要写得太细。我见过有人把每一行代码的格式都规定死结果 AI 生成时畏手畏脚反而影响效率。抓大放小把关键约定写清楚就行。2.2 项目上下文类 Skills一次配置长期受益这类 Skills 解决的是“AI 不了解我项目”的问题。一个典型的项目上下文 Skill 应该包含项目简介这个项目是干什么的核心功能有哪些技术栈清单框架、语言、数据库、部署方式关键目录说明每个目录放什么哪些是核心代码外部依赖调用了哪些第三方服务接口文档在哪环境变量说明需要配置哪些环境变量各自什么作用我习惯在项目根目录建一个.skills/文件夹把这类 Skill 放进去。每次开新会话AI 会自动读取这些信息省去了大量重复交代的时间。这里有个小技巧项目上下文 Skill 要定期更新。项目迭代快的话建议每个 sprint 结束时花五分钟检查一下把过时的信息改掉。我踩过的坑就是有次数据库从 MySQL 换成了 PostgreSQL但 Skill 里没改结果 AI 生成的查询语句全是 MySQL 语法排查了半天才发现问题。2.3 工作流类 Skills把重复操作自动化工作流类 Skills 是我觉得最能体现价值的一类。它把那些你每天都要做、但每次都要手动操作的事情固化下来。举几个我实际在用的例子提交信息生成 Skill读取 git diff按照团队约定的格式生成 commit message。我们团队的格式是type(scope): descriptionAI 会自动判断 type 是 feat 还是 fixscope 是哪个模块。代码审查 Skill按照检查清单逐项审查代码包括是否有硬编码、是否有未处理的边界情况、是否有性能隐患。这个 Skill 我配置了输出格式审查结果直接以表格形式呈现一目了然。文档生成 Skill读取代码注释和函数签名自动生成 API 文档。支持 Markdown 和 OpenAPI 两种格式。测试用例生成 Skill根据函数逻辑生成单元测试覆盖正常路径和边界情况。这类 Skills 的设计要点是输入输出要明确。你得清楚告诉 AI输入是什么比如 git diff输出是什么格式比如特定格式的 commit message中间经过哪些步骤。2.4 工具集成类 Skills让 AI 调用外部能力这类 Skills 让 AI 能够调用外部工具扩展能力边界。常见的集成场景包括工具类型典型用途集成方式图片生成生成占位图、图标、示意图调用图片生成 API数据库查询查询数据、生成报表封装 SQL 查询接口文件处理批量重命名、格式转换调用脚本网络请求调用第三方 API封装请求方法代码执行运行测试、执行脚本调用终端命令我重点说一下图片生成 Skills 的配置。很多开发者需要生成占位图或者简单的示意图手动做很麻烦。配置一个图片生成 Skill 后直接告诉 AI“生成一个 800x600 的占位图主题色是蓝色”它就会调用相应的接口生成图片并保存到指定目录。提示工具集成类 Skills 要注意权限控制。不要让 AI 无限制地调用外部工具特别是涉及文件删除、数据库写操作这类危险动作时一定要加确认步骤。2.5 学习辅助类 Skills把知识库变成可调用的能力这类 Skills 适合那些需要频繁查阅文档的场景。比如你正在学一个新框架可以把官方文档的核心内容整理成 Skill之后遇到问题直接问 AI它会基于你整理的文档来回答而不是靠它自己的记忆。我学 Rust 的时候就这么干的。把所有权、生命周期、trait 这些核心概念整理成 Skill遇到不确定的语法就查一下比翻文档快多了。这类 Skills 的整理要点是结构化。不要直接把文档复制粘贴进去要提炼成问答形式或者要点列表。我一般会按“概念定义 - 使用场景 - 代码示例 - 常见错误”这个结构来整理。2.6 调试排查类 Skills把排查经验固化下来调试是开发中最耗时的环节之一。一个有经验的开发者排查问题有一套自己的方法论但这些经验往往只存在脑子里。调试排查类 Skills 就是把这套方法论固化下来。我配置的调试 Skill 包含这些内容常见错误模式比如空指针、类型不匹配、异步时序问题各自的典型表现是什么排查步骤从哪开始查先看日志还是先看代码怎么缩小范围工具使用断点怎么打、日志怎么加、性能怎么分析修复验证改完之后怎么验证问题真的解决了这个 Skill 我用了大半年最大的感受是排查速度明显变快。以前遇到问题要愣半天想从哪下手现在 AI 会直接给出排查路径照着走就行。2.7 代码重构类 Skills安全地改进代码质量重构的难点不在于改代码而在于保证不改出问题。重构类 Skills 的核心价值就是提供一套安全的改进流程。我的重构 Skill 包含这些规则小步前进每次只改一个点改完立即验证测试先行重构前先确保有测试覆盖没有就补上行为不变重构只改结构不改行为所有测试必须通过及时回滚发现问题立即回滚不要试图在错误的基础上继续改具体操作上我会让 AI 先分析代码的坏味道重复代码、过长函数、过深嵌套然后给出重构建议我确认后再执行。执行过程中每改一步就运行一次测试确保没有破坏现有功能。2.8 团队协作类 Skills统一团队的 AI 使用方式如果你是团队负责人这类 Skills 值得重点关注。它解决的是“团队里每个人用 AI 的方式不一样”的问题。团队协作类 Skills 通常包含代码审查标准审查时关注哪些点什么级别的问题必须改文档模板技术方案、接口文档、变更记录的模板沟通规范AI 生成的回复应该用什么语气详细程度如何知识沉淀解决问题后如何记录记录到哪里我帮一个十人团队配置过这类 Skills效果很明显。以前 code review 时每个人关注的点不一样有人只看逻辑有人只看风格。配置了统一的审查 Skill 后审查标准一致了漏掉问题的概率大幅降低。3. 接入 Cursor 的完整流程3.1 Cursor 中 Skills 的存放位置与加载机制Cursor 对 Skills 的支持是通过项目根目录下的.cursor/skills/文件夹实现的。每个 Skill 是一个独立的 Markdown 文件文件名就是 Skill 的名称。目录结构大概长这样项目根目录/ ├── .cursor/ │ └── skills/ │ ├── code-style.md │ ├── project-context.md │ ├── commit-message.md │ └── debug-guide.md ├── src/ └── package.jsonCursor 在启动会话时会自动扫描这个目录把所有 Skill 加载到上下文里。你可以在对话中通过skill名称的方式显式调用某个 Skill也可以让 Cursor 根据当前任务自动匹配。注意Skill 文件不要写得太长。我实测下来单个 Skill 控制在 500-1500 字效果最好。太短信息量不够太长会挤占上下文窗口反而影响其他信息的处理。3.2 编写第一个 SKILL.md 文件SKILL.md 的格式没有强制要求但遵循一定的结构会让 AI 更容易理解。我推荐的结构是这样的# Skill 名称 ## 用途 一句话说明这个 Skill 是干什么的。 ## 触发条件 什么情况下应该使用这个 Skill。 ## 具体规则 1. 规则一 2. 规则二 3. 规则三 ## 示例 输入示例和输出示例。 ## 注意事项 需要特别提醒的点。拿代码规范 Skill 举例实际内容大概是这样# 代码规范 ## 用途 确保生成的代码符合团队约定的风格规范。 ## 触发条件 生成任何 JavaScript/TypeScript 代码时自动应用。 ## 具体规则 1. 变量和函数使用驼峰命名常量使用全大写下划线 2. 导入顺序Node 内置模块 第三方库 本地模块 3. 每个函数不超过 50 行超过则拆分 4. 异步操作统一使用 async/await不用回调 5. 错误处理使用 try-catch错误信息包含上下文 ## 示例 输入写一个读取配置文件的函数 输出 javascript async function readConfig(filePath) { try { const content await fs.readFile(filePath, utf-8); return JSON.parse(content); } catch (error) { throw new Error(读取配置文件失败: ${filePath}, { cause: error }); } }注意事项不要过度格式化保持代码可读性优先遇到规则冲突时以项目现有的 ESLint 配置为准### 3.3 Cursor 中文设置与 Skills 的配合 很多开发者习惯把 Cursor 设置成中文界面这个在 Settings 里搜索 “language” 就能改。但要注意的是**界面语言和 Skill 语言是两回事**。 我的建议是Skill 文件用英文写或者中英混合。原因是英文的 token 效率更高同样的信息量占用的上下文更少。而且 AI 对英文技术术语的理解通常更准确。 如果你确实想用中文写 Skill也没问题但要注意术语的一致性。比如“组件”和“模块”不要混用“接口”和“API”选一个固定的说法。 ### 3.4 在 Cursor 中调用 Skills 的几种方式 Cursor 里调用 Skills 主要有三种方式 **自动匹配**Cursor 会根据你的问题自动判断该用哪个 Skill。比如你问“帮我写个登录函数”它会自动加载代码规范 Skill。 **显式引用**在对话中输入 code-style 来显式调用某个 Skill。这种方式适合你明确知道需要哪个 Skill 的场景。 **组合调用**可以同时引用多个 Skill比如 code-style project-context让 AI 同时遵循代码规范和项目上下文。 我个人的习惯是日常开发用自动匹配遇到复杂任务时显式引用多个 Skill。这样既能享受便利又能在需要时精确控制。 ## 4. 接入 Claude Code 的完整流程 ### 4.1 Claude Code 的安装与基础配置 Claude Code 是 Anthropic 推出的命令行 AI 编程工具安装方式根据操作系统不同略有差异。 在 macOS 或 Linux 上可以通过 npm 安装 bash npm install -g anthropic-ai/claude-code在 Ubuntu 上如果遇到权限问题可以加上sudo或者配置 npm 的全局目录。安装完成后运行claude命令会引导你完成初始配置包括 API 密钥设置和默认模型选择。Windows 用户建议在 WSL2 环境下使用体验会更顺畅。原生 Windows 支持虽然有了但某些终端相关的功能还是 WSL 下更稳定。提示Claude Code 的配置文件默认在~/.claude/目录下。如果你想自定义配置位置可以通过环境变量CLAUDE_CONFIG_DIR来指定。4.2 Claude Code 中 Skills 的组织方式Claude Code 对 Skills 的支持方式和 Cursor 不太一样。它使用的是~/.claude/skills/目录全局或者项目根目录下的.claude/skills/目录项目级。项目级 Skills 的优先级高于全局 Skills。也就是说如果同一个 Skill 名称在两个地方都存在项目级的会覆盖全局的。这个设计很合理允许你为特定项目定制 Skill而不影响其他项目。Claude Code 的 Skill 文件格式和 Cursor 基本一致都是 Markdown。但 Claude Code 支持一些额外的元数据字段比如--- name: code-style description: 代码规范检查 version: 1.0.0 tags: [javascript, typescript, style] --- # 代码规范 ...这些元数据字段可以帮助 Claude Code 更精确地匹配 Skill。特别是tags字段在自动匹配时很有用。4.3 手动安装 GitHub 上的 Skills社区里已经有不少人分享了自己写的 SkillsGitHub 上搜 “claude skills” 或者 “cursor skills” 能找到不少。手动安装的步骤一般是找到想要的 Skill 仓库clone 到本地把 Skill 文件复制到.claude/skills/或.cursor/skills/目录根据需要修改内容适配自己的项目重启 Claude Code 或 Cursor 使配置生效我建议不要直接拿来就用。社区分享的 Skills 往往是针对特定项目或技术栈的直接套用到自己项目上可能水土不服。正确的做法是把它当作参考理解它的设计思路然后根据自己的需求改写。4.4 Claude Code 与 VS Code 的配合使用Claude Code 虽然是个命令行工具但可以和 VS Code 配合使用体验会更好。具体做法是在 VS Code 的集成终端里运行 Claude Code这样它就能直接访问当前打开的项目。配合 VS Code 的文件树和编辑器可以边看代码边和 AI 对话。如果你用的是 VS Code 的 Claude Code 扩展还可以实现更深度的集成比如在编辑器里直接选中代码让 AI 解释或重构。注意VS Code 扩展和命令行版本的功能不完全一致。扩展版本更偏向于编辑器内的交互命令行版本功能更全。我个人的习惯是两个都用简单问题用扩展复杂任务用命令行。5. 常见问题与排查技巧实录5.1 Skills 不生效怎么办这是最常见的问题。排查思路按优先级排列第一步检查文件位置。Cursor 是.cursor/skills/Claude Code 是.claude/skills/别放错了。我见过有人把 Skill 放在.github/目录下然后问为什么没生效。第二步检查文件格式。必须是.md后缀文件名不要有特殊字符。中文文件名虽然支持但有时候会有编码问题建议用英文。第三步检查是否重启。添加或修改 Skill 后需要重启工具才能生效。Cursor 有时候需要完全退出再打开不是简单的新建会话就行。第四步检查 Skill 内容。如果 Skill 内容格式有问题比如 YAML frontmatter 写错了整个 Skill 会被忽略。可以先用一个最简单的 Skill 测试确认机制没问题后再加复杂内容。5.2 Skill 之间冲突怎么处理当多个 Skill 的规则冲突时AI 的行为会变得不可预测。比如一个 Skill 说“函数不超过 50 行”另一个说“函数不超过 30 行”AI 就不知道该听谁的。我的处理原则是明确优先级在 Skill 里写明优先级比如“本规则优先级高于通用代码规范”避免重叠不同 Skill 负责不同维度不要在一个维度上定义多套规则定期清理删掉不再使用的 Skill减少冲突可能如果两个 Skill 确实需要同时存在且有冲突可以在调用时显式指定用哪个比如code-style-strict而不是code-style。5.3 性能问题Skills 太多导致响应变慢Skills 不是越多越好。每个 Skill 都会占用上下文窗口Skill 太多会导致响应速度变慢上下文被挤占AI 记不住重要信息匹配准确率下降我的经验值是项目级 Skills 控制在 5-8 个全局 Skills 控制在 3-5 个。超过这个数量就要考虑合并或删减了。合并的技巧是把相关的 Skill 整合成一个。比如把“代码规范”和“命名约定”合并成“编码规范”把“提交信息”和“分支管理”合并成“Git 工作流”。5.4 常见问题速查表问题现象可能原因解决方法Skill 完全不生效文件位置错误检查是否放在正确的 skills 目录Skill 时灵时不灵内容太长被截断精简 Skill 内容控制在 1500 字以内AI 忽略 Skill 规则规则不够明确用明确的祈使句避免模糊表述多个 Skill 冲突规则重叠合并或明确优先级响应变慢Skill 数量过多精简到 5-8 个中文 Skill 乱码编码问题统一使用 UTF-8 编码5.5 几个我踩过的坑坑一Skill 写得太抽象。一开始我写 Skill 喜欢用“保持代码简洁”这种模糊表述结果 AI 理解不了。后来改成“单个函数不超过 50 行嵌套不超过 3 层”效果立竿见影。坑二忘了更新 Skill。项目技术栈升级了但 Skill 没同步更新导致 AI 生成的代码用的是旧语法。现在我养成了习惯每次技术栈变更时第一件事就是更新相关 Skill。坑三Skill 之间互相引用。我在一个 Skill 里写了“参考 code-style Skill 的规则”结果 AI 有时候找不到那个 Skill行为就不一致了。后来改成每个 Skill 自包含不依赖其他 Skill。坑四过度依赖 Skill。有段时间我什么都要写成 Skill连“帮我改个变量名”这种一次性任务也想固化下来。后来发现维护成本太高很多 Skill 用了一次就再也没用过。现在我的原则是只有重复三次以上的操作才值得写成 Skill。6. 进阶如何设计高质量的 Skill6.1 好 Skill 的三个特征用了大半年 Skills我总结出高质量 Skill 的三个特征特征一边界清晰。一个好的 Skill 应该能一句话说清楚它是干什么的。如果你需要用一段话来解释说明这个 Skill 的职责太宽泛了应该拆分。特征二规则可执行。规则必须是 AI 能直接执行的不能是“写得好一点”这种主观判断。好的规则像“函数参数不超过 4 个”坏的规则像“代码要优雅”。特征三有示例。示例比规则更有说服力。一个具体的输入输出示例比十条抽象规则更能让 AI 理解你的意图。6.2 Skill 的迭代方法Skill 不是写完就完了需要持续迭代。我的迭代方法是收集反馈每次 AI 输出不符合预期时记录下问题分析是 Skill 没覆盖到还是规则不明确。小步修改每次只改一个点改完立即测试。不要一次性大改否则出了问题不知道是哪个改动导致的。定期回顾每个月花半小时回顾所有 Skill删掉不用的合并重复的更新过时的。版本管理把 Skills 目录纳入 git 管理这样可以看到每次改动的内容出问题也能回滚。6.3 团队协作中的 Skill 管理如果是团队使用Skill 管理需要额外的规范统一存放所有 Skill 放在项目的.skills/目录下纳入版本控制命名规范用模块-功能.md的格式命名比如frontend-style.md、backend-api.md变更流程修改 Skill 需要走 code review确保改动合理文档说明每个 Skill 开头写清楚用途和维护人我帮团队配置的时候还加了一个README.md列出所有 Skill 的清单和用途新人进来一看就明白。6.4 Skill 的未来演进方向从目前的发展趋势看Skills 正在往几个方向演进更智能的匹配未来的 Skills 可能会根据项目类型、当前任务、历史行为自动推荐不需要手动配置。更丰富的类型除了文本规则可能会出现可视化配置、流程图形式的 Skill降低编写门槛。更强的组合能力多个 Skill 可以组合成 Skill 链按顺序执行完成复杂任务。跨工具兼容不同 AI 编程工具的 Skill 格式可能会统一写一次到处能用。这些演进方向对开发者来说是好事意味着学习成本会降低使用体验会提升。但核心逻辑不会变把重复性的、标准化的能力封装起来让 AI 更懂你的项目。我个人在实际操作中的体会是Skills 的价值不在于数量多而在于精准。与其装二十个用不上的 Skill不如精心维护五个真正贴合自己工作流的。每次配置一个新 Skill 之前先问自己这个操作我一个月会做几次如果少于三次那就不值得。这个判断标准帮我省下了大量维护时间也让我的 Skills 目录始终保持精简高效。
