最近不管是逛 GitHub 还是刷技术社区总能看到skills这个词冒出来而且后面往往还跟着 Claude Code、Codex、Cursor 这些 AI 编程工具的名字。很多朋友跑来问我skills 到底是什么是不是又一种提示词模板和 MCP 有什么关系到底怎么用才能让 AI 真的变聪明我花了几周时间把主流的 skills 玩法、官方文档、社区热门项目都过了一遍自己也从零手写了好几个能用的技能文件。这篇文章就从一个实际开发者的视角把 skills 的来龙去脉、目录结构、写法细节、常见坑一次性讲清楚。无论你是刚接触 AI 编程的新手还是已经用惯了 MCP 的老手这篇文章应该都能给你一些可以直接抄作业的参考。1. skills到底是个什么东西为什么突然这么火1.1 一个靠提示词堆出来的技能外挂要理解 skills先要理解一个痛点大模型本身很聪明但它在面对具体任务时经常会不知道怎么干活。比如你让它做一个前端页面还原它知道 HTML、CSS 的语法但不知道你的项目规范、不知道你习惯用哪种命名方式、不知道设计稿里的间距要不要精确到像素。传统的解决办法是把这些要求全部写进 system prompt。可问题是system prompt 越堆越长不仅消耗上下文窗口还会让模型变得什么都想管什么都管不好。不同任务的需求互相打架结果就是每个任务都做得马马虎虎。skills 的思路完全不一样它把怎么做某类任务的完整方法论拆成一个个独立的小文件夹。每个文件夹里是一个SKILL.md文件里面写清楚这个技能适用于什么场景、需要遵循什么步骤、有什么注意事项。AI 会根据用户当前的请求自动判断要不要加载这个技能文件。我把这个机制理解成给 AI 装了一抽屉的操作手册平时不打扰AI 正常发挥就好一旦遇到对应场景AI 自己会去抽屉里翻出那本手册照着上面的步骤干活手册之间互不干扰想加新能力就再塞一本进去。这和传统的把所有规则塞进 system prompt有本质区别。system prompt 是让 AI记住规矩skills 是让 AI按流程做事。模式识别、规则遵循、专业术语的运用都被封装进了技能文件里而不是散落在对话上下文中。1.2 skills和MCP、插件、Workflow的区别很多人一上来就把 skills 和 MCP 搞混这俩确实是当前 AI 工具链里最容易混淆的两个概念。我用一个生活化的类比来解释MCP 是给 AI 装手的让 AI 能调用外部工具、读取数据、操作文件skills 是给 AI 装脑子的让 AI 知道遇到某类事情时按什么流程、用什么标准去做。举个实际的例子。假设你给 AI 配了一个网页截图的 MCP 服务。MCP 解决了AI 能不能截图的问题但 AI 截完图之后要干什么、怎么分析布局、怎么把设计还原成代码MCP 管不着。这时候就需要一个 skills 文件里面写清楚拿到截图后先识别布局结构再提取颜色和字体然后生成对应的前端代码。MCP 提供能力skills 提供方法论。两者配合效果远胜于单独使用任何一个。至于插件和 Workflow那又是另一个维度的事了。插件通常自带代码逻辑能直接执行比较复杂的本地操作Workflow 更像是预设好的多步骤流程比如读取文件→调用 API→生成报告。skills 本身不包含可执行代码虽然可以引用外部脚本它是纯提示词级别的指导文件只是指导的内容比普通 prompt 更结构化、更专业。为了让你一眼看懂区别我整理了一个对比表格维度skillsMCP插件Workflow核心作用告诉 AI 怎么做让 AI 能做什么扩展 AI 的本地能力预设多步骤执行流程是否含代码一般不含可引用脚本含服务端实现含插件代码视实现而定触发方式AI 根据请求自动判断显式调用或自动调用显式启用显式触发修改成本改 Markdown 即可需要写服务需要写代码需要配置流程依赖关系可调用 MCP 工具被 skills 调用可与 skills 配合可与 skills 配合1.3 什么样的场景真正适合用skills我实测下来skills 在下面这几类场景里收益最明显第一类是高频但流程固定的任务。比如我做前端开发时经常需要把设计稿转成页面。这个流程其实高度标准化分析布局、提取设计令牌、按项目规范生成组件、输出响应式样式。把这些步骤写成一个前端还原类的 skillsAI 每次做出来的页面质量都稳定在 80 分以上不需要我反复纠正。第二类是需要专业领域知识的任务。比如数学建模、学术研究、测试用例设计。这些任务光靠大模型的通用知识是不够的需要特定的分析框架和质量标准。把框架写在 skills 里相当于给 AI 做了一次专业培训。第三类是需要多步操作且容易遗漏细节的任务。比如代码审查、渗透测试这里仅指授权范围内的安全审计、数据分析。这些任务如果让 AI 自由发挥它往往会漏掉关键步骤。有了 skills 的步骤约束AI 就会按清单一步步执行漏检的概率大大降低。反过来那些一次性的、探索性的、需要大量实时信息的任务不太适合用 skills。这种场景更适合直接对话或者配一个检索类的 MCP。2. 从零手写一个能用的skills直接照着抄2.1 准备工作目录结构和最小文件先说结论一个最简 skills 只需要一个目录加一个 Markdown 文件。以 Claude Code 为例默认的技能目录是.claude/skills/。在这个目录下每个子文件夹代表一个技能文件夹名字就是技能名里面必须有一个SKILL.md文件。整体结构长这样.claude/ └── skills/ └── frontend-design-recovery/ ├── SKILL.md ├── references/ │ ├── project-conventions.md │ └── color-palette-rules.md └── scripts/ └── extract-colors.pySKILL.md是核心references和scripts是可选的辅助资源。references目录里放一些补充文档AI 在需要时会去读取scripts目录里放一些可执行脚本配合 MCP 或者本地命令使用。对于 Codex 来说路径逻辑类似一般也是放在.codex/skills或者项目根目录的AGENTS.md关联文件里。不同工具有各自的约定但整体思路是一致的。我建议你优先掌握 Claude Code 的规范因为它的 skills 机制最成熟、社区生态最丰富懂了这一套之后迁移到其他工具成本很低。注意技能文件夹的名字不要乱起最好用英文短横线命名。一方面避免编码问题另一方面 AI 对英文命名的识别更加稳定。2.2 SKILL.md的写法与frontmatter细节SKILL.md看起来就是个普通的 Markdown 文件但它有个关键部分开头的 YAML frontmatter。这个元信息块是 AI 判断该不该激活这个技能的依据写得好不好直接影响技能的触发准确率。一个标准的 frontmatter 长这样--- name: frontend-design-recovery description: 仅在用户需要将设计稿/图片还原为前端页面代码时使用。当用户提供截图、设计图、Figma 链接时逐步完成布局分析和代码生成。 ---name字段是技能的唯一标识必须和文件夹名一致。description字段是最重要的它相当于技能的使用说明书。AI 每次收到用户消息都会快速扫一遍所有技能的 description判断当前请求是否匹配。我踩过一个大坑最开始我把 description 写得特别宏大比如处理所有前端相关任务。结果 AI 在写一个简单的函数组件时也把这个技能激活了加载了一堆不必要的步骤约束反而限制了发挥。后来我把范围收紧到仅在用户提供图像或设计稿时使用触发准确率立刻上去了。描述里还要写清楚使用条件、适用范围、主要步骤关键词。你甚至可以这样写当用户消息中出现截图设计稿还原页面切图等词汇时考虑使用本技能。这相当于给 AI 一个明确的开关。2.3 一份完整可用的skills示例前端设计稿还原光说理论太虚我给你看一个我实际在用的前端设计稿还原技能。这个技能解决的是给我一张设计图帮我写页面代码的需求也是社区里被搜索最多的 skills 方向之一。SKILL.md的正文我按功能分成了几大块。首先是任务描述和目标让 AI 明确知道完成的标准是什么# 前端设计稿还原 将设计稿截图、设计图或 Figma 导出图还原为高质量前端代码。 ## 开始之前 - 确认是否了解项目当前使用的框架React/Vue/小程序等。 - 如不确定先询问用户。 - 检查是否有现成的组件库和设计令牌design token优先复用。 ## 执行步骤 1. 用图片分析能力识别设计稿的整体布局列出主要区块。 2. 提取颜色、字体、间距、圆角等设计属性整理为设计令牌。 3. 按区块从上到下、从左到右构建页面结构。 4. 使用语义化标签并保证样式尽可能还原设计稿细节。 5. 输出页面前先自查布局是否完整、颜色是否一致、是否存在冗余代码。然后是输出格式的要求。我发现如果不明确输出格式AI 会自由发挥可能直接给你一个巨大的单文件也可能拆得乱七八糟。我加了这样一段## 输出要求 - 组件代码使用 TypeScript。 - 样式方案优先使用 Tailwind CSS若项目未使用则退化为 CSS Modules。 - 每个组件文件不超过 200 行超出则拆分。 - 输出时先给文件结构概览再按文件逐个输出内容。 - 关键设计令牌颜色、字体、圆角需在注释中标注来源。最后是常见边界和禁止事项。这一步很关键因为 AI 在不了解约束时往往会做出多余的事情## 边界与注意事项 - 不添加设计稿中不存在的装饰元素。 - 不擅自引入新的依赖库。 - 不需要实现交互逻辑除非用户明确要求。 - 如果设计稿信息不足如缺少移动端适配样式主动询问不猜测。写完这个文件后我实际测试了一个响应式后台管理页面的还原AI 的产出质量比我手动写提示词时稳定得多。它真的会先去识别布局、提取颜色、再生成组件而不是像以前那样一上来就堆代码。2.4 调试与验证判断skills是否生效写完 skills 不等于能用你还需要验证它到底有没有被 AI 正确识别和触发。我的验证方法分三步第一步用能触发此类任务的问题去问 AI比如帮我把这张图还原成移动端页面。然后在对话中观察 AI 的行为——它有没有按技能文件里的步骤走。如果它完全没提步骤或者直接自由发挥说明技能没有被加载可能是 description 写得不对也可能是目录位置不对。第二步用不该触发的问题去测试边界。比如你给前端设计稿还原技能提问帮我写一个防抖函数如果 AI 还是调用技能说明 description 写得太宽泛需要收紧。第三步查看工具的运行日志。Claude Code 在 verbose 模式下会输出加载了哪些技能文件Codex 也有类似的调试选项。通过日志你能确认技能文件是否被正确解析有没有语法错误。我还习惯在技能文件里加一个版本号和修改记录--- name: frontend-design-recovery description: 仅在用户需要将设计稿还原为前端代码时使用... version: 1.0.2 last-updated: 2025-05-10 ---版本号的意义不只是记录更重要的作用是当 AI 加载技能时它能知道这个技能是新的还是旧的。如果你在调试中改了内容但 AI 的行为没有变化很可能是因为它缓存了旧版本这时候版本号就是你判断缓存有没有刷新的依据。3. 把skills用出水平进阶技巧与场景扩展3.1 给skills配工具call MCP的正确姿势skills 和 MCP 最好的用法是组合。我自己最常用的一个组合就是让 skills 调用网页检索类的 MCP 工具。比如我写过一个最新技术调研类的 skills它的流程是拆解调研主题→搜索最新资料→阅读网页内容→整理成报告。这个流程里搜索和阅读网页需要 MCP 能力而拆解主题整理报告需要 skills 提供方法论。具体实现上在技能文件的步骤里明确写出调用 MCP 的方式。不同的工具有不同的调用语法Claude Code 里通常是直接用mcp__工具名这样的标记来调用。我在技能里是这么写的## 执行步骤 1. 分析用户提出的技术主题拆解出 3-5 个关键子话题。 2. 逐个使用 mcp__fetch 搜索子话题的最新资料。 3. 阅读搜索结果时优先筛选官方文档和知名技术博客。 4. 综合多个来源的信息输出一份带引用链接的调研报告按背景-现状-趋势组织。加了这一步之后整个调研流程的自动化程度明显提高。以前我都要自己先搜一圈再让 AI 总结现在直接一句话就能得到带交互过程的完整报告。注意skills 文件本身不负责实现 MCP 服务它只是告诉 AI在哪个环节使用哪个工具。这个过程就像给一个熟练工人配了一套专用工具。工人AI有了操作手册skills又有工具箱MCP自然能按标准流程把手上的活干好。3.2 多skills之间的协作与依赖在实际项目中单靠一个 skills 往往不够。比如从需求文档生成前端页面这个场景其实涉及两个技能一个是需求拆解一个是设计稿还原。玩到后面你会自然面临一个问题多个技能之间怎么协调我先说结论尽量让每个 skills 只做一件事。如果一个技能文件里塞了太多目标description 很难写好AI 的触发判断也会混乱。实际操作中我通常这样设计多技能的协作每个技能只解决一个类型的任务如果任务 A 需要用到任务 B 的能力在技能 A 的步骤里明确写先调用技能 B 完成某某步骤技能的 description 里不要互相引用太多避免 AI 加载了 A 之后又连锁加载 B把一堆技能都塞进上下文。我还试过在 references 目录里放一个workflow-dependencies.md把技能之间的调用关系写清楚。比如设计稿还原在执行步骤 3 之前可以先查看component-library.md确认可用的组件。这样 AI 在需要时会主动去读补充文档而不是一上来就全量加载。多个技能配合时最怕的一个问题是两个技能的要求互相冲突。比如一个技能要求所有样式内联另一个技能要求必须使用 CSS ModulesAI 就会无所适从。所以我建议在编写技能时把不可妥协的硬性要求和可以动态调整的软性建议分开写AI 可以根据实际情况选择遵循哪一个。3.3 通用领域skills推荐与改造思路社区里已经积累了不少高质量的 skills 资源下面这几个方向我个人实测下来非常值得关注前端开发类设计稿还原、组件代码生成、移动端页面适配、网页性能优化检查。学术研究类文献综述、论文结构梳理、学术写作规范检查。数学建模类问题分析、模型选型、报告撰写、数据可视化方案推荐。测试类测试用例生成、边界条件分析、自动化测试脚本编写。安全审计类仅限授权范围内的代码安全审查、风险点识别、修复建议输出。很多人下载了别人的 skills 文件后发现效果不好原因常常不是文件本身不行而是没有针对自己的项目做改造。举个最常见的例子社区里流传的前端代码生成类技能大多默认你用的是 React 加 Tailwind CSS。但如果你实际项目用的是 Vue 加 Element Plus这套技能的效果就会大打折扣。我的改造方法是下载一个技能的 SKILL.md 之后先检查它的硬编码偏好。把技术栈相关的内容全部改成变量或者直接在文件里注明本项目使用 Vue 3 组合式 API样式使用 Element Plus布局使用栅格系统。AI 看到这些说明后生成的代码风格就会自动贴合你的项目规范。改造完之后记得把项目特有的规范沉淀到 references 目录里。比如你的项目要求所有 API 请求必须走统一封装那就在 references 里写清楚同时让主文件在步骤中引用这份规范。这样维护起来比把规范直接埋在步骤里更清晰。4. 踩坑记录与排查手册4.1 常见问题速查表我写了不少 skills 文件也帮朋友排查过各种问题。这里整理了一张速查表基本覆盖了新手最容易遇到的几种情况问题现象可能原因解决方案AI 完全不理会技能文件目录放错或文件名不叫 SKILL.md检查.claude/skills/技能名/SKILL.mdAI 在不需要的时候也加载技能description 写得太宽泛收窄触发条件明确限定场景AI 该用技能但没触发description 里的关键词与实际请求不匹配补充常见触发词和同义表达技能生成了但效果很差步骤不够具体或缺少项目规范补充执行细节引用项目规范文档修改后行为没变化工具缓存了旧版本增加版本号或重启会话清除缓存多个技能一起加载导致冲突技能职责边界不清晰合并或拆散技能让每个技能职责单一引用 MCP 工具时报错调用语法不符合工具要求确认对应 MCP 的调用格式和使用限制4.2 我在实际项目里踩过的几个坑第一个坑以为 skills 能替代上下文管理。有一次我写了一个全栈项目开发的技能里面塞了大量步骤想着 AI 加载之后就能自动完成从数据库设计到前端页面的所有工作。结果那些步骤占据了大量上下文AI 加载技能之后反而没力气干活了。教训是技能文件本身不宜太长最好控制在 60 行以内复杂流程靠 references 里的辅助文档拆解。第二个坑description 里堆砌太多同义词。我看网上有些教程说关键词写越多越好就照着把设计稿、原型图、UI 图、视觉稿、PSD、Figma 全写进去了。结果测试时发现AI 在用户提到UI时激活了这个技能但用户其实只是随口聊一句 UI 设计趋势。后来我把描述改成了结构化表达明确适用的任务类型、触发条件、以及激活后的主要行为效果明显改善。第三个坑完全没有版本管理。skills 文件改起来很容易但改坏了想回退就麻烦了。我现在把整个.claude/skills目录都纳入了 Git 管理每次修改都提交一个版本。如果 AI 行为异常直接git diff看历史记录定位到具体改动效率极高。第四个坑忽视工具差异。同一个 skills 文件在 Claude Code 里运行良好不代表在 Cursor 或者其他工具里也没问题。不同工具对技能文件的解析机制、加载方式、调用语法都有差异。跨工具使用前一定先读目标工具的官方文档确认路径、文件格式和调用方式。4.3 判断一个skills好坏的标准写多了自然会有手感。我总结了一套评价 skills 文件好坏的维度分享给各位参考触发准确率该触发时触发不该触发时不触发这是第一优先。步骤可执行性每一步对 AI 来说都足够明确不是那种好好分析之类的废话。输出稳定性连续测试多次产出质量波动不大。修改可维护性文件结构清晰想改一个环节不用动整个文件。上下文开销文件长短适中不占用过多上下文窗口。如果一个技能在这五个维度上都做得不错那基本就是个能实战的技能了。我在实际迭代中还会经常做一件事把 AI 之前的不理想输出拿出来反向倒推看是哪个环节缺了约束。比如 AI 生成的组件没有按项目规范使用枚举类型我就会在技能的输出要求里补一句。这种小步迭代比一次性想写一个完美技能靠谱得多。最后再分享一个小技巧写完一个技能后不要急着用复杂任务去测。先用一个小而精的样本任务跑一遍确认步骤走通了再拿复杂任务做压力测试。这就像写代码先跑单元测试再跑集成测试能省很多排查时间。我自己每一次新增或修改技能都会先跑一遍最小用例确保行为符合预期后才放进日常项目里使用。
