最近半年只要你在跟 AI 编程工具打交道不管是 Claude Code、OpenCode 还是 Cursor基本都会撞上“skills”这个词。它被反复提到甚至有人把它称作 AI 编程里的 superpower但真正能说清楚它是什么、怎么用、怎么自己写一个的人并不多。我花了大概两周时间把主流的 skills 规范、社区项目、以及几个大模型的官方文档都过了一遍自己也手搓了几个能跑的 skills今天这篇就把完整玩法拆开来讲。先说结论skills 不是一个具体工具也不是某个平台的独占功能而是一套让 AI 编程助手“按模块化方式获得专项能力”的组织方法。它解决的核心问题是——通用模型很强但在特定任务上又不够强。比如让 Claude 写个单元测试它写得不错让它按照你们团队的测试规范、目录结构、命名规则、覆盖率要求去写它就拉胯了因为你没法把这些上下文塞进一次对话里。skills 就是把这类“专项操作手册”提前准备好需要的时候让模型按手册执行。这篇内容适合谁正在用 Claude Code、OpenCode、Cursor 这类工具的人或者在做 Agent 应用开发、想把重复性工作固化成标准化流程的人。看完你至少能掌握三件事一skills 的正确目录结构和配置文件怎么写二如何从零开发一个自己的 skill 并在本地调试三如何处理 skills 与 MCP 工具的关系以及我踩过的那些坑。1. Skills 究竟是什么它跟提示词、插件、MCP 有什么本质区别1.1 它本质上是一份“给 AI 的操作手册”很多人在第一次看到.claude/skills或skills目录时会想这不就是换个方式写 prompt 吗理论上确实终极都是“用文字驱动模型”但区别在于组织粒度、触发方式和上下文管理策略。普通的 prompt 是一段一次性交付的指令模型读完就执行用完就忘。skills 则是一套“预设行为包”它由描述文档、示例、甚至可执行脚本组成模型在收到任务时会先读取 skill 的说明文件再把技能加载到自己的“工作台”上按流程执行。这个机制类比一下就像做饭——提示词是“你告诉我做红烧肉”skills 则是“你递给我一本菜谱菜谱里不但写了步骤还标注了家常版和宴客版怎么做连配菜切法都配了示意图”。所以 skills 真正的价值不是“写了一堆指令”而是把过去藏在资深工程师脑子里的领域知识、团队规范、操作流程变成了 Agent 随时可以调用的外部记忆。它让新成员在这就是 AI第一次干活就有老师傅带而不是靠运气。1.2 为什么几乎所有主流 Agent 工具都在押注 skills从 2024 年底到现在我观察到一件明显的事OpenAI 开始在自己的 Agent 工具里做“自定义指令”Anthropic 直接搞了 Agent Skills 的官方文档Google 的 Gemini 也开始支持类似插件机制。更别提开源生态里baoyu 的 skills 项目、mattpocock 的 typescript skills、各种 math modeling 相关的 skills一夜之间铺天盖地。这背后的逻辑其实很简单纯靠“模型更大、参数更多”来提升 Agent 能力的边际效应在递减。更大的上下文窗口确实能装更多信息但模型处理长下文时的注意力漂移、成本爆炸、延迟上升都是现实问题。Skills 走的是另一条路——每次只加载当前任务真正需要的知识片段其余保持惰性。这是一种信息架构上的优化不是蛮力堆料。另外skills 也把“人机协作”的边界往前推了一步。过去我们要写好详尽的产品需求文档AI 才能比较好地执行现在有了 skills你可以把公司的编码规范、代码评审清单、发布流程全部固化进去。团队里任何一个人调用 AI 写代码出来的东西风格都是一致的。把这个机制称为团队能力的“水平复制”也不为过。2. 目录结构与配置规范几个关键文件决定了 skills 好不好用2.1 标准的目录结构长什么样目前我接触到的几种实现虽然不同工具在细节上有出入但主干结构基本是同一套。以 Claude Code 的 Agent Skills 为例一个干净的 skills 项目长这样my-skill/ ├── SKILL.md ├── scripts/ │ ├── analyze.py │ └── generate_report.py ├── assets/ │ ├── template.yaml │ └── sample_data.json └── references/ └── domain_notes.mdSKILL.md是这个 skill 的入口和核心模型在调用时会先读它。这个文件的头部是 YAML frontmatter接着是 Markdown 正文。frontmatter 里的name和description尤其重要因为它们决定了这个 skill 什么时候会被模型“想起来”。我见过不少失败的 skill 案例共同点就是 description 写得太宽泛。比如“用于帮助写前端代码”——这种描述在调用的时候模型根本不知道什么时候该用它结果就是 skill 不被触发白写。正确做法是像搜索词一样精确比如“适用于将设计稿图片转换为语义化 HTML/CSS 代码支持 Tailwind 和 CSS Modules 两种输出格式”。2.2 Frontmatter 元信息与正文写作的心法一个典型的SKILL.md文件头我建议这样写--- name: frontend-design-to-code description: 将设计稿图片或截图转换为语义化 HTML/CSS 代码支持 Tailwind 和 CSS Modules 两种输出格式适用于 React/Vue 项目。 ---注意 description 不要超过两行要写清楚“触发条件 输出格式 适用范围”。模型做技能匹配的时候基本就是把你的 description 和当前用户请求做语义相似度匹配所以描述越接近用户的真实说法命中率越高。正文部分不是让你写一个“万能指令”而是围绕“执行流程、输入输出规格、约束条件、示例”四块来写。拿设计稿转代码来说正文可以规定第一步先分析图片里的布局结构第二步提取色彩和字体第三步生成 HTML 骨架第四步写 CSS 样式第五步做响应式适配。每一步都标注清楚期望的产物格式。实际操作心得不要把 SKILL.md 写成一份面面俱到的长文档。模型能一次读完的上下文是有限的skill 文档太长会挤占后续交流空间。我的经验是控制在 400-600 行 markdown 以内尽量用短句、列表和示例代替大段叙述。3. 从零开发一个自己的 Skills设计一个代码审查技能的全过程3.1 场景选择与技能边界定义我这段时间开发了不少 skills有用于前端开发的、有用于渗透测试的、还有用于数学建模的。如果让我推荐一个最容易上手的练习项目那就是“代码审查 skill”。原因很简单需求明确、输出格式可以标准化、不需要额外调外部服务。先定义这个 skill 的边界。团队里的代码审查通常包含检查代码风格是否符合规范、查找明显的逻辑漏洞、评估单元测试覆盖率、检查是否有硬编码的敏感信息。我们的 skill 就要把这四件事拆成标准步骤并规定每一步的产物。我给这个 skill 起名code-review-helper它的定位不是替代人的审查而是做“第一道扫描”输出结构化审查报告让人再去判断。3.2 手把手编写 SKILL.md 与辅助脚本下面是我实际用的SKILL.md骨架你可以直接参考--- name: code-review-helper description: 对指定代码文件或代码片段进行初步审查按提交规范、逻辑缺陷、测试覆盖、安全弱点四个维度输出结构化报告。适用于代码合并前的自我检查或 MR 预审。 ---正文里我专门加了一个“审查节奏”的部分要求模型在每次审查前先列出它将要检查的文件清单再开始逐文件分析。这个设计的目的是防止模型突然“跳步”——如果它连审查范围都没跟用户对齐就开始写结论很容易出现漏文件或者评估偏差。另外我在正文里明确要求模型区分“阻断问题”和“建议优化”避免所有问题都一锅端增加团队 Review 的噪音。辅助脚本方面我写了一个scripts/scan_patterns.py作用是用正则匹配出常见的危险模式比如console.log残留、TODO 注释、password 这类硬编码然后把它扫描出的结果作为上下文传给模型结合分析。这一手很管用——模型本身不具备实时读取仓库全部文件的能力时脚本可以帮它快速抓取指定范围内的关键信号再展开判断。我用这种组合方式跑过一个小型前端仓库的审查效果比我单纯给模型发代码强很多。脚本负责客观、可重复的那部分扫描模型负责模式识别和语义判断各干各擅长的事。3.3 本地调试的方法别再一上来就指望模型表现完美写完 skill 不能直接拿去生产环境用必须先在本地做一轮“冒烟测试”。我的调试流程分三步第一步准备一个测试样本集样本里故意放入常见问题——一个变量命名不合规、一个可能的 XSS 注入点、一个缺少边界判断的函数。为什么要故意埋雷因为只有样本里已知有问题你才能验证 skill 有没有按预期把问题找出来。第二步用一个你会反复用到的对话启动方式去调用 skill。如果你用的是 Claude Code就直接在会话里输入“请用 code-review-helper 审查这个文件”观察它有没有正确加载 skill 文档。如果它完全没有触发优先怀疑 description 的表述和当前命令的语义距离过大。我碰到过一次把 description 里的“审查”改成“Review”再试触发率立刻提升。第三步检查输出的报告格式是否符合预期。如果模型漏掉了某个维度要么是 SKILL.md 里的步骤描述不够有存在感要么是示例部分没有覆盖这种情况。给每个维度配一个“输出示例”往往是修正漏检最有效的办法。4. Skills 如何调用 MCP 工具打通模型与外部世界的最后一公里4.1 MCP 在 skills 体系里的角色到现在还有人在问 skills 和 MCP 到底是什么关系。可以这样理解MCPModel Context Protocol相当于一个标准化的插头接口用来让 AI 模型能访问外部工具和数据源skills 则是“怎么用这些工具完成某项任务的方法论”。两者一个是基础设施一个是上层建筑。举个具体的场景代码审查 skill 希望读取 Git 仓库最近提交的变更记录这就需要一个能访问 Git 仓库的 MCP 服务器比如 GitHub MCP 或 Git 本地仓库 MCP。SKILL.md 里通过规范说明“本技能的依赖项包括读取 git diff 的工具”模型在执行时就会通过 MCP 协议去获取这些数据再结合技能里定义的审查流程做分析。所以 skills 跟 MCP 不是二选一而是叠加关系。Skills 告诉模型“做什么、按什么顺序做”MCP 解决“用什么工具、去哪拿数据”。4.2 在 SKILL.md 中声明 MCP 工具依赖的两种方式第一种方式是“在文档中指定依赖项”。你可以在SKILL.md的正文里增加一个## Requirements章节明确列出这个 skill 运行时需要的 MCP 工具比如这个技能需要以下 MCP 工具支持 - github-mcp-server用于读取 PR 信息和提交记录 - filesystem-mcp-server用于访问本地代码文件模型在阅读 SKILL.md 时如果发现当前环境中缺少这些工具它会主动提示用户配置。这是最稳妥的方案因为它把“依赖检查”前置了。第二种方式是“按需动态发现”。有些场景下你希望 skill 更轻巧不绑定特定 MCP 服务而是让模型在执行过程中根据任务描述动态选择合适的 MCP 工具。这比较灵活但不确定性也更大。我在自己的 skills 里优先用第一种因为团队协作时我需要行为可预期不能每次执行结果都因为临时工具切换而不稳定。4.3 一个调用 MCP 的真实过程示例以“前端设计稿还原”这个 skill 为例。它需要两个外部能力一个是读取图片文件通过 filesystem MCP另一个是以图生文即将设计稿内容转换为结构描述通过视觉模型或者 OCR 能力。我的 skill 流程是读取设计稿路径通过 filesystem MCP 确认文件存在。提取图片的基本规格比如宽高、主色值。结合图片分析生成 HTML 骨架。查询项目本地的 Tailwind 配置通过 filesystem MCP 读取配置文件生成符合现有设计体系的类名。输出完整组件代码并在结尾附上“需要人工确认的项”。实际跑出来效果比我预期好但也暴露了 MCP 调用环节的脆弱点图片文件如果过大模型在读取时可能超时。后面我加了一个约束——在 SKILL.md 里写明“如果图片超过 2MB请先提示用户压缩后再处理”这个坑就算堵住了。5. 避坑指南与常见问题排查实录那些文档里不会写的问题5.1 问题一skill 写了不触发或者触发得玄学这个是我见过最多的抱怨。排查思路其实有套路可循。先确认你的 SKILL.md 是否在正确目录下不同工具对 skills 目录的搜索路径不一样。Claude Code 会搜索.claude/skills/OpenCode 几乎用全局~/.config/opencode/skills/Cursor 则主要靠.cursor/skills/。如果你放错目录无论描述写得多好都不可能被加载。再检查描述的可检索性。描述里的关键词要和用户实际操作时表达的方式匹配。我画个简单的表对比一下状态description 写法示例实际触发效果过于宽泛“帮助处理网站问题”很难触发语义太散中等具体“修复网页兼容性问题”部分场景触发不稳定行为导向“当需要让页面在 Chrome/Firefox/Safari 下表现一致并修复样式错位时使用”较高概率触发行为可预期第三点是别忽略 frontmatter 的解析错误。我踩过一次坑frontmatter 里name写了带空格的值结果整个 skill 直接静默失败没有任何报错。建议所有字段都用简单的英文小写和连字符。5.2 问题二技能输出的质量不稳定时好时坏在技能方法论里有个被忽略的点模型执行 SKILL.md 的忠实度跟文档结构正相关。如果你的步骤描述是“分析代码逻辑”模型可能只泛泛而谈但如果改成“请按以下四步分析先列出所有函数签名再标注每个函数的外部依赖接着查找可能的内存泄漏点最后给出修改建议”模型的输出质量马上上一个台阶。另一个技巧是给关键输出节点增加“自检清单”。比如在文档末尾加一段## Self-Check 自检清单 在输出最终结果前请逐项检查 - [ ] 是否覆盖了所有分析维度 - [ ] 是否给出了可执行的下一步建议 - [ ] 是否标注了不确定的推测这相当于在模型推理链路末端加了一道质量门效果显著。我自己把这个方法用在了很多 skill 里都管用把它当成 SKILL.md 的标配也不为过。5.3 问题三上下文被 skill 文档撑爆对话越来越慢skill 文档不是越全越好尤其当你一个会话里同时加载三四个 skill 时上下文占用会迅速上升。解决方法有两个一是把不必要的长示例挪到references/子目录让模型按需加载而不是 SKILL.md 一开始就全部读取二是让 SKILL.md 充当“索引页”每个环节用一两行说明去哪里找详细资料。我个人现在的习惯是SKILL.md 只保留 frontmatter、执行流程、关键约束、输出格式说明、自检清单其他所有细节都丢到 references 和 assets 里。这样既保证了技能的完整性又不至于撑爆上下文。5.4 问题四git 协作时大家拿不到最新版 skillSkills 本质上也是代码需要版本管理。把 skills 放仓库里并且建立“目录内变更必须过 Review”的规矩可以避免团队里出现“我明明写了你为什么不执行”的互相甩锅。建议在 README 里标记每个 skill 的维护者和更新时间方便追溯问题。6. 进阶玩法针对不同场景定制 Skills前端、建模、测试、安全6.1 前端方向设计稿还原与移动端适配热词里反复出现“图片还原设计稿给前端开发”和“移动端的 skills 推荐”说明这是很多前端的刚需。我的经验是这个 skill 的成败主要取决于“约束是否明确”。在设计稿还原 skill 里我定义了以下硬性约束颜色值必须从设计稿中准确提取尺寸使用 rem 相对单位组件拆分必须符合项目的原子设计体系图片资源输出为 WebP 格式。然后才进入生成代码的步骤。把规范前置模型生成的东西才不会“看起来像但细节一团糟”。移动端适配的 skill 则重点约束断点和交互细节什么是移动端优先布局什么情况下使用手势代替点击事件图片如何做懒加载。这类 skill 很适合团队统一规范因为所有成员拉到的行为基线是一样的。6.2 数学建模与测试用例生成数学建模的 skills 热词也不低。一个完整的建模 skill 至少得包含问题定义是预测、分类还是优化、模型选型指导什么时候用线性回归、什么时候上深度学习、数据处理规范、结果评估格式。这个方向比较重建议用脚本辅助——比如写一个scripts/check_model_assumptions.py来验证数据是否满足模型的前提假设。测试用例生成的 skill 则更偏向流程控制。核心点是输出格式测试用例标题、前置条件、测试步骤、预期结果、优先级。我写的 skill 会把“需求覆盖度检查”放在最后一步要求模型对照原始需求逐项确认是否有遗漏场景这能明显降低漏测率。6.3 安全方向的一点提醒热词里有“渗透测试 skills”这让我多说一句做安全方向的 skill 时一定要把授权和边界写进 SKILL.md 的开头。这不是形式主义而是负责任开发的底线。我的安全类 skill 都会明确规定“只允许在授权目标范围内执行检测”、“输出结果中不得包含真实攻击载荷”、“所有操作必须可审计、可回滚”。技术上再厉害的东西失去了边界意识最后一定是坑自己。7. 收尾我踩过这么多坑后的真实体会如果你问我这轮 AI 编程浪潮里最值得学的是什么我会说是“结构化地把自己的专业能力封装给 Agent”的能力而 skills 就是目前最顺手的一把工具。它让我从“重复告诉 AI 怎么做”升级到“一次性告诉 AI 怎么按我的标准做”这在日常工作效率上的提升非常明显。最后再分享一个小技巧不管你写什么 skill都先拿它去处理一个你 100% 知道正确答案的旧任务。只有模型输出跟你的预期对齐了这个 skill 才算真正合格。我见过太多人写完 skill 直接上生产结果等它出了错再来调浪费的时间反而比手写 prompt 还多。好工具是拿来用的不是拿来供的多写几个、多踩几次坑你自然就知道什么样的 skill 才是好 skill。