Agent Skills实战指南：从零搭建高效技能包工作流

最近一直在折腾 agent-skills 这套东西起因很简单用 Claude Code 和 Codex 写代码、做自动化任务时总觉得每次都要把同一套规则、同一个流程反复说一遍费 token 不说Agent 发挥也不稳定。后来把常见的操作沉淀成 skills 之后很多重复劳动直接被砍掉了Agent 的表现明显上了一个台阶。这篇就把我整理 skills 的经验、踩过的坑、还有怎么从零搭一套自己的 skills 工作流一次性讲清楚。先说结论Agent Skills 不是花架子它是把“你会但 Agent 不会”的经验固化下来的最小单元。无论你是前端、后端、做 AI 绘画、写 LaTeX 论文还是跑数据比赛只要过程中有重复性、流程化的步骤就都值得抽成 skill。这篇文章会从概念拆起然后讲怎么写、怎么装、怎么调最后附上我实际用过的问题排查表适合所有刚接触 agent 开发、技能包管理的朋友直接照着抄。1. Agent Skills 到底是什么为什么要做“技能化”1.1 从 Agent 的“手”说起工具调用与技能包的区别先讲一个很朴素的比喻。Agent 本身像一个刚毕业的高材生脑子好使知识面广但你让他直接上手干活他往往不知道你公司的流程怎么走、你的代码规范是什么、你出图喜欢什么风格。工具tool是给他的“手”但光有手还不够他还需要一本“操作手册”告诉他什么场景下用什么工具、按什么顺序来、产出物长什么样。这本“操作手册”就是 skill。很多人会把 Skill 和 Tool 搞混。在我自己的实践里这两者的边界其实很明显Tool 是单个可执行的原子操作比如“读取文件”“发送请求”“调用某个 API”Skill 是把多个原子操作组合成一套完整工作流的“指导包”里面既有说明文档也可能带着脚本、模板、示例资源。Codex 和 Claude Code 里都能看到这种设计一个 skill 目录下通常有 SKILL.md 作为入口然后配一堆辅助文件。那它和 plugin 又有什么区别我个人的理解是plugin 更偏向于给宿主应用扩展功能离 framework 近skill 则更像是给 Agent 预置行为模式离 prompt 近。后者不需要复杂的运行时机制本质上是“结构化 prompt 配套资源”这也是它能在多个 agent 框架里被快速复用的原因。提示如果你在选型时纠结用 tool 还是 skill记住这个判断标准——如果这件事你只需要调一次 API那是 tool如果你希望 Agent 拿到任务后按一套固定流程走完出结果那是 skill。1.2 为什么“Agent 开发 Skills”的组合突然成了主流其实最核心的原因就一句话上下文窗口再大也扛不住每次任务都从零开始描述。我最早用 Agent 的时候喜欢把一大段背景、规则、示例全塞进 system prompt。一开始还行等到任务变复杂prompt 越写越长Agent 开始“前面说完后面忘”或者把旧规则套到新任务上。后来接触了 skills 机制才想明白我们原本的思路是“让 Agent 记住所有东西”但更合理的做法是“让 Agent 在需要的时候去查手册”。这个思路之所以能流行还有一个现实基础现在的 Agent 框架越来越成熟harness调度外壳和 agent决策内核开始分层。热词里很多人搜“harness 和 agent 区别”其实 harness 承当了运行环境、工具注册、上下文管理等脏活让 Agent 可以把精力放在“选择哪个 skill、怎么执行”上。两者配合才有了真正可落地的“技能化”开发方式。另一个推动力是社区生态。现在 GitHub 上有大量现成 skills从前端开发、图片生成到 LaTeX 排版、数据比赛应有尽有。相当于你把一群资深工程师的“肌肉记忆”直接下载到本地装进 Agent 里就能用。对我这种什么都想折腾一下的人来说这个生态的价值不亚于当年 npm 的出现。2. 一个 Skill 由什么组成怎么写才能让 Agent 真正听话2.1 Skill 的标准骨架SKILL.md 是大脑其余全是弹药我见过不少刚开始写 skill 的同学直接在目录里丢一个 Markdown 文档就完事。能用但效果通常不好。一个真正好用的 skill标准结构大概是这样的my-skill/ ├── SKILL.md # 入口文件Agent 优先读取这里 ├── instructions/ # 可选分步骤的详细指令 ├── scripts/ # 可选辅助脚本比如处理图片、格式化数据 ├── assets/ # 可选模板、示例图片、参考文件 └── examples/ # 可选输入输出示例few-shot 学习用其中 SKILL.md 是整个技能包的大脑它通常由两部分组成最上面的 YAML frontmatter元信息以及正文的指令部分。元信息里最关键的是 name 和 description因为 Agent 靠 description 来判断“这个技能适不适合当前任务”。如果 description 写得含糊Agent 就不会在合适的时机调用它。SKILL.md 正文的写法也有讲究不能用散文要像给新同事写的 onboarding 文档一样分步骤、列清单、给验收标准。我在写的时候会比较强调“触发条件”和“完成定义”也就是告诉 Agent什么情况下你启动这个 skill做完之后什么样的结果算合格。注意SKILL.md 的 description 不是写给人类看的是写给模型看的所以一定要包含关键词和触发场景。比如“用于生成博客封面图输入主题返回 1200x630 的 PNG适合社交媒体配图”这种描述要远比“图片生成技能”有用。2.2 前端开发 Skills 和图片生成 Skills两个典型拆解拿前端开发和图片生成这两个最热门的场景来举例。我以前写前端时常遇到一个困境Agent 确实能生成页面但项目里既有 Vue 又有 React还有自己的组件库和样式规范Agent 默认生成的代码风格总是对不上。后来写了一个前端开发 skill里面几十行说明把组件写法、样式命名规范、目录结构、常用依赖选型全部固定下来再让 Agent 干活出来的代码几乎可以直接进 review。这个 skill 还带了一个 checklists 文件让 Agent 在交付前逐项自查比如 props 类型是否写好、是否有多余 import、响应式断点是否覆盖。图片生成 skill 是另一个有趣的方向。很多人以为这种 skill 需要写代码其实核心是 prompt 模板库。我会把一个“AI 漫剧/插画封面”的 skill 设计成用户输入故事主题skill 自动拆出角色设定、场景氛围,再结合风格关键词渲染成一段高质量绘图 prompt。与其每次手动调 prompt不如让 skill 帮你完成“翻译”出图稳定度提升非常明显。比较有意思的是我还在 skill 里放了几个“反面案例”截取一些常见的低质量 prompt 和对应修正版本。模型看过这些对比之后对“好 prompt 长什么样”的理解会具体很多。这个技巧同样适用于写代码类的 skill。2.3 手把手写一个 LaTeX 排版 Skills从零到能跑为了让你能直接照做我用“怎么做一个 LaTeX 排版 skills”来演示一遍完整过程。这个场景在学术写作、建模比赛里都是刚需。我的目标让 Agent 拿到一段论文草稿后帮我排版成符合模板的 LaTeX 文档。skill 创建过程分四步第一步建目录和 SKILL.md 文件。mkdir -p ~/.claude/skills/latex-formatter/scripts mkdir -p ~/.claude/skills/latex-formatter/examples由于我用 Claude Code 比较多默认放在~/.claude/skills下面如果你用 Codex通常是~/.codex/skills或者项目目录下的.codex/skills规则都类似。第二步写 frontmatter。--- name: latex-formatter description: 将 Markdown 或纯文本论文草稿转换为符合标准模板的 LaTeX 文档 适用于学术论文、建模比赛报告、学位论文排版。 当用户要求“排版”“转 LaTeX”“生成论文模板”时使用。 ---第三步写正文指令。我会明确告诉 Agent先识别文档结构标题层级、图表位置、引用格式再选择合适的包和模版最后编译并修复报错。最好还把“不要在导言区堆无关宏包”“图表使用 caption 和 label”这类定制规则写进去。第四步放一个 examples 目录里面存一份简单的论文示例和对应的输出结果。Agent 在模糊的时候会模仿示例输出这比任何文字说明都来得有效。3. 搭建一套能落地的 Skills 工作流3.1 常用 Skills 源网站和安装路径去哪找高质量的包写 skill 之前建议先去社区里逛逛站在别人的肩膀上干活。目前来找 skills 比较靠谱的几个渠道GitHub 上聚合类仓库有人专门维护 awesome-skill-type 的资源列表里面按前端、后端、写作、绘画、数据处理分类整理质量参差但胜在数量多适合找灵感。各框架官方文档里的集成指南Claude Code 和 Codex 的官方文档都会列一些已验证过的 skill这部分最稳妥。社区分享帖子和个人博客很多资深开发者在自己的博客里分享技能包质量通常比聚合仓库高但需要自己甄别。有人可能会问为什么不在某个统一“应用市场”里装原因是 skills 生态还太早期各家 Agent 框架的目录格式又不完全一致。目前最通用的方式还是直接从 GitHub 仓库或者个人仓库下载到本地对应目录里手动装。3.2 手动安装 GitHub 上某个 Skills 的两种方式不管你是从哪个渠道找到的 skill安装原理都差不多把技能包目录放到 Agent 能读到的 skills 路径下。以 Claude Code 为例官方默认会扫描两个地方用户级目录~/.claude/skills/所有项目共享和项目级目录.claude/skills/当前项目专属。一种方式是手动下载。你可以在 GitHub 仓库页面把单独文件夹下载下来或者用命令的方式比如git clone https://github.com/your-id/your-skill-repo.git ~/.claude/skills/your-skill另一种方式如果仓库只包含一个技能包也可以通过代码库工具的复制功能一次拉取。装完之后记得重启你的 Agent 会话让它重新扫描 skills 路径。很多“装完但没生效”的问题十有八九是没重启。提示项目级目录适合放团队内部约定的技能包比如公司组件库规范、发布流程检查。个人通用的效率技能建议放在用户级目录做到一次安装处处可用。没有现成源的时候还要学会“手搓”。我自己会用同样方式新建一个仓库把折腾出来好用的技能包都整理进去再用分支管理不同版本。这里提一个建议别急着做“大而全”的技能包先把单个场景的流程跑通再迭代扩充。3.3 如何规划自己的 Skills 目录避免变成一团乱麻用过一段时间 skills 之后最大的问题已经不是“不会装”而是“装太多”。我一个朋友的目录里躺了上百个技能包结果 Agent 选技能时反而犹豫不决甚至频繁选错。后来我整理了三条规划原则第一按“任务类型”而不是“工具类型”分类。比如不要建“Python 技能”“Shell 技能”而是建“爬虫技能”“数据分析技能”“自动化报表技能”。这样 Agent 描述里能更好匹配用户意图。第二控制单一 skill 的职责范围。一个 skill 只做一件事哪怕事情只覆盖两三个步骤。Skill 太臃肿会造成两个问题一是容易被误触发二是写 prompt 时容易前后矛盾。第三及时清理 deprecated 技能包。目录里的技能包应该和代码一样常删常新。我每隔一段时间会把最常用的 10 个技能包提出来做精修其余基本不动。什么“越全越好”在 Agent 工程里是不成立的。3.4 多技能协同让 Agent 在多个 Skill 之间自由编排等你技能包多了会遇到一个更高级的问题一个任务往往需要多个 skill 协同。比如做一个“AI 漫剧解说视频”可能需要图片生成 skill 出分镜、视频剪辑 skill 合成片段、文案写作 skill 写配音脚本。这时候 Agent 会在内部对任务做拆解决定先后调用哪些技能以及如何传递中间结果。这里有一个很关键的设计思路技能包之间不要写死“我调用你”的强依赖而是通过共享的中间文件协议来通信。比如图片生成技能输出统一格式的 JSON 描述文件视频剪辑技能读取这个 JSON。这样即使以后替换掉其中一个技能包整个流程也不会崩。我实际体验下来让 Agent 自主编排多个 skill它的成功率比“一个 goto prompt 解决所有事”高很多。原因在于每个 skill 都是一个小模型擅长的局部操作叠加之后复杂度反而下降了。这就是 agent 开发里常说的“组合式智能”。4. 调试、评估与常见问题排查4.1 遇到 “Agent execution terminated due to error.” 的定位思路这是我在各种 Agent 框架里遇到最多、也最让人抓狂的报错。好在这条报错虽然可怕背后的原因通常就那么几类。第一类技能包路径错误。给了 Agent 一个不存在的 skill 路径或者 SKILL.md 里写了个不存在的文件名。排查方法很简单先确认路径拼写再确认文件是否存在。第二类环境缺少依赖。有些技能包会调用 Python 脚本而脚本里import的库没装全。这时候去终端手动跑一遍脚本看会不会报错通常能立刻发现问题。第三类上下文冲突。Agent 在连续执行多个 skill 的时候可能因为前一个 skill 输出的内容不符合预期导致后续工具调用传入非法参数。特别是图片生成类技能经常因为尺寸格式不对导致整个流程终止。我的排查顺序固定是先看错误发生在哪个技能、哪一步再去手动执行对应脚本看依赖和参数最后才怀疑模型层面的问题。90% 的 case 都能在第二步解决。4.2 Skills 不生效、或总选错技能的排查清单另一种常见的无语情况是技能包明明装好了Agent 就是不调用。我刚开始用的时候也遇到过明明写了个非常好用的技能包但模型每次都无视它。排查方向有这么几个先看技能描述里有没有写清楚触发条件。模型判断是否调用 skill 的主要依据就是描述文本。如果你只写“这是一个排版工具”它当然很难把“我想生成一个论文”和这个工具关联起来。要写“当用户要求生成论文、排版文档、转换 LaTeX 时使用”。再看技能包是不是放在当前会话能扫描到的目录。有些 Agent 框架默认不扫描项目外目录所以你可以把技能包临时复制到项目目录里试试排除路径问题。最后检查 SKILL.md 的格式。YAML frontmatter 的缩进写错或者 description 太长被截断都可能导致模型读不到有效信息。注意有些框架对 frontmatter 的字段有严格限制name 里不要带空格和特殊字符。4.3 常用 Skills 推荐与避坑清单实测版我在实战中经常会用到下面这些技能包推荐的时候我也标注一下容易踩的坑技能类别推荐用途容易踩的坑前端组件开发按项目规范生成组件代码规范写得太粗输出风格漂移建议把样式规范单独写成一个文件图片生成/封面设计博客配图、漫画分镜生成prompt 模板要定期更新不同绘图模型的风格关键词差异很大LaTeX 排版论文、建模比赛报告排版别忘了处理中文支持和字体配置否则编译容易失败数据处理与图表快速生成统计图表和报表依赖库多建议在 skill 里写清楚需要的 Python 包和版本团队代码审查按团队规范审查代码别让它只查格式要告诉它重点审查逻辑、安全和性能我自己写技能包的时候还有一个避坑心得不要把一个复杂流程的所有细节全部塞进 SKILL.md模型读长文档时容易出现注意力分散后面的规则经常被忽略。我把长技能包拆成“主说明 子文档”主说明只负责流程概览细节放到子文档里让 Agent 在执行到对应步骤时再去读取。这个模式是我用过之后觉得最稳定的。注意如果是给团队用技能包一定要配一个 maintainer 和版本记录不然规则有改动大家用的还是旧版最后“各说各话”。我一般会在技能包目录下放一个 CHANGELOG.md记录每次改动的原因和时间。4.4 如何评估一个 Skill 到底好不好用不要凭感觉很多人写完了 skill 就直接用也不评估效果这其实挺可惜。因为技能包这种东西改进空间非常大但必须用数据衡量。我习惯用一组“任务成功率”来评估。具体做法挑 10 个真实任务作为测试集分别用“开 skill”和“不开 skill”两种方式跑一遍。对比几个维度任务完成率、平均耗时、输出是否符合要求、需要人工干预的次数。如果一个技能包能让完成率提升 20% 以上那它就是值得放主目录的优质技能包否则建议继续打磨。另一种评估方式是对比多个 skill 在同一任务上的表现。比如你有两个网页抓取技能包就分别跑同一个站点对比抓取结果完整性、字段正确率、以及异常处理的妥当程度。代码类的 skill 还可以配合 evals 一起用做成自动化回归测试每次修改技能包之后自动跑一遍看有没有破坏原有能力。这里我要特别说一下Agent 的执行结果有随机性一次跑成功不代表次次成功。至少跑三次再下结论不然你可能会为了偶尔一次失败去改一个本来已经很好的技能包越改越糟。写在最后的一点个人经验我自己的体会是skills 这套体系最大的价值不是帮你省了多少 prompt token而是逼着你把“自己会但描述不清”的经验结构化。刚开始写第一个技能包时你可能觉得麻烦甚至有点矫枉过正但等你积累了十几个经过实战打磨的技能包再回头看以前那套“每次重新写 prompt”的做法真的回不去了。最后再分享一个小技巧不要只写“能跑”的技能包务必在每个 skill 里留一个 troubleshooting 章节。你把平时遇到过的坑记下来Agent 出错时它会自己去翻阅这部分大大的减少重复排查。我很多技能包的第一版都是“能用”加了 troubleshooting 章节之后才真正“好用”。希望这篇文章能帮你少走一些弯路早日建立起属于自己的 agent 技能库。