1. 为什么 Skills 值得每个开发者认真对待第一次接触 Skills 这个概念是在给一个前端团队做工程效率内训的时候。当时有个同学问我“我每天都在用 Cursor 写代码但总感觉它像个刚入职的实习生每次都要从头交代一遍项目规范。”这句话点醒了我——大模型本身能力已经足够强真正卡住效率的是上下文和领域知识的注入方式。Skills 就是解决这个问题的。简单说Skills 是一套用 Markdown 描述的“技能包”它把某个具体任务的操作流程、约束条件、输出格式、参考样例打包成一个可复用的模块。你把它放进 Cursor、Claude Code、Codex 这类支持 Agent Skills 的工具里模型在遇到对应场景时就会自动加载这套技能按照你预设的方式干活。它解决的核心问题是把一次性的提示词工程变成可沉淀、可版本管理、可团队共享的工程资产。这篇文章适合三类人看。第一类是已经在用 Cursor 或 Claude Code但每次都要重复写提示词的开发者第二类是团队里负责工程规范、想把最佳实践固化下来的技术负责人第三类是对 Agent Skills 完全没概念想搞清楚 SKILL.md 到底长什么样、怎么装、怎么写的入门者。我会从设计思路讲到具体实操把 8 类我认为最值得装的技能拆开讲再给出接入 Cursor 和 Claude Code 的完整流程。内容基于我自己的使用经验和社区常见实践涉及具体参数的地方我会说明推导过程。需要先明确一点Skills 不是插件也不是传统意义上的扩展。它本质上是一段结构化的自然语言指令加上可选的脚本和资源文件。理解这一点后面很多设计取舍就顺了。2. Skills 的整体设计与核心思路拆解2.1 Skills 到底是什么从提示词到技能包的演进很多人第一次看到 SKILL.md 会有点懵觉得不就是个 Markdown 文件吗确实它的载体很朴素但关键在于它的组织方式和加载机制。传统的提示词是你每次对话时手动粘贴或者存在某个笔记里复制过来。Skills 把这个过程标准化了一个技能就是一个文件夹里面有 SKILL.md 作为入口可以附带脚本、模板、示例数据。工具在启动或按需时会扫描这些技能把匹配当前任务的技能内容注入到模型的上下文里。这个演进的意义在于提示词从“个人技巧”变成了“团队资产”。你可以把技能提交到 Git 仓库做 code review打版本号。新人入职拉下仓库技能就自动生效了。这是它和普通提示词最本质的区别。从技术实现角度看SKILL.md 通常包含几个部分技能名称和描述用于匹配、触发条件、执行步骤、输出规范、注意事项。有些实现还支持 frontmatter 元数据用来声明技能适用的工具、依赖等。不同工具对格式的要求略有差异但核心结构是相通的。2.2 为什么是 Markdown 而不是代码或配置这里有个设计上的取舍值得说清楚。为什么 Skills 用 Markdown 而不是 JSON、YAML 或者直接写代码我一开始也觉得奇怪后来想明白了Skills 的消费者是语言模型不是程序。模型最擅长理解的就是自然语言Markdown 既有结构又能承载自由文本是模型友好度和人类可读性之间的最佳平衡点。如果用 JSON 写你得把每个步骤塞进字符串里转义字符一堆写起来痛苦模型理解起来也未必更好。如果用代码写那就变成插件了失去了“用自然语言描述任务”的灵活性。Markdown 的好处是你可以用标题分层、用列表列步骤、用代码块放示例模型读起来结构清晰人读起来也舒服。提示写 SKILL.md 的时候不要为了追求格式漂亮而牺牲信息密度。模型不在乎你的标题层级是否完美它在乎的是指令是否明确、边界是否清晰。2.3 技能加载机制按需注入还是全量加载这是很多人关心的性能问题。如果装了几十个技能每次对话都全量加载上下文很快就爆了。实际实现里主流工具采用的是元数据匹配加按需加载的策略。启动时只读取每个技能的 name 和 description当用户的请求和某个技能的描述匹配度足够高时才把完整的 SKILL.md 内容注入上下文。这个机制决定了你写 description 的方式。description 不是给人看的简介而是给模型看的匹配依据。它要包含这个技能解决什么问题、什么场景下触发、关键词有哪些。写得含糊技能就永远不会被激活写得太宽泛又会误触发。我一般建议 description 控制在两三句话把核心场景和关键词都覆盖到。理解了这个机制你就能明白为什么有些技能装了没反应——大概率是 description 没写好模型匹配不上。3. 8 类值得装的 Skills 深度解析3.1 代码规范与风格统一类技能这类技能是我认为优先级最高的。原因很简单代码风格问题是团队协作里最高频的摩擦点。每个人都有自己的习惯缩进用空格还是 Tab、命名用驼峰还是下划线、注释写不写、写多少这些如果每次都靠人肉 review成本极高。一个典型的代码规范技能会在 SKILL.md 里明确写出项目使用的语言和框架版本、命名约定、目录结构约定、注释规范、错误处理模式。比如你可以写“所有异步函数必须用 try-catch 包裹错误统一走 logger.error 上报禁止直接 console.log”。模型在生成代码时就会遵守这些约束。我实测下来这类技能对 Cursor 的补全质量提升非常明显。因为 Cursor 的 Tab 补全和 Agent 模式都会参考上下文里的技能内容风格统一之后生成的代码几乎不需要手动调整格式。写这类技能有个技巧用反例比用正例更有效。与其写“请使用驼峰命名”不如写“禁止使用下划线命名变量例如 user_name 应写成 userName”。模型对否定约束的执行力往往更强。3.2 项目脚手架与初始化类技能每次新建项目都要重复配置一遍 ESLint、Prettier、TypeScript、测试框架这个过程既枯燥又容易漏。脚手架类技能就是把这套流程固化下来。这类技能的内容通常包括项目初始化命令、依赖安装清单、配置文件模板、目录结构创建步骤。你可以把常用的配置文件内容直接嵌在 SKILL.md 的代码块里模型会照着生成。我自己的做法是把公司内部的项目模板做成一个技能里面包含我们统一的技术栈选型。新人说一句“帮我初始化一个前端项目”模型就会按照技能里的步骤生成完整的项目骨架包括我们内部的 CI 配置和提交规范。这比写一份文档让新人照着做靠谱多了因为文档会过期技能跟着仓库走。注意脚手架技能里的依赖版本号要定期更新。我踩过的坑是技能里写的还是两年前的版本生成出来的项目一堆安全警告。建议把版本号抽出来或者用 latest 加注释说明。3.3 测试用例生成类技能写测试是很多开发者的痛点尤其是边界条件的覆盖。测试生成类技能可以显著提升这块的效率。这类技能的核心是告诉模型这个项目的测试框架是什么、断言风格是什么、mock 怎么做、覆盖率要求是多少。更进阶的写法是把常见的边界条件清单列进去比如“数值类型要测 0、负数、最大值、NaN字符串要测空串、超长串、特殊字符”。我试过在技能里加入“每个函数至少生成 3 个测试用例正常路径、边界条件、异常输入”这样的硬性约束生成出来的测试质量比不写这条时高出一截。模型有了明确的量化要求就不会偷懒只写一个 happy path。这里有个细节如果你的项目用 Jest就在技能里明确写 Jest 的 API 风格如果用 Vitest就写 Vitest 的。不要写“用常见的测试框架”模型会猜猜错就白干了。3.4 文档与注释生成类技能代码写完了文档没人写这是行业通病。文档生成类技能可以把这个环节的摩擦降到最低。这类技能要定义清楚文档的格式JSDoc、TSDoc、Markdown、注释的语言中文还是英文、需要包含哪些字段参数、返回值、异常、示例。我一般会要求模型为每个导出函数生成 TSDoc 注释包含 param、returns、example 三个标签示例代码要能直接运行。对于 API 文档可以做一个专门的技能规定接口文档的模板请求方法、路径、参数表、响应示例、错误码。模型读完代码后就能按模板生成比手写快得多而且格式统一。实测心得文档技能最好配合“只对导出成员生成文档”的约束否则模型会给每个内部函数都写一遍噪音太大。3.5 代码审查与重构建议类技能Code Review 是另一个高频场景。审查类技能可以定义审查的检查清单安全问题、性能问题、可读性问题、重复代码、错误处理缺失。我通常会在技能里列一个优先级顺序先看安全和正确性再看性能最后看风格。这样模型给出的审查意见有主次之分不会一股脑抛出一堆鸡毛蒜皮的问题。重构建议类技能则更进一步它会要求模型在指出问题的同时给出重构后的代码。这里要写清楚重构的原则比如“优先使用组合而非继承”“避免超过三层的嵌套”“单个函数不超过 50 行”。有了这些量化标准模型的建议才有可执行性。提示审查类技能建议设置“只报告严重和中等问题忽略轻微风格问题”的过滤条件否则 review 意见会淹没真正重要的内容。3.6 特定框架与库的专家类技能这类技能是针对具体技术栈的深度知识包。比如你团队重度使用 React就可以做一个 React 专家技能里面写清楚用函数组件不用类组件、状态管理用 Zustand 不用 Redux、副作用用 useEffect 的注意事项、性能优化用 memo 和 useMemo 的场景。再比如后端用 FastAPI就写清楚依赖注入的写法、Pydantic 模型的规范、异步路由的注意事项。这类技能的价值在于它把团队的技术选型和踩坑经验固化下来模型生成的代码天然符合团队习惯。我见过一个很聪明的做法把团队内部封装的工具库的 API 文档做成技能模型在生成代码时会优先使用内部库而不是第三方库减少了重复造轮子。3.7 数据处理与脚本编写类技能日常开发里总有一些一次性的数据处理任务解析日志、转换格式、批量重命名、生成报表。这类任务写起来不难但很烦交给模型又怕它写错。数据处理类技能可以定义输入数据的格式、输出格式、异常处理方式、日志输出规范。比如“读取 CSV 时用 pandas缺失值统一填 0输出前打印行数和列数做校验”。有了这些约束模型生成的脚本基本可以直接跑。我自己的经验是这类技能里加上“先打印数据前 5 行做确认”这样的步骤能避免很多因为数据格式理解错误导致的返工。3.8 提交信息与变更日志类技能Git 提交信息写得好不好直接影响后续的排查效率。提交信息类技能可以规定提交信息的格式Conventional Commits、语言、长度限制、body 里要写什么。比如规定“提交信息用英文type 从 feat/fix/docs/refactor/test/chore 里选subject 不超过 50 字符body 说明变更原因而不是变更内容”。模型在帮你生成提交信息时会严格遵守。变更日志类技能则更进一步它会读取一段时间的提交记录按类型归类生成结构化的 CHANGELOG。这个在发版本的时候特别省事。4. 接入 Cursor 与 Claude Code 的完整实操流程4.1 环境准备与工具版本确认在动手之前先把环境确认清楚。Cursor 需要较新的版本才支持 Skills 相关的目录扫描建议更新到最新稳定版。Claude Code 这边确认你已经完成安装并能正常在终端里调用。我一般会先跑一遍版本检查确认工具能正常启动。Cursor 的话打开设置面板确认 Agent 相关功能是开启状态。Claude Code 的话在终端里执行一次简单对话确认 API 连通性没问题。注意不同版本对技能目录的位置要求可能不同。动手前先查一下当前版本的文档确认技能应该放在哪个路径下。放错位置是最常见的“技能不生效”原因。4.2 技能目录结构设计与文件组织一个规范的技能目录长这样skills/ code-style/ SKILL.md examples/ good.ts bad.ts test-generator/ SKILL.md templates/ test-template.ts每个技能一个文件夹SKILL.md 是必须的入口文件其他资源按需添加。文件夹命名用小写加连字符和技能名称保持一致方便管理。SKILL.md 的头部通常需要 frontmatter声明 name 和 description。name 要和文件夹名一致description 写清楚触发场景。正文部分按“适用场景、执行步骤、输出规范、注意事项”的结构来写。我建议在项目根目录建一个 skills 文件夹纳入 Git 管理。这样团队共享的时候拉下代码就自动生效。个人全局技能可以放在用户目录下的配置文件夹里具体路径看工具文档。4.3 编写第一个 SKILL.md 的完整示例下面是一个代码规范技能的实际写法你可以直接参考--- name: code-style description: 当生成或修改 TypeScript 代码时使用此技能确保代码符合团队规范。适用于 .ts 和 .tsx 文件。 --- # 代码规范技能 ## 适用场景 生成新代码、修改现有代码、重构时。 ## 命名规范 - 变量和函数用驼峰userName、fetchData - 常量用全大写下划线MAX_RETRY_COUNT - 类型和接口用大驼峰UserProfile、ApiResponse - 禁止使用单字母变量名循环索引除外i、j ## 代码结构 - 单个函数不超过 50 行 - 嵌套层级不超过 3 层 - 优先使用早返回early return减少嵌套 ## 错误处理 - 异步操作必须用 try-catch 包裹 - 错误统一通过 logger.error 上报 - 禁止吞掉错误空 catch 块 ## 注释 - 导出函数必须有 TSDoc 注释 - 复杂逻辑需要行内注释说明意图 - 禁止保留被注释掉的死代码这个结构清晰、约束明确模型读完之后生成的代码基本符合预期。你可以根据自己的团队规范调整具体条款。4.4 在 Cursor 中启用与验证技能把技能文件夹放到 Cursor 能扫描到的位置后重启 Cursor 让它重新加载。然后在对话里测试让模型生成一段代码观察它是否遵守了技能里的规范。验证的时候要具体。比如技能里写了“禁止使用单字母变量名”你就让模型写一个循环看它用的是 i 还是 index。如果没生效先检查目录位置再检查 frontmatter 格式最后检查 description 是否匹配你的测试请求。我实测下来Cursor 对技能的加载有时候需要重新打开项目才生效。如果改了技能内容没反应先重启再说。4.5 在 Claude Code 中配置技能路径Claude Code 的技能配置通常在配置文件里指定技能目录。你需要确认配置文件的位置把技能目录路径加进去。具体配置项名称看版本一般是 skills 或 skillPaths 之类的字段。配置完成后在终端里启动 Claude Code它会扫描指定目录下的技能。测试方法和 Cursor 类似让模型执行一个技能覆盖的任务观察输出是否符合规范。提示Claude Code 在终端里运行时技能加载的日志通常会打印出来。如果没看到技能被加载检查路径是否正确、权限是否足够。4.6 技能生效验证与调试技巧技能不生效是新手最常遇到的问题。我整理了一个排查顺序先确认文件路径和命名再确认 frontmatter 格式然后确认 description 的匹配度最后确认工具版本是否支持。调试的时候有个技巧把 description 写得非常具体包含你测试请求里的关键词。比如你测试“生成测试用例”description 里就要有“测试用例”这个词。匹配上了再逐步优化措辞。另一个技巧是临时把技能内容写得很强硬比如“必须”“禁止”“始终”看模型是否响应。如果强硬措辞都不生效那就是加载环节出了问题不是内容问题。5. 常见问题与排查技巧实录5.1 技能不生效的六种典型原因现象可能原因排查方法完全没反应目录路径错误确认工具文档要求的路径偶尔生效description 匹配不稳定增加关键词写具体场景部分条款不遵守约束不够明确用否定句和量化标准重写改了没变化缓存未刷新重启工具或重新打开项目报格式错误frontmatter 语法问题检查 YAML 缩进和分隔符技能冲突多个技能描述重叠精简 description明确边界这张表是我踩坑之后总结的基本覆盖了九成以上的问题。遇到问题按顺序排查能省很多时间。5.2 技能之间冲突的处理策略装多了技能难免遇到冲突。比如代码规范技能说“用单引号”另一个技能说“用双引号”模型就懵了。处理策略有两个一是合并同类技能把风格相关的约束集中到一个技能里二是明确优先级在 description 里写清楚适用场景避免同时触发。我倾向于第一种技能数量控制在十个以内每个技能职责单一但完整。如果确实需要多个技能协作可以在技能里写明“本技能优先级高于通用规范”给模型一个明确的裁决依据。5.3 技能内容过长导致上下文溢出的应对技能写得太长注入上下文后会挤占对话空间导致模型“忘记”前面的内容。这个问题在装了很多技能时尤其明显。应对方法是分层核心约束放在 SKILL.md 主体详细的示例和参考资料放到附属文件里只在需要时引用。比如 SKILL.md 里写“示例见 examples/good.ts”模型需要时会去读不需要时不占用上下文。另一个方法是定期清理不常用的技能。我每个季度会 review 一遍技能列表把三个月没用过的归档。5.4 团队协作中技能版本管理的最佳实践技能纳入 Git 管理之后版本管理就很重要。我的做法是技能仓库单独一个 repo用语义化版本打 tag。团队成员的技能目录通过软链接指向这个 repo 的 checkout。更新技能时走正常的 PR 流程有人 review 之后再合并。这样避免了某个人随手改技能导致全团队行为变化。技能变更也要写 CHANGELOG说明改了什么、为什么改。注意技能里的敏感信息内部 API 地址、密钥不要直接写进去用占位符代替让使用者自己填。5.5 技能效果评估与迭代方法技能写完不是终点要持续迭代。我的评估方法是记录技能生效前后的效率变化。比如测试生成技能上线前写一个模块的测试要 30 分钟上线后 10 分钟这就是有效。迭代的时候小步快跑一次改一两个条款观察效果。不要一次性大改否则出了问题不知道是哪个改动导致的。我一般会在技能里留一个“变更记录”区块记下每次调整的原因和效果。6. 技能开发的进阶思路与个人体会6.1 从使用者到创作者的心态转变用了一段时间别人的技能之后你会发现通用技能总有不贴合自己项目的地方。这时候就该动手写自己的技能了。写技能的过程其实是在梳理自己对项目的理解。很多平时说不清楚的规范写技能的时候被迫想明白了。我的建议是从最小的技能开始比如就规定一条命名规范跑通了再扩展。不要一上来就写一个大而全的技能容易挫败。6.2 技能组合与工作流编排单个技能解决单点问题多个技能组合起来能形成工作流。比如“脚手架技能 代码规范技能 测试生成技能”组合起来就能实现从建项目到写测试的完整流程。编排的关键是让技能之间的衔接自然。前一个技能的输出格式要能被后一个技能识别。这需要在写技能时就考虑上下游的接口。6.3 我踩过的三个印象深刻的坑第一个坑是 description 写得太文艺。我一开始写“本技能致力于提升代码质量”模型根本匹配不上。后来改成“生成 TypeScript 代码时使用确保命名和结构符合规范”立刻就生效了。description 要写大白话写关键词。第二个坑是技能里用了太多“建议”“可以”这样的软性词。模型对软性词的执行力很弱基本等于没写。后来全部改成“必须”“禁止”“始终”效果立竿见影。第三个坑是技能没有版本控制改乱了没法回滚。有一次误删了一段关键约束导致生成的代码风格全乱排查了半天才发现是技能被改了。从那以后技能仓库严格走 Git 流程。6.4 技能生态的后续扩展方向技能这个东西用顺手之后会想更多玩法。比如把技能和 CI 结合在流水线里用技能做自动 review或者把技能做成模板市场团队之间共享。再远一点技能可以和项目文档联动文档更新时自动同步技能内容。我个人最看好的方向是技能的可测试化。给技能写测试用例验证它在各种输入下是否产生预期输出。这样技能迭代就有了质量保障不会越改越乱。这个方向目前工具支持还不够但值得关注。最后分享一个小技巧写技能的时候把自己想象成在给一个聪明但完全不了解你项目的新人交代事情。该说的说清楚不该假设的别假设。这个心态下写出来的技能质量都不会差。
