1. 一堆报错背后SKILLS 到底在解决什么问题先说一件我踩过的事。前阵子在一个 agent 项目里跑文档格式化任务模型对话能力没问题上下文也塞对了指令结果一执行就报agent execution terminated due to error。我把错误日志翻来覆去看了好几遍最后发现问题根本不在 prompt 上而是在于我把太多操作细节写在对话里而 agent 并没有一个稳定的、可复用的执行切片去承载这类任务。那阵子正好赶上社区里到处都在聊 agent skills从 OpenAI Codex 的 skills 写法到 Claude Code 手动装 GitHub 上的 skills再到“前端开发 skills”“LaTeX 排版 skills”“图片生成 skills 安装包”这些关键词热度高得离谱。起初我也觉得这不过就是把提示词整理一下换个名字直到我自己真正把一个任务拆成 skill 跑通之后才意识到这里面的差异比想象中大得多。这个标题里的agent-skills如果只从字面理解很容易被当成“给 agent 一堆技能文件”。但真正把它放到项目里你会发现它改变的是人跟 agent 协作的方式你不用再在每一轮对话里反复交代背景、规则、输出格式而是把这些“约定”固化成一个可以被随时调用、跨项目迁移、甚至能被其他人直接安装的能力单元。说白了skills 就是 agent 世界的“插件化常识”。在这篇里我打算用实际项目里摸出来的经验把 agent skills 的开发、安装、验证、维护这几个环节讲透。适合谁看如果你在做 AI agent 开发、写自定义技能、或者打算从零搭建 agent 工作流这篇文章应该能帮你少走不少弯路。2. skills 和 prompt、tools 之间边界到底划在哪2.1 技能不等于“多写几段提示词”很多第一次接触 skills 的人第一反应是这不就是 system prompt 加长版吗其实不是。拿我自己最早失败的经历来说我试过把 LaTeX 排版的规则、字号、页边距全部塞进对话里结果 agent 在长对话中越跑越偏要么丢掉前面的格式约束要么参考了错误的样例。原因很简单对话上下文是“易失性”的而技能是“持久性”的。一个合格的 skill通常是一个包含SKILL.md以及若干辅助文件的独立目录。SKILL.md里写的是能力说明、使用场景、执行步骤和边界条件辅助文件里可以放参考样例、模板、脚本、示例输出。agent 在启动一个任务的时候会去读取这个目录而不是依赖你每次临时输入的指令。这就好比你可以跟新同事讲一遍公司流程但不如直接甩给他一本《操作手册》他需要时自行翻查效率完全不同。2.2 和 tools 的区别工具负责“做”技能负责“怎么想”有人会继续问那我直接用 function call 不行吗Agent 开发里的 tools 通常是外部接口封装比如调用搜索引擎、打开一个文件、执行一段代码。tools 偏“执行”它通常是一个确定性的函数入口。而 skills 更偏“认知层面的操作策略”它规定的是 agent 在面对某个类型任务时“按什么套路来处理”。举一个项目里的例子。我需要 agent 做前端开发中的代码审查我写了一个frontend-reviewskill。这个 skill 里不是简单地写“请检查代码”而是规定了先看组件结构再看样式隔离最后检查可访问性。每个步骤都会给出明确的检查项和示例。它没有直接调用某个 API但它在模型推理时提供了稳定的执行框架。你可以在一个 skill 内部接多个 tools比如让 agent 先读取文件、再跑 lint、最后按 skill 里的规则整理报告。所以 tools 和 skills 不是替代关系而是上下层关系。2.3 为什么突然这么多人在找 skills 源站搜索热词里出现了大量“skills 推荐”“常用 skills 源网站”“skills 技能库网址”说明已经过了“教 agent 做事”的阶段大家开始追求“拿来即用”。我自己也是从到处找技能包开始的。开源社区目前确实有一批聚合仓库也有一些带界面的技能市场不过我建议你在下载任何技能包之前都先打开目录看一眼SKILL.md确认里面没有要求你上传敏感信息的步骤。技能包本质上是一段可提示注入的文本用之前要有基本的甄别意识。3. 准备一套能用的 agent skill 运行环境3.1 目录结构是基本功别一上来就写内容不少人第一次手动装 GitHub 上的 skills 时习惯性把整个仓库 clone 下来然后复制粘贴文件到项目根目录结果 agent 根本不认。原因大概率是目录结构不对。不同框架对技能目录的位置有约定。拿我用的 Codex 项目举例它通常是读取本地项目里的.codex/skills/目录如果你在用 Claude Code常见的约定是.claude/skills/或skills/这种路径opencode 也有自己的 skills 目录约定。最稳妥的做法是进入你正在使用的 agent 工作目录执行一下配置相关的命令查看默认路径或者看官方文档里的目录说明。手动安装的基本步骤如下先创建一个合适目录例如skills/latex-format/把从 GitHub 拉下来的SKILL.md放进去如果有附加文件保持相对路径不变用 agent 能识别的清单命令确认技能已被加载如果框架要求编辑配置文件让技能目录生效3.2 SKILL.md 里的头部元信息决定了它能不能被识别很多人把SKILL.md当成普通说明文档这是误区。它的开头部分往往带有结构化的元信息一般用 YAML frontmatter 格式包括 name、description 这些字段。description尤其重要agent 连接时就是靠这个字段来判断当前任务和哪个技能匹配。我见过有人在 description 里写得很泛比如“用于文本处理”实际用起来会发现 agent 压根不会主动触发这个技能因为它不知道该技能适用的具体场景。建议你把 description 写得具体一些适用任务类型、输入条件、输出格式、规避风险都可以放进去。我一般会写两到三句话尽量包含任务的关键词和明确触发条件。3.3 零依赖安装方案不是所有技能都要跑代码有些技能包带了 Python 脚本或 Node 脚本看起来功能很强但安装依赖也是一堆麻烦。从实用角度讲我建议你优先选纯 prompt 型的技能也就是只靠SKILL.md和文本参考文件就能完成任务的技能。这类技能不依赖脚本运行不会因为环境残缺而崩。以我做图片生成 skills 的经验来说真正有用的核心其实是“提示词工作流”——从用户需求到最终画面的拆解步骤、风格设定的思路、以及常见反例。这些完全可以写进文档里不需要调用任何外部代码。你需要的只是一个规范而不是一套整天要更新的程序。4. 动手写一个自己的 skill从一个真实任务的全过程说起4.1 选定任务边界是第一步所谓技能不是越大越好。你写一个“全自动数据分析 skill”听起来厉害但实际上因为任务范围太宽agent 要么执行得模棱两可要么在步骤之间胡乱跳转。我建议把一个 skill 的边界收缩到“一个输入、一个输出、一套固定流程”的程度。我拿一个我已经跑通的小技能举例把 Markdown 文档转成符合部门规范的 HTML 邮件正文。这个任务的输入是 Markdown 源文件输出是一段带内联样式的 HTML。如果只扔给 agent 一句话“把它转成 HTML”结果大概率样式混乱。为此我在 skill 里写清了完整的处理流程。4.2 写好文档比写好代码更重要这个 skill 的SKILL.md主体大致包含这几块任务描述说明该技能适用于将 Markdown 转为可用于邮件发送的 HTML步骤列表先解析标题层级再处理段落、列表、图片引用最后套用内联样式样式约定直接给出一个基础样式表格说明标题用什么字号、正文用什么行高、按钮用什么背景色常见反例例如不要把外链写成不带下划线的裸文本不要把表格转换成嵌套 div输出要求明确要求不输出!DOCTYPE html开头的完整页面只输出邮件 body 片段写入后我还放了一个sample.html作为参考样例。这一招非常管用因为语言模型的 few-shot 能力只有在提供具体样例时才能发挥出来。你写再多的“注意排版美观”都不如给它一个符合预期的小样稿来得直接。4.3 边界条件必须写清楚最容易翻车的不是主流程而是边界情况。比如 Markdown 里有代码块时该怎么办遇到空标题时该怎么处理。我在一开始没写这些结果 agent 处理乱序标题时自己发挥了一套逻辑输出完全不符合要求。之后我干脆在技能里加了一条硬性规则“来源文档中的代码块一律使用 pre 标签并添加等宽字体样式不得省略原代码内容不得使用自定义 div 模拟代码块。”规则越明确执行结果越稳定。所以每写完一个技能我都建议你专门做一轮“边界压力测试”挑几个残缺输入、异常输入去跑看 agent 是不是会犯错。合理补充边界规则通常比反复优化主流程更提升整体表现。5. 从零搭建技能包时最容易忽略的四个细节5.1 目录里的辅助文件命名要有规律辅助文件不要随便叫a1.md、a2.md。agent 读取目录时文件名的含义会影响它的理解。统一用有意义的命名比如reference.md、example-good.md、example-bad.md、checklist.md。这样即使 agent 不打开文件也能从文件名推断出内容范围。5.2 给技能设置“必须输入”和“可选输入”一个常见问题是agent 在缺少必要信息时也会强行执行技能结果产出半吊子成果。在技能文档里明确写出必填字段比如“处理前必须获得目标设备类型”或者“必须确认源文件编码格式”。再进一步你可以在文档中规定如果缺少必需输入先主动向用户询问而不是猜测。5.3 善用“结构化工作流”而不是“自由发挥式”指令写技能的时候尽量避免用“认真分析”“合理考虑”这类模糊词汇。改成“按步骤执行第一步读取文件第二步确认标题层级第三步生成输出”会显著提升稳定性。这里的逻辑是agent 在长上下文里对模糊动词的依赖很低但对明确任务描述和步骤编号的遵循度很高。5.4 尽量在技能文件里内置安全提示我在技能包的末尾通常会写一句“本技能执行过程中不得将文件内容输出到公网不得访问环境变量中的密钥信息”。看起来像废话但它能有效减少 agent 在某次运行中突然“脑洞大开”的概率。技能的文本会作为后续提示词的组成部分在系统层面多设一道防线没有坏处。6. 我整理常用技能源和“技能瘦身”的实操方法6.1 从哪找技能三个维度来判断一个源靠不靠谱现在网上技能仓库很多质量参差不齐。我一般按三个维度来判断一是更新频率长期不更新的技能建议直接跳过因为它大概率跟不上模型的版本迭代二是有没有示例输出没有样例的技能装起来等于盲盒三是维护者的口碑看看有没有人在 issue 里反馈过“误导性输出”。社区里推荐的常用技能源基本上都有共同特点结构统一、路径清晰、附有可运行的例子。至于那些只贴了一个长文 prompt 就声称是 skill 的“伪技能包”我通常直接掠过。因为它们没有目录结构没有上下文感知能力本质上还是一个普通提示词模板。6.2 技能装多了也要学会“清理”就像手机装太多 App 会卡skill 目录里堆太多技能包agent 在匹配相关技能时会变迟钝有时候还会匹配错。有一类用户专门研究清理 skills方法其实不复杂核心就一句话只保留近两周实际会用到的技能其他要么删要么移到归档目录。我在本地目录会加一个归档区比如skills_unused/不参与 agent 加载。每过一段时间我把已经一个月没用的技能挪到那里。这样做能显著降低 agent 按 description 匹配技能时产生的“干扰项”。另外如果你的框架支持配置禁用指定技能也可以直接用注释或配置文件把它关掉不用物理删除。6.3 别被“技能包安装量”带跑经常能看到一些“好用的 skills”列表动辄列了几十个工具。但实际项目里一个 agent 任务链真正依赖的核心技能通常不超过五个。装一大堆花里胡哨的技能最后反而会让 agent 在做简单任务时反复犹豫要不要把技能带进来。我现在的习惯是新技能先在小项目里试跑三到五个真实任务如果效果稳定再决定要不要纳入主技能集。这样做虽然听起来保守但能避免“看起来全能、实则全废”的尴尬。7. 关于“agent execution terminated due to error”的排查链路这个话题我只说一次因为太典型了。很多人在群里发这个报错截图里只有一行红字没有任何上下文。如果你的 agent 在执行一个自定义 skill 时突然终止并且报这个错我的排查顺序基本如下第一看是不是技能内部脚本出错。打开终端手动运行技能引用的脚本确认它是否缺少依赖或传入参数格式不对。第二看技能文件是否损坏。检查SKILL.md里的 frontmatter 是否格式正确比如缺少了结束符、字段名拼错了都会导致 agent 解析失败。第三关掉所有第三方技能再做测试。如果这时候能正常运行说明某两个技能之间发生了冲突把它们逐个启用找到罪魁祸首。第四查执行超时。模型生成文本有长度上限如果技能里的参考文件太长连带输出一起超过了 token 限制也会触发异常终止。解决办法是把参考文件缩小或者让 agent 只按需读取参考文件的特定段落。大多数“执行终止”类的错最后都逃不过这四个原因之一。你甚至不用去看复杂的 traceback直接按这个清单走一遍能省下大量时间。8. 从“会写技能”到“让技能真正被用起来”如果你已经写好了几个技能接下来最忌讳的是把它晾在目录里不管。一个技能如果没有被真实使用过你永远不知道它在哪些环节会表现不稳定。我的做法是主动在项目里设计几条会触发技能的工作流然后跑一遍完整任务。不要只测试标准输入还要测一测“用户输入里带了与技能无关的内容”时 agent 的表现。只有让技能在复杂信息流中主动被选择和执行它才算真正和 agent 融为一体。另外多注意 agent 版本更新带来的行为迁移。同一个技能在旧版模型上表现稳定换了新模型之后可能执行逻辑就变了。这不是技能写错了而是模型对文本的解读方式发生了偏移。遇到这种情况不用急着推翻技能先微调描述字段里的触发条件通常就能解决。关于 agent skills 的开发目前还没有一个“标准答案”各家框架的约定也在快速演进。但底层逻辑是确定的把你有价值的执行经验沉淀成一个个可复用、可安装、可验证的能力单元然后让 agent 在恰当时机把它们调出来。这件事做顺了不仅单次任务的准确率会提升你积累的技能库本身也会成为一笔越来越值钱的无形资产。