Agent Skills 这个词最近在开发者圈子里刷屏的频率有点高我一开始也没太当回事以为又是哪个框架换了个名字炒冷饭。直到自己真把一个重复性极高的活儿——前端页面评审——沉淀成一份 Skill 之后才发现这东西解决的其实是 Agent 落地最痛的一环让模型从“听一次指令干一次活”变成“拿着 SOP 稳定干活”。这篇文章把我的完整思路、写法和踩坑过程都摊开讲适合正在做 Agent 开发、或者想把日常重复工作沉淀成可复用能力的朋友参考。如果你是刚接触 Agent 的新手也不用担心我会把基础概念一并讲透。1. Agent Skills 到底解决什么问题1.1 从“会对话”到“会干活”Agent 卡在哪先聊聊背景。任何一个 Agent 的雏形本质上都是“大模型 工具调用”。你在对话里给它一个目标它自己拆解步骤、选工具、执行。但用久了你会发现一个问题同一个 Agent同样类型的任务昨天干得漂亮今天就可能翻车。原因很简单——模型每次都在“临时发挥”。你要求的格式、步骤、检查清单它记得住一部分、忘掉一部分、发挥一部分结果就飘了。Skills 就是冲着这个痛点去的。它把完成某一类任务的方法论固定下来打包成一个可以随取随用的模块。Agent 在运行过程中只要识别到当前任务匹配某个 Skill就会按 Skill 里写好的步骤走而不是每次重新“临场创作”。这个思路其实很像现实里的岗位说明书新员工上手不用瞎琢磨照着说明书一步步来质量下限就保住了。我最早意识到 Skill 的价值就是因为同样的页面评审任务每次让 Agent 做出来的报告格式都不一样改都改不过来。后来把流程固化成 Skill三秒钟就解决了格式漂移的问题。1.2 Skill 和 Prompt、Tool、Agent 到底啥关系很多人第一次听到 Agent Skills会自然冒出几个问题这不就是加强版 Prompt 吗跟 Tool 有什么区别和 Agent 是不是一个东西我按自己的理解给你拆一下。Prompt 是给模型的一次性指令用完就没了不具备复用性。Tool 是 Agent 可以调用的一组外部能力接口比如搜索、读文件、执行代码它解决的是“能做什么”。Skill 则是封装了一整套操作流程和执行规范的能力包解决的是“怎么做得对、做得稳”。Agent 是承载这一切的运行实体它负责感知任务、决定调用哪个 Skill、调度哪些 Tool。一句话总结我的理解Tool 是零件Skill 是操作规程Agent 是工人。零件能让工人干活但只有配上操作规程干出来的活儿才是可预期的。Skill 往往还会引用 Tool比如一个前端审查 Skill 里面会要求调用浏览器工具或代码执行工具这样才能把流程和接口串起来。另外注意Skill 和记忆Memory也不是一回事记忆负责记住历史状态Skill 负责提供稳定能力两者不要混着规划。1.3 为什么 Skills 突然集体冒头细究起来Skills 的理念并不新但真正火起来跟几个因素有关。一是主流模型厂商开始在官方生态里推广 Skills 形式的能力扩展Claude 这边把 Skills 当做一个对外推荐的形态社区里出现了各种“skills 市场”的讨论和第三方合集。二是代码智能体赛道也跟进了Codex 推出了自己的一套 skills 机制Reasonix、Hermes 等工具也各自支持或兼容技能市场。三是大家慢慢发现Agent 能不能在真实工作中落地关键在于可复现的工作流而不在于模型单次推理有多聪明。我观察热搜词的时候看到一堆人在问“skills 安装包下载”“skills 推荐”“skills 开发”说明这个生态已经从“技术概念”进入“实际使用”阶段了。更多人关心的是到哪里找现成的 Skill怎么装怎么测试怎么自己写一个。这篇文章后面就按这条实操路线走把这些事情一次说清楚。2. 吃透 Skill 的骨架SKILL.md 该怎么设计2.1 一个 Skill 的目录长什么样在我见过的各种实现里最通用的 Skill 形态是一个独立目录里面至少有一个 SKILL.md 文件作为入口再根据需要挂上脚本、参考文档和示例。你可以理解成SKILL.md 是说明书scripts 是可执行工具references 是参考资料examples 是演示样例。Agent 碰到相关任务时首先读 SKILL.md按说明书要求做事。为什么入口文件是 Markdown 而不是 JSON 或者 YAML因为大模型对自然语言指令的理解最稳定Markdown 这种带标题层级、列表、代码块的格式模型解析起来非常顺。你写一个 SKILL.md本质上就是在写一份“给模型看的标准作业流程”它的读者不是人是模型所以措辞必须清晰、无歧义、有明确边界。我见过有人把 SKILL.md 写成 JSON 配置模型虽然也能读但遇到复杂流程时理解效果明显不如结构化 Markdown。与其搞花活不如老老实实遵守这个社区约定。2.2 元信息描述是 Skill 的灵魂SKILL.md 开头一般有一段 YAML 格式的元信息至少包含 name 和 description。很多第一次写 Skill 的人会把 description 写得很宏大比如“处理前端问题”结果 Agent 看到什么都觉得匹配什么都往这个 Skill 里塞最后输出一堆牛头不对马嘴的内容。我的经验是description 里要同时写清楚“这个 Skill 负责什么”和“不该负责什么”。举个例子。与其写“帮助用户解决网页问题”不如写“对给定的 HTML 或页面 URL 进行结构评审输出布局、可访问性、性能三个维度的检查报告当用户只是询问前端概念而不是要求评审页面时不要使用本技能”。这样模型做匹配时触发条件明确的时候才调用边界也清晰了。我后来把不少 Skill 的 description 改成“正面功能 负面排除”双段式结构之后误调用率明显降了下来。name 的命名也要注意短横线小写是主流比如 page-review别用什么汉字或带空格的名字各种工具对名字格式的容忍度不一样。2.3 正文流程把“执行逻辑”写得像程序SKILL.md 的正文部分就是流程描述了。这里有个关键心得你是在教模型执行一套固定流程不是在写一篇科普文章。所以正文要尽量写成这样——第一步做什么、判断条件是什么、满足时走哪个分支、输出结果的格式是什么。我写过一版效果不好的 Skill正文全是散文模型每次执行都靠“悟”。后来改成清晰的编号步骤加明确分支条件加输出模板执行的一致性好很多。你可以把正文理解成“给模型的伪代码”只不过用自然语言写。另外如果某个 Skill 里有绝对不能做的事一定要写进去。只写“应该做什么”不够模型确实会出现“虽然没让做但觉得合理就去做了”的情况。把“禁止事项”单独列一节比如“除非用户明确要求否则不要修改任何源代码”能少踩很多坑。我早期写的 Skill 经常让 Agent 顺手改用户代码加了这个禁止项之后才消停。这两个字值得记住边界。2.4 配套脚本和参考文件怎么放不是所有 Skill 都需要脚本但需要计算、抓取、文件处理的场景脚本能帮模型省大量事。比如让模型计算一个页面上的颜色对比度是否达标模型可能算得头大但一个几行脚本能稳定给出结果。Skill 目录里脚本放在 scripts/ 子目录引用时在 SKILL.md 里写清楚怎么调用、参数是什么、返回值长什么样。参考文件放 references/用来放那些需要长期维护的知识性内容比如“常见图片格式与压缩对比表”。示例放 examples/演示一个典型任务的完整输入输出模型在不确定时可以参考。这里我默认你用的是 “SKILL.md scripts references examples” 这套最小公约数结构。不管最后在哪个工具里跑这套结构不容易出错。等你写多了就会发现参考文件和示例往往比正文更值钱因为模型看到具体例子远比你描述规则来得稳。3. 实操全过程从零手写一个前端评审 Skill3.1 选好场景别一上来就搞大而全开发 Skill 的第一件事不是写代码而是确定边界。我挑了“前端页面评审”作为示例因为这是一个高频、流程相对固定的场景你拿到一个页面地址想从布局、可访问性、性能隐患几个维度快速得到一份报告。这类任务适合做成 Skill因为它有明确的输入、明确的步骤、明确的输出格式。一开始我也犯过贪大的毛病想一个 Skill 把前端所有问题都覆盖了结果模型反而不知道重点在哪。后来把一个 Skill 拆成“页面评审”“跨浏览器兼容性检查”“性能清单核查”几个独立单元每个只管一段流程整体效果好很多。Skill 的粒度建议是一个任务类型对应一个目录宁可拆细不要堆大。你写的时候觉得多写几个文件麻烦但 Agent 执行时目标明确返工率低反而是省时间。3.2 编写 SKILL.md一个可直接参考的模板下面这份是我实际用过的简化版流程做了裁剪但结构完整可以直接抄去改。核心就是元信息管触发条件正文管执行步骤输出格式管交付物。--- name: page-review description: 对给定的页面 URL 或 HTML 片段执行前端质量评审输出布局、可访问性、性能三个维度的检查报告。当用户提供页面地址或要求评审页面/检查网页时使用当用户仅询问前端概念或要求写代码时不要使用。 --- # 页面前端质量评审 ## 输入 用户提供页面 URL 或 HTML 文件内容。 ## 执行步骤 1. 获取页面内容优先使用浏览器工具访问 URL获取 DOM 结构和关键渲染信息如果用户提供的是 HTML 片段直接使用。 2. 布局检查依次核对顶部导航、主内容区、侧边栏、页脚的排列是否正常。若页面上存在明显重叠或遮挡记录具体元素。 3. 可访问性检查检查 img 是否包含 alt表单控件是否有关联 label文本与背景对比度是否存在低于 4.5:1 的区域。 4. 性能隐患检查查看页面引用的图片数量与体积是否同步加载了未被使用的大脚本。 5. 生成报告字段包括页面地址、检查时间、三个维度各自的问题数量、每个问题的问题描述与位置。 ## 输出格式 使用表格输出问题清单每个问题一行列包含维度、严重程度、所在位置、问题描述、修复建议。 ## 注意事项 - 如果页面无法访问不要猜测直接报告无法获取页面内容。 - 不输出与评审无关的代码修改建议除非用户额外要求。这份文件的结构很直白description 写清边界正文写清步骤输出部分写清交付物。模型执行时就是照着这个流程跑而不是自己开脑洞。我第一次写的时候漏了“输出格式”结果 Agent 给了一段散文后来补上表格模板效果立竿见影。3.3 配套脚本把模型算不准的部分交给代码SKILL.md 里我特意留了一个口子对比度校验。让模型自己判断“这个颜色和那个颜色对比度是否达标”不仅慢还经常算错因为模型对色值计算并不稳定。更合理的做法是提供一个脚本让模型调用它去算准确数值。我写了一个简单的 Node.js 脚本放 scripts/contrast.js逻辑就是用标准相对亮度公式计算两个颜色之间的对比度返回“对比度数值, 是否通过”。脚本本身不长核心函数也就十几行。SKILL.md 里我会在可访问性检查那一步补充一句“如果需要计算对比度运行node scripts/contrast.js hex1 hex2读取输出结果”。模型执行到这里时发现要算数值就会调这个脚本拿准确结果填进报告里。这就是把 Tool 和 Skill 结合的例子Skill 定义流程Tool 提供能力两者配合结果才靠谱。3.4 测试与迭代别指望一次写对写好 SKILL.md 和脚本之后我的测试方法很简单准备三个不同状态的页面——一个正常页面、一个有明显可访问性问题的页面、一个完全无法访问的页面——然后分别让 Agent 执行评审看它是否走完全流程、报告格式是否统一、描述是否真实准确。第一次测的时候模型把“布局检查”写成了一段散文描述完全没有按我表格化的输出格式来。我回到 SKILL.md把输出格式那一节直接放了一个具体例子模型第二次就照着例子走了。这个经验值得记下来对模型来说“给例子”比“讲规则”管用得多。只要格式不对优先在 Skill 里补示例而不是指望模型自己理解规则。测试还有一个容易被忽略的点要测试“边界情况”。什么意思就是故意问一个和这个 Skill 无关的问题看 Agent 会不会误调用。比如我问“什么是可访问性”如果 Agent 启动了页面评审 Skill说明 description 写得还不够细需要继续加负面排除词。这步测试做扎实了Skill 才不会在真实使用中给你捣乱。4. Skill 的获取、安装与生态适配4.1 安装位置决定生效范围不同工具对 Skill 的安装位置约定大同小异最常见的两类是用户级和项目级。用户级的目录通常放在用户主目录下的隐藏配置目录里比如 ~/.claude/skills这个位置的 Skill 对你所有项目生效适合放通用型能力。项目级的目录放在 .claude/skills 下面只对当前项目生效适合放跟这个项目强相关、不想带进其他项目的特殊流程。安装就是把整个 Skill 目录复制到对应位置。装完之后怎么确认成功了最简单的方式是问 Agent 一句“你现在有哪些可用技能”如果它能把新 Skill 的名字和能力说出来说明安装成功如果它说什么都不知道基本就是目录位置放错了或者描述信息没解析好。这一步虽然简单但很多人第一次装都折在这里。我见过不下五次目录建错了层级Skill 嵌在子文件夹里Agent 根本扫不到。装完之后自己检查一遍目录树比反复问 Agent 省事得多。4.2 从社区和第三方市场找 Skill 的注意点现在网上能搜到不少“skills 推荐”和“skills 下载平台”之类的资源。社区整理的合集、GitHub 上的仓库、个别工具自带的技能市场都是获取现成 Skill 的有效渠道。我的建议是先看更新频率和活跃度再决定是否采用。Skill 本质上是可执行文档它在跟着模型能力一起演进一个一年没更新的 Skill很可能基于旧模型的行为习惯写的拿来直接用效果会打折扣。另一个安全提醒Skill 是可以让 Agent 执行脚本的所以从网上下载的 Skill 一定要先打开目录看看里面有什么。那种只包含一个 SKILL.md、没有脚本的最安全带脚本的你得确认脚本内容没有恶意行为比如偷偷上传文件或者读取敏感信息。我自己的习惯是从网上下载的 Skill 一律先本地打开看一遍再复制进正式目录。定期清理不再使用的 Skill也能减少 Agent 误匹配的概率毕竟技能库也不是越大越好。4.3 跨平台的格式差异与兼容思路我前面一直强调 SKILL.md 这种通用结构是因为除了 Claude 生态其他 Agent 工具也在往这个方向上靠。比如 Codex 有自己的 skills 机制Reasonix 支持加载新的 skillsHermes 这类第三方工作台也在做技能市场。不同工具之间SKILL.md 的核心思想一致但字段和目录约定会有差异。你从 A 工具上看到一份 Skill原封不动塞进 B 工具里不一定会被识别这是正常现象。如果你打算把 Skill 做成跨平台可用的我有几个建议。目录结构保持 SKILL.md scripts references 这个最小公约数不要依赖某个工具专有的字段。脚本用跨平台运行时优先选 Node.js 或 Python而不是绑定某个平台的技术栈。流程描述尽量工具无关不要在步骤里写死“调用某某浏览器插件”之类除非你非常确定所有环境都有这个工具。按这个思路写的 Skill至少能在几个主流工具之间搬来搬去省去反复改写的麻烦。4.4 用 Git 管理自己的 Skill 仓库Skill 和代码一样一变起来没完没了。我建议从写第一个正式 Skill 开始就用 Git 做版本管理。目录结构可以是 skills/ 下面按领域分子目录比如 skills/frontend/page-review、skills/frontend/contrast-check每个 Skill 目录独立一个 changelog 文件记录改了什么、为什么改。以后你发现问题回溯版本时这些记录比你的记忆靠谱得多。命名规范也需要统一。我自己的习惯是 name 用小写短横线命名法比如 page-reviewdescription 写英文因为模型对英文指令的解析稳定性通常更好。更讲究一点可以在仓库里加一个 README把每个 Skill 的适用场景和依赖列成表格方便自己和别人查找。将来 Skill 数量多了这个索引比什么都好使。我现在的仓库就是这样一个结构每次新增一个 Skill先补 README再写 SKILL.md已经成了固定动作。5. 高频报错与排查技巧实录5.1 Skill 没有被调用怎么定位最常见的抱怨是“我明明装好了Agent 就是不调它”。我排查时一般按三层来查。第一层目录位置对不对文件名大小写对不对。SKILL.md 必须放在正确目录下文件名也不能错别小看这个Windows 和 macOS 文件系统大小写敏感程度不一样很多神秘问题就是这个引起的。第二层description 写得够不够具体。“页面评审”和“对开发者提供的页面 URL 进行详细评审输出指定维度的报告”模型匹配的成功率完全不同。第三层看 Agent 执行日志搞清楚它当时到底看到了什么、为什么选择了别的路径。日志是最诚实的模型嘴上说“我没有这个技能”日志里可能明明扫到了但匹配得分不够两者差别很大。5.2 Agent 误调用不合适的 Skill怎么纠正误调用和调不到是两个极端。如果你发现 Agent 经常“自作多情”地把某个 Skill 用于不相关的任务原因多半是元信息里缺了“不适用范围”。我在前文强调过负面描述一定要写。另外还可以把 description 中容易混淆的邻域词去掉比如你的 Skill 是“页面评审”就不要在描述里写“页面优化建议”免得模型把普通咨询也匹配进来。一旦出现误调用不要急着怀疑 Agent 智力先回看 description 是不是有歧义词。我自己遇到过一次最典型的情况一个“图片压缩工具”的 Skill因为描述里写了“处理图片文件大小”结果用户问“图片文件太大怎么发邮件”也触发了它。把负面排除词补上后问题立刻消失。5.3 多个 Skill 职责重叠怎么排优先级当你的技能库里同时有好几个和前端相关的 Skill比如“页面评审”和“性能清单核查”模型很可能选错。这本质上是一个路由问题。我的做法是给每个 Skill 的 description 明确标注自己的入口条件例如“当用户要求全维度评审时使用本技能当用户只需要性能清单时使用 performance-checklist”。换句话说把类似 Skill 之间互相引用的关系写清楚模型就有据可依了。如果你在跑多 Agent 或者编排框架路由会更复杂Skill 的 description 就更重要因为每个子 Agent 不仅要选对 Skill还得在多个候选里给出优先级判断。这个工作没法偷懒描述写得越细路由越准。5.4 执行中出错与中断的处理我调试时常遇到类似 “Agent execution terminated due to error” 的报错。这类错误大多是执行脚本或调用工具阶段出的问题而不是模型推理阶段。第一步看日志里失败的操作是什么如果是脚本命令找不到或缺少依赖去补装如果是脚本输出格式奇怪导致 Agent 解析失败回查 scripts/ 相关内容把输出改成纯文本或固定 JSON如果是因为上下文太长被截断想办法精简参考资料只保留必要信息。这些排查方式不是万能药但按照“日志 → 定位 → 修哪一层”的思路走大多数情况下都能找回来。等你把一套 Skill 反复打磨几轮你会发现自己对 Agent 的掌控力不知不觉就上了一个台阶。如果让我说这几周折腾 Agent Skills 的最大心得我会讲Skill 不是越写越多越好而是越写越准越好。每次迭代都把边界写得更清楚、步骤更可执行、示例更到位它的价值就越高。与其收藏一堆别人的“万能 Skill”不如把自己手里最高频的一个流程先做成 Skill用起来再慢慢打磨。这大概也是 Agent 开发最有意思的地方——你在教模型的同时其实也是在把自己怎么干活这件事重新想得更明白。