最近半年AI圈子里冒出来一个词出现频率高得吓人skills。GitHub上相关的仓库动辄几千星吴恩达专门出了Agent Skills的教程Claude Code、Codex、OpenCode、Cursor这些主流工具也都在往这个方向发力。有人把它叫“Agent的超级能力包”也有人说是“给AI装上可复用的肌肉记忆”。我自己的判断是这东西正在成为LLM应用层最值得投入的方向之一甚至比RAG、Agent编排更容易落地见效。如果你还不知道“skills”到底是什么或者听说了但不知道怎么上手更不清楚它和MCP、Prompt、Rules这些概念之间的边界那我建议你花十五分钟把这篇看完。我会从一次实际踩坑经历出发拆解skills的结构、开发流程、调用MCP的方式以及不同场景下怎么设计自己的skills最后附上调试和团队复用的一些经验和教训。先说结论Skills本质上是用一套标准化格式打包“指令、流程、脚本、参考示例”的组合体让模型在需要的时候按任务自动加载并使用。听起来不复杂但设计得好不好效果差距是巨大的。1. Skills的价值不是所有场景都需要一份长Prompt我第一次接触skills是在一个前端还原设计稿的项目里。当时用对话式Agent调UI效果一直不稳定。同一个任务今天生成的结构和明天生成的结构能差出十万八千里。后来我尝试把所有规范、组件约定、示例代码都塞进系统Prompt结果Prompt直接冲到了两万多字调用成本上去了模型的注意力也明显涣散后面几轮对话经常把前面的约束忘掉。这个问题的根源在于模型是“无差别”地处理感知到的所有上下文。你塞进去一万字规范它不知道这一万字里有哪部分是和当前目标高度相关的权重分配是靠注意力机制自己学的常常跑偏。而skills的思路不一样。它是把“领域知识操作流程工具调用方式示例”封装成一个独立单元按需加载。模型先判断当前任务属于哪个场景再决定调用对应的skill。比如你说“帮我从这张图还原一个登录页”Agent会先识别这是前端还原任务加载frontend-restore这个skill然后按skill里的工作流一步步执行。你不需要在每次对话里都重复那一大堆规范skill自己就是一个携带全套上下文的知识包。这套设计思路让我想到了一个很贴切的类比普通Prompt像你把一本操作手册塞给实习生让他自己边翻边干skill则像你给一个老员工戴上专用的工牌他进对应的车间就知道该干什么、找谁配合、用什么工具。前者的效果取决于实习生的临场发挥后者的效果取决于工牌背后的培训体系。吴恩达在Agent Skills的教程里也表达过类似的观点要让Agent高效工作不能只依赖模型本身的通用能力而要把专家流程和领域知识沉淀下来。这正好解释了为什么这个领域突然火起来——大家都在寻找一种比长Prompt更可靠、比复杂Agent框架更轻量的中间态。2. Skills的架构拆解一个Skill背后到底有什么2.1 从文件的视角看Skills以目前社区里比较通行、也是Claude Code等工具采纳的格式为例一个skill通常是一个独立的目录里面至少包含一个核心描述文件和一个可选脚本目录。常见的目录结构长这样my-skill/ ├── SKILL.md ├── scripts/ │ ├── generate_report.py │ └── analyze_data.py ├── assets/ │ ├── template.md │ └── examples/ └── README.md可选SKILL.md是整个skill的入口和“操作手册”一般用Markdown书写包含名称、描述、适用场景、核心步骤、注意事项等。格式上类似早期GPTs的instruction但更强调可执行流程而不是简单的角色扮演。scripts/目录放的是可执行的脚本或代码片段允许skill在需要时运行Python、Shell、JavaScript等脚本完成具体计算、文件操作、数据抓取等任务。这部分配合Claude Code、Codex这类具备代码执行能力的Agent使用效果尤其突出。assets/目录用来存放模板、示例输出、参考资料等静态文件。我习惯把“正例”和“反例”都放进去因为模型对示例的学习能力远强于对抽象规则的理解。2.2 Agent是怎么“学会”一个Skill的用最朴素的逻辑讲Agent在启动时会扫描指定的skills目录读取每个skill的SKILL.md中的描述字段建立一份“技能索引”。当用户提出请求后Agent会先在索引里做一次匹配判断是否有skill适用。如果匹配上就把对应的SKILL.md内容作为高优先级上下文注入当前会话并可能在后续步骤中调用scripts/里的脚本执行具体操作。这个机制的巧妙之处在于索引阶段技能描述是短文本开销低真正执行时技能内容是完整上下文精度高。模型用“短描述做路由长内容做执行”一举两全。注意不同工具的加载机制有细微差别。以Claude Code为例它早期更多是把skills作为附加说明让模型自行决定是否采用而像Codex的Skills机制则倾向于在检测到匹配意图时强制注入对应流程。前者灵活但依赖模型的自我判断后者稳定但需要更精确的匹配规则。我建议你在具体工具中做实验时先搞清楚它属于哪种策略免得出现“文件放对了却不生效”的困惑。2.3 Skills、MCP、系统Prompt之间的边界这块我踩过比较大的坑也收到过不少读者的私信统一梳理一下。Skills是“知识和流程的封装”回答的核心问题是“这个任务应该怎么干、有哪些注意事项、按什么步骤推进”。它更偏向静态的、稳定的经验。MCPModel Context Protocol是“工具接入的协议”回答的核心问题是“Agent如何访问外部数据源、如何操作外部系统”。它更偏向动态的、实时的数据交换。系统Prompt是“全局的通用约束”回答的是“Agent的基本人设、语气、底线规则等”。简单说一个负责“知道怎么做”一个负责“能去操作外部世界”一个负责“约定底层的性格和边界”。三者是互补关系不是替代关系。理想情况下一个Agent里同时挂载几个核心skills、接入若干MCP server、再配一份精简系统Prompt各司其职。3. 动手开发一个Skills从设计到落地3.1 第一个原则从一个具体问题出发我觉得开发skill最容易犯的错误是一上来就想做一个“全域专家”技能把很多不相关的东西揉在一起。结果就是索引匹配时什么都能匹配上执行时又什么都不够精准。我自己定下的筛选标准是如果你能很清晰地用一句话说这个skill解决什么问题那这个skill就值得做如果不能先拆分任务。比如“前端还原设计稿”可以说清楚“帮我写所有代码”就不行。3.2 核心元信息与描述写法假设我们做一个“前端设计稿还原”的skillSKILL.md的开头我会这么写--- name: frontend-design-restore description: 将设计稿图片/PDF/Figma导出图还原为高保真HTML/CSS页面。适用于响应式Web页面开发、组件库页面实现、登录页/落地页还原等场景。不适用于逻辑复杂的Web应用后端开发。 version: 1.0.0 tags: [frontend, ui, design, html, css, tailwind] --- # Frontend Design Restore ## Objective 将输入的设计稿还原为结构清晰、视觉一致的HTML/CSS页面。 ## Steps 1. 分析设计稿的布局层级识别主要的区块、组件、间距、颜色变量。 2. 确定技术栈默认使用HTML CSS或指定Tailwind。 3. 先搭HTML语义结构再写CSS样式保证移动端优先响应式。 4. 对图片资源用本地占位图或base64避免外链失效。 5. 自查对比设计稿的间距、字号、圆角、阴影输出修正清单。 ## Guidelines - 颜色使用CSS变量管理命名有语义。 - 不使用深层嵌套超过4层的选择器。 - 对无法确定的细节在输出末尾列出“待确认项”。这段描述里有两个值得注意的点一是description字段写了具体的场景边界包括什么情况“适用”、什么情况“不适用”这能显著降低Agent误用skill的概率二是格式上用YAML front matter做元数据很多工具原生支持解析命名上也要与文件夹名对应。3.3 用脚本强化Skills的硬实力只有文本指令的skill说白了就是一包“优质Prompt”。要让它真正有生产力必须接入可执行脚本。我举个例子给前端还原这个skill配一个scripts/extract_colors.py传入设计稿路径自动提取主色板并输出CSS变量。这样Agent在还原时就不需要靠肉眼估色而是直接拿到一组可用的颜色变量。#!/usr/bin/env python3 从设计稿中提取主色调并生成CSS变量 import sys from collections import Counter from PIL import Image def extract_colors(image_path, top_n8): img Image.open(image_path).convert(RGB) img_small img.resize((100, 100)) pixels list(img_small.getdata()) counter Counter(pixels) return counter.most_common(top_n) if __name__ __main__: path sys.argv[1] colors extract_colors(path) print(:root {) for i, (color, count) in enumerate(colors): hex_color #{:02x}{:02x}{:02x}.format(*color) print(f --color-{i}: {hex_color};) print(})这个脚本本身不复杂但它的存在让skill从“教模型怎么想”变成了“帮模型做出来”。我在实践中发现带有专用脚本的skill比单纯靠模型推理的同一场景效果好出一大截。原因是脚本处理颜色、数据、文件操作时是确定性逻辑而模型在这些场景下容易产生幻觉。3.4 版本管理与描述迭代skills升级是不可避免的事。建议在SKILL.md里明确一个version字段并用CHANGELOG.md记录变更。我在团队推行这套方法之后解决了很多“明明改了文件但Agent还在用旧逻辑”的问题。我还习惯在描述里写一句“如果正在处理X场景请优先使用本技能并遵循其中步骤”效果比单纯列举标签更好。4. Skills如何调用MCP工具组合出更强的能力4.1 MCP工具为Skills提供数据触手很多人在分区讨论skills和MCP但我更倾向于把它们看作两个纬度。举个真实例子我做“网页查资料”类skill时发现一个问题——SKILL.md里写得再详细模型也无法实时获取搜索结果和网页正文。后来我接入了一个MCP server来提供网页抓取和搜索的能力skill里的步骤就变成了使用MCP提供的搜索工具查询关键词相关的最新5篇文章。读取每篇文章的正文内容剔除导航、广告等噪声。按SKILL.md中的格式要求整理成摘要标注来源和日期。这样以来skill负责“怎么查、怎么整理、按什么格式输出”MCP负责“能查到”。两个组合起来才是一个完整的查资料技能。现在GitHub上热门的academic research skills基本都是这种结构。4.2 在Skill中如何指定MCP调用不同工具里写法不同。以Claude Code为例你可以在SKILL.md里直接写明建议调用的工具名让Agent在执行流程中自己去调用也可以把MCP的调用封装在scripts/里由脚本发起请求。实际操作中我两个方式都用。封装进脚本的做法适合有固定口径的查询比如“查询论文引用数”用脚本调API更可控写在SKILL.md里的做法适合开放式任务比如“根据用户意图决定查什么”让Agent在运行时自己选工具。注意不要在SKILL.md里写死MCP server的地址和密钥。一方面不安全另一方面各环境配置差异大。更好的做法是用工具支持的环境变量或配置注入skill里只写“使用search工具”这类逻辑指令。4.3 组合示例图片还原设计稿我把前端还原这个skill升级到2.0时加入了MCP调用流程变成了这样用户上传或提供设计稿图片地址。Agent调用MCP的图片识别获取布局结构化描述也可用本地视觉模型。调用颜色提取脚本生成CSS变量。Agent按SKILL.md中的步骤搭建HTML/CSS。调用本地浏览器截图工具将页面渲染截图与设计稿进行简单对比列出偏差。做完这套流程之后还原的精度高了不少关键是每一步都有明确的输入和输出模型不再需要靠猜来填补空白。5. 不同场景的Skills设计思路5.1 前端开发场景除了设计稿还原前端开发中常见的高价值skill还包括组件库代码生成、无障碍a11y检查、性能优化审查。设计这类skill时我认为最重要的是沉淀团队自己的代码规范而不是让模型自由发挥。比如你们的项目用了某个UI库、规定了目录结构、有统一的API请求层把这些约定写进skill效果远好于让模型去模仿网上千奇百怪的写法。前端场景我特别推荐把“自查清单”写进skill。让Agent在输出代码之后强制做一轮对照检查是否有硬编码文案、是否缺少loading状态、是否有潜在内存泄漏。模型在生成时和自查时的状态其实是不同的明确要求它自查一轮能明显减少低级错误。5.2 数学建模场景数学建模类的skill最近热度也很高。这类skill的设计重点不是让模型会解题而是让模型知道完整的建模流程问题分析、假设建立、模型选择、求解、验证、报告撰写。我见过一个不错的数学建模skill它把SKILL.md写成了类似“团队工作手册”的形式明确每个阶段需要什么输入、用什么方法、输出什么文档。还提供了一套scripts/visualize.py能把结果快速画成规范图表。这个思路的价值在于让模型不遗漏建模的任何一个关键环节。5.3 测试用例设计场景测试用例类的skill是我个人觉得投入产出比最高的一类。把常见的等价类划分、边界值分析、状态转换等方法论写进去再塞一个“按P0/P1/P2分级”的模板让模型直接产出可粘贴到用例管理平台的表格。这类skill的格式要求非常重要一定要提供示例输出最好是“一份完整用例”的成品而不是抽象描述。5.4 需要注意的边界场景像渗透测试、爬虫这类敏感性较高的场景如果你确实在工作中有正当需要建议把skill定位在“授权范围内的安全测试流程”和“合规数据采集规范”上。不要设计那种自动扫描、绕过防护的skill这和安全测试的基本原则是相悖的。涉及系统安全和数据采集的自动化脚本务必确认授权边界和合规要求。6. 常见问题与排查技巧实录6.1 Skill完全没有被调用这是最常遇到的问题。文件放好了目录也建了但Agent就是“视而不见”。排查顺序我一般是这样检查工具支持skills的目录路径确认文件放进去了。查看工具的日志或调试模式确认启动时是否成功加载了skill索引。检查description字段如果描述里没有覆盖用户当前问法的关键词模型很可能无法匹配。解决办法是写多个同义表述比如“还原设计稿”“图片转网页”“psd生成html”都写上同时加上场景标签。确认不是多个skill描述互相抢占导致每个都不够确信。6.2 Skill被调用了但执行过程跑偏这个问题的根源往往是SKILL.md里的步骤写得不够细。模型默认倾向于“尽快给出结果”如果步骤里没有明确说“先做什么再做什么”它就会偷工减料。解决办法是我在前面提到的把步骤写成不可跳过的流程并在最后加一个自查环节。比如“输出前必须检查以下10项”模型对这个指令的执行力远远高于对泛泛要求的执行力。另外我建议在SKILL.md里加入“不要做什么”的负面清单。模型对明确的“不要”理解得比模糊的“注意”要好。6.3 输出质量不稳定时好时坏我踩过的一个坑是skill里的示例文件用了太“偏门”的例子导致模型被带偏。后来我把assets/examples/调整为“一个标准正向案例 一个常见错误案例”效果立刻稳定了下来。正向案例教它最佳实践错误案例教它避开坑两者比十个中规中矩示例的指导性都强。另外一个原因是模型本身的版本或temperature设置。系统能力强了之后skill内步骤的遵守度显著提升temperature偏高也会导致模型在步骤之间“自由发挥”。如果你的应用追求稳定输出temperature不要超过0.5。6.4 团队多人协作时skills混乱当团队规模超过两三个人skills就开始乱了。我目前比较认可的方案是用Git管理skills目录每个技能一个独立仓库或monorepo子包。明确负责人每个skill至少有一个owner修改需要review。版本号写进SKILL.md同时维护一个CHANGELOG.md。定期清理无效技能避免索引越来越大匹配精度下降。最后的一点个人体会我做了这么多skills相关项目之后一个真实的感受是skills项目的复杂度天花板不高但效果天花板很高。它不像做一个完整RAG系统那样需要处理一堆基础设施它的重心全在“如何把经验组织好、把流程定义清楚、把工具用好”。这反而是很多开发者的短板——我们习惯了写代码不习惯把“怎么做一件事”的隐性知识结构化地表达出来。如果你现在手头有一些重复性高、经验性强的任务场景比如代码审查、设计稿还原、周报整理、数据报告生成我非常建议你试着把它们分别封装成一到两个skills。先在本地项目里小范围跑通再慢慢补充示例和脚本。持续迭代三四个版本之后你会明显感觉到Agent从“一个聪明但毛躁的实习生”变成了“一个熟悉你团队规则的资深助手”。最后分享一个小技巧给skill取名时优先用描述动作的短语比如check-a11y-issues、extract-palette、write-test-cases而不是抽象名词。因为模型在路由匹配时对动作型描述的理解准确率明显更高而且这样的命名在多人协作时也更不容易产生歧义。希望这篇能帮你少走一些弯路。