最近一段时间GitHub 上被一个词刷屏了就是skills。点进去一看有叫superpower skills的有叫baoyu skills的还有各种claude code skills、codex skills、opencode skills。如果你跟我一样第一反应是“这不就是提示词模板合集吗”那这篇文章可能会改变你的看法。Skills 确实长得很像提示词但它解决的问题、工作的方式以及踩坑的点都跟传统提示词完全不是一个量级。我花了两周时间把几个主流编程 AgentClaude Code、Codex、Cursor、OpenCode的 Skills 机制都跑了一遍自己写了 4 个可以复用的 Skill也踩了不少坑。这篇文章不聊概念就聊实操Skill 到底是什么、怎么装、怎么写、怎么跟 MCP 配合、出了问题怎么排查。文章里所有目录结构和代码都是我在本地跑通过的真实方案你可以直接照着抄。1. Skills 不是技能清单是 Agent 的“岗位说明书”先说结论Skills 是一套给 AI Agent 用的、结构化的“岗位说明书”。它告诉 Agent 在什么场景下、按什么步骤、用什么工具把一类任务稳定地做完。1.1 为什么提示词不够用了才轮到 Skills 上场早期我们用提示词本质上是在“一次性交代任务”。比如你写一句“帮我分析一下这个项目的代码结构”模型会基于它的常识和当前上下文里的文件内容临时组织一套流程。问题是这套流程每次都不一样。同一个项目今天让它分析它先看 README明天再问它可能直接去翻 package.json。结果就是你得反复纠正效率很低。Skills 做的事情是把“稳定的流程”从“随机的模型行为”里剥离出来。你把一套最佳实践写成文档放在固定的目录里Agent 在遇到匹配场景时自动加载这个文档按里面写的步骤一步步执行。相当于你给 Agent 发了本《工作手册》它照着做就行。我试过之后最直观的感受是输出质量从“看运气”变成了“可预期”。还有一个很实际的原因上下文窗口是有限的。一次会话里塞 10 个提示词模板真正执行时模型反而不知道该听谁的。Skills 是按需加载的Agent 看到任务先判断匹配哪个 Skill再把对应内容读进来。平时不占空间用到时才加载这才是它适合复杂任务的根本原因。1.2 它和 MCP、插件、Prompt Template 到底什么关系这块是新手最容易绕晕的地方。我一开始也把 Skills 和 MCP 混在一起后来用多了才理清楚边界。打个比方MCP 是 Agent 的“手脚”负责执行外部操作比如查数据库、调 API、读写文件Skills 是 Agent 的“大脑皮层”负责决定遇到什么情况用什么手脚、按什么顺序用。具体区别可以用一个表说清楚概念核心作用载体典型例子Prompt Template一次性对话模板一段文字“你是一个资深前端请审查以下代码”Skill可复用的任务流程Markdown 文件 脚本 资源目录“按设计稿还原前端页面并输出结构图”MCP外部工具连接器服务端程序文件系统、数据库、浏览器自动化Plugin / Extension工具集成框架插件包IDE 插件、命令行扩展这里有个容易误解的地方Skills 内部可以引用 MCP。准确说是 Skill 文档里会写明“执行到某一步时调用哪个 MCP 工具”。最终调用的动作还是 MCP 完成的但“什么时候调、为什么调”是 Skill 说了算。所以两者的关系是配合不是替代。2. 让 Agent 会调 Skill目录结构与 SKILL.md任何工具类技术第一步永远是搞清文件放哪、格式长什么样。Skills 的约定不复杂但细节很碎目录错了、文件名不对、格式不对都可能让 Agent 完全忽略你的 Skill。2.1 目录约定不同 Agent 的加载路径我实测下来目前主流工具遵循两类目录约定。第一类是以 Claude Code 为代表的.claude/skills/第二类是以 Codex 和 OpenCode 为代表的.agent/skills/。好消息是大多数工具为了兼容两个目录都会读取。我自己现在的标准做法是建一个.agent/skills/目录同时在项目根目录放一个.claude/skills/作为软链这样切工具时不用重复维护。目录内部的结构一般是这样的.agent/skills/ └── frontend-design-recovery/ ├── SKILL.md # 核心文件Agent 首先读取它 ├── reference/ │ └── style-guide.md └── scripts/ └── extract-design-tokens.py每个 Skill 一个独立文件夹文件夹名就是 Skill 的名字。核心文件必须是SKILL.md这是所有工具的统一约定。辅助文件可以随便放但建议按功能分子目录reference/放参考资料scripts/放可执行脚本。目录里的文件都会被 Agent 感知但它不会一次性全读只会按需打开这个机制对控制上下文消耗很重要。2.2 SKILL.md 的 Frontmatter 怎么写才不白写SKILL.md是一个带 YAML Frontmatter 的 Markdown 文件。Frontmatter 里最关键的两个字段是name和description。name没太多讲究跟文件夹名一致就行description是灵魂因为 Agent 判断“这个任务跟这个 Skill 匹不匹配”全靠读 description。我写 description 的经验是要把“触发场景”和“任务目标”写清楚但不要写具体执行步骤。比如你写“用于把人脸照片转成素描”这个描述太粗Agent 可能在处理风景照时也强行加载它。更好的写法是“当用户上传包含人脸的图片并希望生成素描风格图像时使用”。反过来也千万别把步骤写进 description比如“先裁剪图片再转灰度再增强边缘……”这样会限制 Agent 在遇到特殊情况时做调整的灵活性。Frontmatter 的基本格式长这样--- name: frontend-design-recovery description: 当用户提供设计稿图片PNG/JPG/Figma 导出图并要求还原为前端代码时使用。包括提取设计规范、生成页面结构、输出可用组件代码。适用于电商活动页、后台管理界面、移动端 H5 页面等场景。 ---正文部分就是你希望 Agent 执行的具体流程。这里我建议写得“像一个老员工带新人的操作手册”而不是“给机器人的指令序列”。什么意思呢把步骤、原则、质量标准都写清楚但给 Agent 留出做具体实现的自由。它可以按你写的流程走同时允许它调用合适的工具来自行完成实现。比如某一步我写“按 W3C 规范检查无障碍属性”至于具体检查哪些Agent 自己会补充细节。2.3 触发的两种方式自动匹配与手动点名调用 Skill 有两种方式。第一种是自动触发Agent 根据用户当前请求在已安装的 Skills 里搜索 description 匹配度最高的自动加载执行。第二种是手动触发你直接在对话里输入#skill-name或/skill-name指定它必须使用某个 Skill。具体语法取决于工具不过大方向一致。这里有个很实用的技巧当你想强制测试一个 Skill 时手动触发是最好的方式。我在开发初期调试 Skill 的时候永远手动点名确认它能跑通之后再调整 description 让自动匹配生效。这样能避免一个常见困境你改了 description但 Agent 还是经常优先加载另一个长得比较像的 Skill最后分不清是哪个在起作用。3. 手写一个 Skill把“图片转前端设计稿”变成可复用工作流光说理论没有感觉我直接拿一个我实际开发的 Skill 当案例拆给你看。这个 Skill 解决的是“设计稿还原前端页面”的问题这个是前端开发里最高频、最繁琐、也最值得自动化的场景之一。3.1 先把工作流拆成 Agent 能理解的步骤在写 Skill 之前我先把人工还原设计稿的流程拆了一遍总结成 5 步分析设计稿提取色值、字体、间距、圆角、阴影等设计变量识别页面布局结构确定是 Flex 还是 Grid几个区块嵌套关系编写 HTML/CSS 骨架先保证结构和视觉一致处理响应式按断点调整样式做无障碍检查和代码格式化输出可提交的成品。这个流程本身并不新奇但把它稳定地跑下来效果就很可观了。因为模型每次自己发挥时总会漏掉其中一步。有时候漏了响应式有时候忘了提取设计变量直接硬编码色值。写成 Skill 之后Agent 会老老实实按步骤走质量明显稳定。3.2 SKILL.md 完整示例主干的写法下面是我这个 Skill 的主干内容精编版。你不需要照抄重点关注它的结构和语气。--- name: frontend-design-recovery description: 当用户提供设计稿图片PNG/JPG/Figma 导出图并要求还原为前端代码时使用。包括提取设计规范、生成页面结构、输出可用组件代码。适用于电商活动页、后台管理界面、移动端 H5 页面等场景。 --- # 前端设计稿还原 ## 任务目标 将用户提供的设计稿图片转化为语义化、响应式、可维护的前端代码。 ## 执行流程 ### 第一步提取设计规范 1. 打开设计稿图片列出所有出现的颜色值建立色板。 2. 识别字体族、字号、字重、行高整理成 typography 规范。 3. 测量主要区块的间距、圆角、阴影值。 4. 将以上结果统一输出到一个 DESIGN_TOKENS.md 文件中。 ### 第二步确定布局结构 1. 判断整体布局方向横向导航 / 纵向导航 / 混合。 2. 识别内容分区为每个区块命名并标注嵌套关系。 3. 根据区块特征选择实现方式Flex 用于一维排列Grid 用于二维布局。 ### 第三步实现组件与页面 1. 先写 HTML 结构确保语义化标签使用正确header、nav、main、section、footer。 2. 再写 CSS优先使用设计变量避免 hardcode 值。 3. 如果用户要求使用 Tailwind将设计变量映射为 Tailwind 的配置项如果要求普通 CSS则使用自定义属性。 ### 第四步响应式适配 1. 设置合理的断点根据内容而不是固定设备宽度。 2. 优先采用移动优先策略再逐步增强桌面样式。 ### 第五步质量校验 1. 检查图片是否全部处理了 alt 属性。 2. 检查颜色对比度是否符合 WCAG AA 级别。 3. 检查是否有未使用的 CSS 类名或重复样式。 4. 格式化代码提交最终结果。 ## 避坑提示 - 不要为了追求像素级还原而忽略响应式优先保证结构清晰。 - 设计稿中使用模糊效果时建议用标准 CSS filter 实现不要用静态图片模拟。写完之后我测试了几轮发现一个现象只要我把“先输出设计变量”这步放在最前面最终代码的规范性就会有一个明显提升。原因也好理解模型先看到了整理好的变量清单后面写代码时会不自觉地引用这些变量而不是随手硬编码。这就是 Skill 带来的“流程约束力”。3.3 给 Skill 加执行脚本复杂任务才能落地有些 Skill 只靠 Markdown 文档就能完成比如代码审查、文档编写。但一旦涉及文件批量处理、数据清洗、图片操作就必须依赖脚本。以我的设计还原 Skill 为例我用一个 Python 脚本从设计稿里提取主要色值输出成 JSON再交给 Agent 去写 CSS 变量。定义一个能传给 Agent 的脚本通常是在 SKILL.md 的正文里用代码块写清楚调用方式。我这里给出一个简化版的示例核心是用 Python 的 Pillow 库识别图片中的主色供参考。# scripts/extract_dominant_colors.py from PIL import Image import sys def extract_colors(image_path, num_colors10): image Image.open(image_path).convert(RGB) image.thumbnail((200, 200)) # 这里使用量化方法提取主色避免直接聚类带来的性能问题 reduced image.quantize(colorsnum_colors, methodImage.MEDIANCUT) palette reduced.getpalette() color_counts sorted(reduced.getcolors(), reverseTrue) colors [] for count, index in color_counts: offset index * 3 rgb tuple(palette[offset:offset 3]) colors.append({ rgb: frgb{rgb}, hex: #{:02x}{:02x}{:02x}.format(*rgb), count: count }) return colors if __name__ __main__: colors extract_colors(sys.argv[1]) for color in colors: print(f{color[hex]} {color[rgb]} occurrence{color[count]})在 SKILL.md 里我会在“第一步提取设计规范”下面加一行说明告诉 Agent 可以运行这个脚本辅助识别色值。实践下来让 Agent 先跑脚本再写样式比让它自己“看”图片更可靠。因为模型对颜色的感知并不总是准确特别是相近色、阴影里的暗色脚本给的是精确值一步到位。4. Skill 和 MCP 工具怎么配合才顺手围绕 Skills 的搜索热词里出现频率最高的一个问题是“Skills 如何调用 MCP 工具”。我一开始也被这个问题困住过后来发现关键不在于代码层面怎么打通而是文档结构上怎么安排。Agent 自己会读取 Skill 文档当流程里标注“需要查资料时调用某某 MCP 工具”它自然就会去调用。4.1 在 Skill 文档里写明工具调用时机以我写的一个“前端技术调研”Skill 为例它的一个典型场景是用户希望我分析某个新框架是否适合项目我需要先上网查最新版本、社区评价、更新记录再结合当前项目情况给出建议。这时候Skill 文档里就有这么一段### 执行步骤 1. 首先使用 web_search 这个 MCP 工具搜索该框架的官方文档和最新版本信息。 2. 如果官方文档页面无法直接读取使用 web_fetch 工具获取页面正文。 3. 顺着文档把安装方式、核心 API、迁移路径整理出来。 4. 结合项目现状README、package.json给出可行性与风险分析。注意我在这里并没有写复杂的代码去调用 MCP只是把“调用什么工具、在哪个环节用”写清楚。Agent 看到这些说明后会根据当前环境可用的 MCP 服务名称去发起调用。所以实际工作时往往是“Skill 提供流程大纲MCP 提供实际操作工具”两者搭配起来效率才会高。你需要确保的是文档里写的工具名称和你实际配置的 MCP 服务名完全一致比如web_search、web_fetch别用别名否则 Agent 可能找不到。4.2 实测让 Skill 在联网检索场景下干活我测试过一个“行业竞品分析”的 Skill它在流程里有一步是“搜索这些竞品最近三个月的版本更新和用户反馈”。在配好相应 MCP 工具后Agent 确实会自动完成搜索、汇总并输出对比表格整个流程非常顺畅。如果不配 MCPAgent 会用自己的内部知识硬写内容很容易过时。不过这里面有个需要当心的地方MCP 工具返回的内容可能很冗长动辄上万字的网页正文会直接冲击上下文窗口。我的解决办法是在 Skill 的流程说明中主动要求“先抓取页面正文提取前 500 字的核心要点如果有版本号或关键数据单独列出不要粘贴完整正文”。这个约束看起来很简单但能帮你省掉大量上下文占用Agent 的执行效率也会高很多。4.3 共享给团队时的注意事项如果你打算把 Skill 提交到团队仓库共享除了文件本身还要附一个说明说清楚这个 Skill 依赖哪些 MCP 服务、哪些脚本、哪些外部命令。我见过不止一次同事拿到了一个很好的 Skill但本地没装对应的 MCP 服务结果 Skill 跑起来直接报错最后大家误以为是 Skill 本身有问题。所以在你写 SKILL.md 时最好在 Frontmatter 下面加一个“依赖环境”的章节把需要预装的东西列清楚这是团队协作里最容易被忽略、却最重要的细节。5. 常见问题排查为什么我的 Skill 不生效Skills 机制本身不复杂但真正用起来各种奇怪的问题一点也不少。我自己整理了一份排查表这些问题你大概率也会遇到。5.1 速查表Skill 不生效的 6 个常见原因下面这张表是我个人踩坑的记录汇总按出现频率排序。如果你发现 Skill 没有被加载先从第一行开始查大概率能快速定位。现象可能原因排查与解决办法Agent 完全忽略 Skill目录结构不对或文件名不是 SKILL.md确认骨架是.agent/skills/技能名/SKILL.md文件夹名字不能有空格文件必须叫 SKILL.md有多个 SkillAgent 总是选错description 写得太宽泛或关键词不精准重新打磨 description写清触发场景比如“当用户提供截图并要求还原为代码时使用”而不是“处理图片”手动点名也不生效工具版本太低或字符写错检查工具版本是否支持 Skills确认是#skill-name还是/skill-name参照官方文档Skill 执行一半突然停止脚本报错或依赖缺失手动运行脚本排查错误检查依赖环境尤其注意相对路径问题同一个任务两次结果差异巨大SKILL.md 中流程描述不够具体把步骤写得更细比如指定输出文件的格式、命名规则、必须包含的检查项上下文被 Skill 相关内容占满Skill 文档太长或子文件被一次性加载精简 SKILL.md 正文把长内容移到 reference 子目录在文档里明确“按需读取子文件”5.2 一个真实的排查案例记录前两天我帮朋友排查一个 Skill现象是他把一个“测试用例生成”的 Skill 放进目录后Agent 完全无感每次还是按默认方式生成测试。我远程看了一眼他的目录问题立刻找到了。他把文件夹建成了test-cases-skill/SKILL.md文件夹名字没问题但 SKILL.md 的 Frontmatter 里name写的是unit-test-generator两边名字对不上。有些工具靠文件夹名识别有些靠name字段识别一旦不一致就会出现加载混乱。改成一致后问题马上解决。还有一次是路径问题。我的 SKILL.md 里引用了./scripts/extract.py但脚本实际放在scripts/tools/extract.py相对路径错了。这里提醒大家SKILL.md 里引用脚本时路径要相对于 SKILL.md 文件本身来写不要相对于工作目录。因为 Agent 执行脚本时它的当前工作目录可能是项目根目录而不是 Skill 所在目录。5.3 调试 Skill 的好用方法写一个“自检版”如果你想系统调试一个 Skill而不是每次靠猜可以给 Skill 加一个“自检模式”。做法是在 SKILL.md 的末尾加一个章节写上## 自检清单 在完成上述任务后请逐项确认以下内容并把结果写入 OUTPUT.md - [ ] 是否提取了设计变量 - [ ] 是否包含响应式断点 - [ ] 是否检查了无障碍属性 - [ ] 是否有未使用的 CSS 类名 - [ ] 引用的脚本是否成功运行这样做有一个额外好处Agent 在收尾时自己会当一回“质检员”根据清单复查一遍结果。这个技巧看起来简单但对输出质量的改善非常明显。相当于你给流程加了一层强制校验模型在做完活之后还要自证“我做完了、做对了”。6. 社区公认的高质量 Skills以及怎么挑现在的 Skills 生态有点像早期的 App Store什么牛鬼蛇神都有。GitHub 上标星最高的几个比如superpower skills和baoyu skills质量确实不错但也不是所有内容都适合你的工作流。我的建议是不要全部照搬把别人好的思路拆出来改造进自己的 Skill 里比直接下载一堆“通用包”有用得多。6.1 我推荐优先收藏的三类 Skill第一类是“研究类”比如学术文献检索、技术调研、竞品分析。这类 Skill 特别适合和 MCP 联网工具配合能把过去 1 小时的调研压缩到 10 分钟。第二类是“代码项目审查类”它会指导 Agent 按层次分析一个仓库从依赖、架构、代码风格、测试覆盖等几个维度分别输出报告非常适合接手旧项目时快速摸清底细。第三类是“文档与内容生成类”比如把会议录音转成结构化的周报、把零散需求整理成 PRD它们的核心价值在于格式规范能让输出直接投入使用。还有一类比较特殊是“数学建模”方向的 Skills在高校和竞赛圈子里讨论度很高。这类 Skill 通常会把建模流程拆成“问题分析、模型假设、数学建模、算法设计、结果检验”几个步骤配合 Python 脚本做数据预处理和可视化。如果是竞赛用途建议自己在本地跑一遍把脚本路径和依赖调通别直接指望 Agent 全自动完成。6.2 如何判断一个开源 Skill 能不能直接用判断标准就三条看文档是否写清了适用场景看是否列出了依赖环境看是否有明确的输出产物定义。如果一个 Skill 的 README 只写了一句“牛逼的 Skills 集合”连每个 Skill 的触发场景都没说明白那哪怕它有一千颗星也不适合生产使用——因为你根本不知道它会在什么场景下被触发、会产生什么行为。相反如果文档里清楚地写着“当用户要求生成接口测试用例时使用依赖 HTTP 抓包 MCP 服务”那基本可以判断作者是认真打磨过的。我在挑选的时候还有一个习惯就是先看它的 SKILL.md 正文是不是用了“检查清单”和“避坑提示”这种结构。有这些内容的说明作者实际用过、被坑过写出来的东西可信度更高。纯讲流程没有实战细节的多半是凑出来的。6.3 直接用的两个注意点把社区 Skill 直接放进本地目录前务必看一遍它的脚本内容。Skills 里的脚本是有执行权限的Agent 在流程要求时会运行它。如果你不确定脚本做了什么就先在隔离环境里跑一遍确认没有危险操作再放进正式目录。这个习惯在团队环境里尤其重要安全怎么强调都不为过。另外社区 Skill 默认的 description 往往写得比较宽泛直接装进来可能跟你的现有 Skill 冲突导致 Agent 选错。我的做法是安装后立刻改写 description让它的触发范围更精准并删掉我项目里用不到的子模块。这样既能用上社区经验又不会污染本地的工作流。7. 从单个 Skill 到一套工作流我的个人实践建议最后聊点更贴近日常经验的东西。Skills 这个模式真正厉害的地方不是“一个 Skill 搞定一个任务”而是你可以基于它搭建一套完整的工作流。拿我自己的技术写作流程举例我把“素材收集、初稿撰写、代码示例验证、SEO 检查、排版格式化”各自拆成一个 Skill再在主 Skill 里按顺序引用它们。这样当我输入一个主题时Agent 会像流水线工人一样一步步产出有稳定质量的成品而不是在一条上下文里从零硬写。在生产环境里我会保证“项目私有 Skill”优先于“用户全局 Skill”这样不同项目可以维持各自的技术栈规范。比如项目 A 用 Vue 写组件项目 B 用 React它们的组件生成 Skill 内容完全不同放在各自项目的.agent/skills/下就不会串。写过几个 Skill 之后我的体会是写它的过程实际上就是在倒逼你自己把平时的工作流想清楚。我以前带人的时候说“按最佳实践来”但其实我自己也没有逐字写下来过。写 Skill 逼着我把它白纸黑字整理出来这个过程本身的价值可能比最后生成的那几个文件还要大。如果你正在学 Agent 相关的开发建议第一条先别想着搞那些花哨的功能就从记录你自己的日常操作开始。