1. 为什么每个重度用户最后都会走到“Skills化”这一步过去半年里我的效率拐点不是换了某个更强的模型而是彻底搞明白了一个机制——Agent Skills。在那之前我用 Claude Code、Codex 这类工具干活的状态基本可以概括为“每次都在面试一个新实习生”同一个项目的前端规范要重新贴一遍单元测试的格式要求要重新描述一遍代码审查的侧重点要重新叮嘱一遍。AI 不是不会做它是每次都“忘了上次怎么做”然后发挥不稳定。后来我接触到了 Skills这个概念在 GitHub 上被一堆仓库反复提及比如 baoyu skills、superpower skills、mattpococks skills还有吴恩达专门讲 Agent Skills 的教程 PDF。大家口径一致地在讨论一件事把“临时对话”变成“永久能力”。我一开始以为这只是把提示词存成文件试过之后才发现完全不是同一个量级。提示词是一张便签Skills 是一本带目录的操作手册AI 到点会自动翻开对应那一页。这篇内容会把这几个月我在 Skills 上的实操经验完整写出来包括它和普通提示词、MCP 工具到底什么关系主流工具各自的实现方式以及我手写一个“图片还原设计稿给前端开发”的 Skills 的全过程。适合三类人看一是正在折腾 Claude Code、Codex、Cursor 但觉得每次对话都要重复说需求的二是已经知道 Skills 但写出来的东西效果忽好忽坏的三是想弄清楚 Skills 和 MCP 该怎么配合的。我会把踩过的坑也都摆出来尽量让你少走弯路。2. Skills、普通提示词和 MCP 到底是什么关系三者的边界与配合2.1 三者的定位知识、动作与临时指令要理解 Skills首先得把 AI 编程助手的工作方式拆开。现在主流的 Agent 工具基本都遵循一个模式模型负责思考和决策工具负责执行动作上下文里的文本负责传递约束。Skills、MCP、提示词这三样东西正好对应了三个不同层面。普通提示词是“一次性指令”。你在对话框里输入“帮我把这段代码改成 TypeScript”这句话只对当前这轮对话生效关掉对话就没了。它的特点是灵活但也意味着每次都要重新交代背景。MCP 是“外部工具接口”它让 AI 能调用文件系统、浏览器、数据库、设计软件等真实世界的动作。你可以把它理解成 AI 的手和工具没有 MCPAI 只能靠文本想象有了 MCPAI 才能真正去操作点什么。Skills 则是“可复用的专业技能包”它封装的是一个人在某类任务上的完整做法——什么时候做什么、按什么顺序做、做到什么标准算完。我用一个生活化的类比来解释假设你请了一个私人助理。提示词是你每次临时交代的“今天帮我订一家川菜馆”MCP 是助理手里的手机和银行卡用来真正完成订餐动作Skills 则是助理脑子里那套“如何根据客人偏好选餐厅、如何确认预订、如何处理突发状况”的标准流程。三者配合才构成一个靠谱的助理。只给提示词助理没有流程每次全凭发挥只给 MCP助理有工具但不知道什么时候用只有 Skills助理知道该怎么做但没有工具落地。2.2 SKILL.md 到底长什么样一个标准 Skills 的解剖理解了定位之后我们来解剖一个标准的 Skills 目录结构。目前社区里比较统一的格式是每个 Skill 独立成一个文件夹文件夹里放一个名为 SKILL.md 的 Markdown 文件里面用 YAML frontmatter 写元信息正文写具体操作指令。skills/ ├── design-to-code/ │ ├── SKILL.md │ ├── examples/ │ │ ├── sample-input.png │ │ └── expected-output.html │ └── assets/ │ └── tailwind-cheatsheet.md └── test-case-generator/ └── SKILL.mdSKILL.md 的 frontmatter 里最关键的是 name 和 description。name 是这个 Skill 的唯一标识description 则写得越精确越好因为它是 AI 判断“当前任务是否该触发这个 Skill”的依据。我曾经图省事把一个测试用例生成 Skill 的 description 写成“生成测试用例”结果它在 AI 处理任何涉及“测试”二字的对话时都会触发甚至包括“测试一下网络连接”这种完全不相关的请求。后来我改成了“当用户要求为 TypeScript 函数或 React 组件生成单元测试时使用”误触发率骤降。正文部分则应该清晰列出执行步骤、输入要求、输出格式、禁止事项。这套结构和人写 SOP标准作业程序很像只不过阅读对象是 AI 而不是人。2.3 Skills 调用 MCP 的正确姿势先决策后执行Skills 和 MCP 的关系不是替代而是协作。一个常见的场景是我写了一个“数学建模 Skills”它知道完整的建模分析流程但真正的数据导入和可视化操作需要调用 Python 环境相关的 MCP 工具。在这种情况下SKILL.md 里要做的是两件事明确告诉 AI“在执行第 3 步数据预处理时必须调用 python_exec 这个 MCP 工具”同时说明在调用前需要检查哪些前置条件。踩过的坑是早期我写的某个 Skill 让 AI 调用一个并不存在的 MCP 工具结果 AI 锲而不舍地尝试了七八次每次都报“工具不存在”白白浪费了大量 token 和时间。后来我在 SKILL.md 里加了“依赖检查”这一步骤执行前先列出所需的 MCP 工具清单并检查当前环境中是否可用不可用就直接告知用户去配置而不是反复试探。这个小小的改动让我那些依赖外部工具的 Skills 稳定了非常多。3. 主流工具里的 Skills 生态横向对比Claude Code、Codex、OpenCode、Cursor3.1 各家的实现方式和目录规范既然要做 Skills第一步当然是选对落地的平台。目前市面上主流 AI 编程工具对 Skills 的支持程度差异很大我用一个表格来对比各家的情况都是我自己实测过的。工具Skills 机制目录/配置位置生态成熟度我的实测体验Claude Code原生支持官方文档有明确规范.claude/skills/下放 Skill 文件夹最成熟社区资源最多触发准确率高对复杂任务的执行稳定性最好Codex部分支持结合 AGENTS.md 使用项目内AGENTS.md skills 目录起步阶段正在快速演进Skills 的自动触发逻辑还在调整好用的很多OpenCode社区支持opencode.json配置中上GitHub 上有不少仓库适合喜欢自己折腾的人灵活性高Cursor规则 项目 Notes 近似替代.cursor/rules等前端生态非常丰富不完全等同于 Skills但对前端开发场景很够用3.2 为什么 Claude Code 的 Skills 生态最热从我的实际使用频率来看Claude Code 的 Skills 机制是当前最成熟的这也是为什么我们在 GitHub 上搜 skills 相关仓库十有八九都是 Claude Code 相关。它最核心的优势在于自动触发机制做得足够好AI 会根据当前对话内容判断匹配哪个 Skill并在需要时主动加载而不是要求用户手动“启用”。这种体验上的差别很大——手动启用意味着你仍需要知道“有这个技能存在”而自动触发则真的像给 AI 装上了一套潜意识。它官方文档里给的定义也最清晰Skills 是由用户定义的一组指令用于扩展 Claude 的能力。一个 Skill 可能指导模型如何分析代码库、如何按特定模式编写代码、或者何时使用某个 MCP 工具。换句话说它就是给 Agent 写的“岗位说明书”。3.3 跨工具迁移一次编写多处运行的可行性很多朋友会问我在 Claude Code 里写的 Skill 能不能拿到其他工具里用我的结论是能但不能无脑复制。因为各家对 SKILL.md 的解析差异不大核心的操作指令文本是通用的但 frontmatter 里的字段定义、description 的触发逻辑、对上下文自动加载的机制都不一样。我试过把一个 Claude Code 的 Skill 原封不动丢到 OpenCode 里个人信息和流程部分没问题但触发描述因为格式不一致被忽略了效果大打折扣。如果你需要在多个工具之间迁移建议的做法是把 Skill 的操作正文写成“工具无关”的纯指令格式然后在各平台单独维护一套 frontmatter。这样你只维护一份核心内容不同的平台自己认领自己的“外壳”。虽然还是有一定维护成本但比每个平台重写一遍强太多。4. 手写第一个 Skills从需求分析到可复用的完整过程4.1 选定场景为什么先从“图片还原设计稿”入手理论讲多了容易飘我们直接上手写一个。我选择的案例是“图片还原设计稿给前端开发”这也是社区里呼声很高的一个 Skill 类型。它之所以适合作为练手案例是因为任务流程固定、判断标准清晰、输出物明确给 AI 一张 UI 设计截图它需要输出对应的前端 HTML/CSS 代码。这对 AI 来说是一个“标准能力”但对人类来说每次描述需求都很繁琐天然适合做成 Skills。实际场景是这样的我有时候会收到设计师发来的一张页面效果图让我做成可交互的前端页面。以前我的做法是把图片直接发给 Claude Code然后手动输入一段很长的 Prompt“请仔细分析这张图片的布局结构、颜色、字体、间距然后用 HTML Tailwind CSS 还原一个像素级接近的页面要求语义化标签、响应式布局、无障碍属性……”这段话我前后复制粘贴了不下 20 次。现在这个场景被我完全 Skill 化了。我在.claude/skills/design-to-code/下创建了 SKILL.md 文件所有的要求、步骤、输出规范全部写在里面以后只需要说一句“把这张图还原成前端页面”AI 就会自动按我的要求执行完整流程。4.2 编写 SKILL.md 正文的完整过程以下是我当时编写的 SKILL.md 核心内容删掉了一些项目特定的细节保留了通用部分供你参考--- name: design-to-code description: 当用户提供一张网页或移动端 UI 设计截图图片文件并要求将其还原为 HTML/CSS 前端代码时使用。尤其适用于图片为设计稿、效果图或原型图的情况。 --- # 图片还原设计稿为前端代码 你的任务是将用户提供的设计图转换为高质量的前端代码。 ## 前置条件 - 如果用户没有提供图片路径先询问用户提供图片不要凭空编造。 - 输出技术栈HTML5 Tailwind CSS除非用户有另外说明。 ## 执行步骤 1. **分析图片整体结构** - 识别页面的布局框架头部、导航、主体内容区、侧边栏、底部等。 - 用文字描述出页面的信息架构确保理解完整。 2. **提取设计 Token** - 从图片中识别主色、辅助色、文字颜色列表HEX 格式。 - 识别字体大小层级和字重层级。 - 识别间距规律4px 的倍数、8px 网格等。 - 识别圆角、阴影、边框等视觉细节风格。 3. **搭建 HTML 结构** - 使用语义化标签header、nav、main、section、article、aside、footer。 - 为关键容器添加具有含义的 class 名称。 4. **实现样式** - 优先使用 Tailwind 实用类完成布局和视觉表现。 - 复杂造型特殊渐变、装饰元素可以用内嵌 CSS 补充。 - 使用 flex 或 grid 完成响应式布局在 375px、768px、1440px 三个断点下都要合理。 5. **补充细节** - 为图片元素添加 alt 文本。 - 为可交互元素按钮、链接添加 hover/focus 状态。 - 保持代码整洁删除无用注释。 ## 输出格式 - 输出一个完整的 HTML 文件CSS 通过 Tailwind 的 CDN 引入。 - 在代码块之前用一段话概括布局结构分析结果、提取的颜色与字体 Token、你做了哪些响应式处理。 ## 禁止事项 - 不要在没有图片的情况下猜测结构。 - 不要为了“追求还原”而使用绝对定位堆砌界面优先使用文档流和布局属性。 - 如果图片里的设计存在明显不合理之处如文字截断、对齐错乱按合理设计修复并在概览中说明。现在看这个文件它其实就是在把“一个有经验的开发看到设计图后的思考过程”给显式化、步骤化。第一次写的时候我没这么清晰是试了几轮之后才迭代成这个版本的。4.3 调试过程中的三个实际问题写完之后并不是一劳永逸我在实际使用中碰到了三个具体问题正好对应了三个经典教训。第一个问题是 AI 偶尔会在没有图片的时候直接编造页面结构。它可能在对话历史里见过别的页面截图就试图“参考”一下。我把这个问题反馈到了文件里添加了前置条件中“不要凭空编造”的明确指令并强调“先询问用户提供图片”。加了这句之后零误诊。第二个问题是输出的代码里 Tailwind 和自定义 CSS 混用严重有时候一个组件用了十一个 class可读性极差。我进一步在“实现样式”步骤中增加了“优先使用 Tailwind 实用类”和“保持代码整洁”两条约束情况立刻改善。AI 不是不知道这些原则而是你在 Skill 里没写它就默认按自己最舒服的方式来。第三个问题是响应式断点不完整。它经常只做桌面端或者只做移动端我不得不在输出格式里硬性要求它写清楚“你做了哪些响应式处理”。有了这个显式要求之后AI 在输出时就会主动检查自己是否满足了不同断点下的表现从而带着“责任感”去处理。4.4 真实效果对比Skill 化前后的差异我拿同一张设计师发来的电商活动页面效果图分别测试了两轮。第一轮是传统方式我手动输入了一段详细的 PromptAI 确实给出了一个能看的页面但存在三个问题间距不统一、按钮 hover 状态没有、最高层级的框架用了过多的固定宽度。第二轮是直接说“把这张图还原成前端页面”AI 自动触发了 design-to-code 这个 Skill产出页面在结构、Token 提取、响应式表现上都明显更规范而且我全程没有说一句多余的话。这就是 Skill 化的价值——不是让 AI 从“不会”变成“会”而是让 AI 从“会但不稳定”变成“每次都会”。如果你有这个场景的重复需求这个 Skill 能帮你省下的是每次演示前那一长串“教师爷念经式”的说明。5. 写好一个 Skills 的“手感”触发条件、输出约束与迭代节奏5.1 高质量 SKILL.md 的黄金结构通过大量阅读社区里口碑好的 Skills 仓库比如 baoyu skills、superpower skills我总结出一份高质量的 SKILL.md 通常包含六个部分清晰的身份定位、精确的触发描述、明确的前置条件、有序的执行步骤、具体的输出约束、避免踩坑的禁止清单。这六个部分不是随便凑出来的每一段都对应一个实际问题。身份定位让 AI 知道“我是谁”触发描述让 AI 知道“什么时候该调用我”前置条件防止 AI 在不合适的场景强行使用执行步骤保证输出质量的下限输出约束让结果符合你的预期格式禁止清单则消除 AI 最容易犯的几种错误。这很像给新员工写的入职手册要有岗位职责、工作边界、SOP 和红线。5.2 触发条件为什么要反反复复打磨很多第一次写 Skills 的人最看重的往往是执行步骤但我个人经验是触发描述description才最需要打磨。因为这个字段决定了 AI 在什么情况下会自动“想起”这个 Skill。写得太宽泛AI 会频繁误触发写得太窄AI 又会在真正需要的场景中“忘记”使用它。我打磨触发描述的习惯是收集平时对话里我会怎么提出这类需求的自然语言。比如“帮我把这张图变成代码”“把这个设计稿还原成页面”“写一个和这张图一样的页面”。把这些说法都融进 description 里AI 就能精准识别。千万不要只写官方腔的“convert design image to frontend code”那是给搜索引擎看的不是给模型看的。5.3 给 Skills 写“测试用例”是怎么回事社区里一些成熟的 Skills 仓库会专门设置一个 examples 目录里面放输入样例和期望输出的对照。这个做法非常值得学。给 Skill 写示例意义有两个一是帮助 AI 更好地理解 Skill 的预期输出二是方便你自己回归验证。每次改了 SKILL.md 之后重新跑一遍 examples 里的场景就能快速发现改动是提升了还是削弱了整体效果。比如我给 design-to-code 这个 Skill 建立了一个 examples/sample-input.png 和 expected-output.html每次调整指令后都会重新生成一遍对比当前输出和期望输出的差距。这种回归测试的思路是从软件开发里借过来的但放在 Skills 上出奇地有效。5.4 迭代节奏不要一次性追求完美而是让它在使用中进化我对 Skills 的态度是“写一个粗糙版本然后用起来在真实使用中迭代”。第一版通常只需要覆盖 80% 的核心流程剩下的 20% 在遇到实际问题时再针对性修补。这个方法最适合初学者上手快正反馈及时。等你自己积累了一个 Skills“军火库”之后就能体会到为什么社区里那些资深玩家会说“Skills 是 AI Agent 时代的插件系统”。6. 我踩过的 Skills 坑四个翻车现场和修复实录6.1 坑一Skill 写得太贪心想一个 Skill 通吃所有框架第一个让我翻车的 Skill 是“前端组件生成器”。我一开始把 React、Vue、原生 HTML、Angular 全部塞进了一个 Skill期望 AI 能够“随机应变”。结果就是 AI 每次都在框架选择上纠结输出风格忽 React 忽 Vue同一个项目里产生了两种互不兼容的组件风格。修复方案很朴素拆。一个 Skill 只绑定一种技术栈。现在我有“react-component-generator”“vue-component-generator”“html-tailwind-generator”三个独立 Skill触发条件清晰输出风格稳定。这个教训让我意识到 Skills 的第一原则是“单一职责”一个 Skill 解决一个问题比大而全重要得多。6.2 坑二约束过死AI 失去判断力和“贪心”相反的另一个极端是“控制狂”。我有一次写测试用例生成 Skill把代码覆盖率、命名规范、文件路径全部写死还要求 AI“必须使用 Mock 库 A”。结果在一个实际项目中被测函数依赖的库导致 Mock 库 A 完全不适用AI 仍然严格按照 Skill 的要求引入了一个没法工作的依赖最后生成的测试文件根本无法运行。修复方式是在 Skill 里加入“合理性判断”层当 Skill 的某个要求与当前项目事实冲突时AI 应暂停执行向用户说明冲突点并提出替代方案而不是机械地遵守。自那以后我每个 Skill 都会刻意写一句“如项目实际情况与本流程冲突说明冲突并征询用户意见”。这个细节让我的 Skills 从“僵化的说明书”变成了“有判断力的助手”。6.3 坑三忽略上下文损耗Skill 变成 Token 黑洞Skill 的本质是往上下文里塞指令如果 SKILL.md 写得过长每次触发都会消耗大量 token。我见过有人把一个 Skill 写了 5000 多字里面大段大段地复制了官方文档。实测下来每次触发光读 Skill 就要消耗 2000 多 token遇到复杂任务中途上下文就快满了反而导致其他必要的信息没地方放。我的修复思路是“瘦身 外置详档”SKILL.md 只保留结构化的操作步骤和关键约束那些比较长的背景知识、代码风格参考、模板示例全部放到 skill 目录下的其他参考文件里并在 SKILL.md 中注明“如需更详细的示例请阅读 examples 目录”。这样 AI 可以根据实际需要去决定是否加载参考文件而不是被动地一次性全吞进上下文。6.4 坑四Skill 和 MCP 的配合出现“死循环”最后一个坑是 Skills 调用 MCP 时的稳定性问题。我早期写过一个工作流 Skills其中一步需要调用浏览器 MCP 工具去抓取网页内容但 MCP 工具所在的服务偶尔会超时。AI 的默认行为是重试重试失败后再重试最多能连着失败七八次白白耗掉几百秒。我甚至一度怀疑是 Skill 写错了后来一条条排查才发现是 MCP 工具本身不稳定。修复方法是双管齐下一方面在 SKILL.md 里为 MCP 调用步骤加上了“失败两次即停止并报告错误”的约束另一方面我去搞清楚了那个 MCP 服务为什么会超时修复了根本原因。这个经历给我的启发是Skills 是逻辑层MCP 是执行层逻辑层要学会善待执行层。别让 AI 做无谓的牺牲性重试。6.5 一份给新手的“避雷清单”把上面这些经验浓缩成一份清单方便你写自己的 Skills 时对照检查。第一一个 Skill 只干一件事不要大而全第二触发描述要包含真实对话里的自然说法别写官话第三前置条件里一定要写“如果没有 xx 就询问用户不要编造”第四输出约束要具体到格式而不是“高质量”第五给 Skill 配 examples 和回归测试第六定期检查触发时的 token 消耗控制文件体积第七当 Skill 要求与现实冲突时给它一个“暂停且询问”的出口。我从最初看着 Skills 一脸懵到现在自己维护了十来个高频使用的 Skill最大的感受是这个机制真正把 AI 编程助手从“对话工具”变成了“知识传承系统”。你写的每一个 Skill都是把你这个人在某个具体任务上的判断力、流程和标准沉淀成了一个可重复调用的资产。同一个团队里如果大家一起维护一套 Skills新成员上手项目的时候AI 的输出质量就等于团队里最资深那几个人的平均水准。最后分享一个小习惯。我会在每个 Skill 的末尾加一个“调试模式”说明当用户回复“--debug”时AI 需要把当前的执行步骤和关键决策点逐步输出。这个小小的分支逻辑让我在排查问题的时候无比省心我第一次强烈推荐你也试试。