把 Agent 项目里的“说明书”升级成“技能包”是最近我做得最值的一件事。先说结论Skills这个概念本质上就是把过去散落在系统提示词、工具函数和项目文档里的能力碎片重新打包成一个个有边界、可复用、能测试的模块。我是在一个内部自动化项目里被逼着走通这条路的最开始所有指令都堆在 system prompt 里结果上下文越塞越满改一处流程要连带调整好几段不相关的逻辑调试体验非常差。后来接触到 Skills 机制才发现之前踩的坑几乎都不该踩。这篇文章就围绕 Skill 的设计、编写、调试和进阶来做完整拆解。适合正在做 Agent 应用、想优化提示词工程、或者单纯觉得“让 AI 稳定干活很难”的朋友。我尽量把每一步讲透包括为什么这么做、实际踩过的坑、以及可以直接抄走的技能包模板。1. 为什么我把 Skills 当成 Agent 项目里的“一等公民”1.1 先看看没有 Skills 的时候我在怎么干活最早我做 Agent 自动化思路很朴素把所有流程说明都塞进系统提示词再把所有外部操作都做成 function calling 工具。看起来挺完整但用起来问题一个接一个。第一是上下文爆炸。一套完整的业务流程少说三四千字多则上万字。每次对话都会把这些内容重新加载一遍模型能记住的“注意力”就这么多真正的用户问题反而得不到足够重视。这就好比一个新人刚入职你把一百页的手册一次性丢给他要求他背下来再干活结果他连你今天交代的重点是什么都没记住。第二是修改成本高。流程里的任何一个环节发生变化比如某个工具的调用参数改了、某个步骤顺序调整了你就得在提示词里找到对应位置小心翼翼地修改还不能保证这次修改不会影响其他无关流程。改着改着你会发现提示词变成了一个只有你自己能读懂的意大利面条。第三是毫无复用性。A 项目里写好的数据处理流程换到 B 项目完全拿不过来只能复制粘贴再改一遍。更麻烦的是这些流程和具体的提示词上下文纠缠在一起根本没法做成独立模块。1.2 Skills 的抽象方式把“流程 脚本 知识”装进一个文件夹后来我接触到 Agent Skills 机制核心思路其实很简单一个技能就是一个文件夹里面包含一份 Markdown 格式的技能说明书通常叫 SKILL.md、一个放脚本和代码的scripts目录以及一个放参考资料或静态文件的assets目录。Agent 在运行过程中会根据用户的需求去检索最匹配的技能包加载它的说明书再按说明书里的步骤去执行脚本。这个设计好在哪里用一个类比来解释过去你是在对话里“手把手教一个聪明但没经验的新同事做事”你说的每一句话他都要消化但可能转头就忘而 Skills 是“直接递给这位同事一本标准作业手册”他甚至不需要背诵只需要在遇到对应任务时翻开手册照着流程走就行。手册里写清楚了什么场景下用、具体分几步、每步做什么、调用什么脚本、遇到异常怎么处理。手册不需要一直放在口袋里需要用的时候再拿出来。这个天然的“按需加载”特性直接解决了上下文爆炸的问题——没被选中的技能包根本不会占用任何对话空间。1.3 选型之后的收益可测试、可组合、可排错把能力模块化以后很多工程上的好处会自然涌现。比如可测试性你不需要关心提示词怎么写才能触发某个行为直接测试技能包在输入特定参数时脚本层能不能给出正确结果即可。一个技能包就是一个黑盒输入、输出、异常都清晰。还有可组合性。拿我手头的一个数据报表项目来说“拉取数据”是一个技能“清洗数据”是一个技能“生成图表”是另一个技能。在某个具体任务里Agent 可以在说明书里写明“如果需要生成图表请先调用拉取数据技能再调用清洗数据技能”技能包之间形成了清晰的流水线关系。这种组合方式比在提示词里用自然语言描述调用关系要可靠得多。排错也变得更舒服。过去流程出错你得去猜是模型理解错了、提示词写错了、还是工具调用时序错了。现在直接定位到具体技能包查看它的脚本日志、说明书步骤、以及 Agent 是否选对了技能几步就能锁定问题范围。2. 一次完整上手从零设计一个图片压缩技能包2.1 需求场景与设计思路我用一个非常容易复现的例子来演示整个流程做一个图片压缩技能包。场景是用户丢给你一个图片目录要求“把图片压缩一下方便发到微信群里”。普通做法是在系统提示词里写“如果你收到图片压缩需求请使用 PIL 库遍历目录下的图片将体积较大的图片压缩到指定质量。”这样写在单一场景下够用但一旦用户问“只压缩 PNG 格式”、或者“把图片和文档一起打包发送”规则就开始互相干扰了。正确的做法是把它封装成独立的技能包。我管它叫image-optimizer。先规划好技能包内部结构image-optimizer/ ├── SKILL.md ├── scripts/ │ └── compress_images.py └── assets/ └── size_guide.txtSKILL.md是说明书scripts目录放核心逻辑assets目录放模型执行时可能需要参考的资料比如“不同平台推荐图片大小”这类知识库文档。2.2 编写 SKILL.md一份能让 Agent 照着执行的操作手册SKILL.md是整个技能包的大脑。它分为两部分头部元信息frontmatter和正文指令。frontmatter 里的name和description直接决定了 Agent 在什么时候唤起这个技能包正文则是一份逐步执行的操作说明。我建议的最小可用模板是这样--- name: compress_images description: 压缩图片、减小图片体积、调整图片分辨率、优化图片尺寸时使用。适用于用户指定目录下的图片文件。不适用于视频、PDF、压缩包。 --- # 压缩图片 ## 前置条件 1. 确认用户提供的源目录存在且目录中包含图片文件扩展名为.jpg/.jpeg/.png/.webp。 2. 如果源目录不存在先向用户确认正确的路径不要自行猜测。 3. 确定输出目录默认在源目录下创建 compressed 子目录。 ## 操作步骤 1. 调用 python3 scripts/compress_images.py --input 源目录 --output 输出目录 --quality 80。 2. 等待脚本执行完成读取控制台输出。 3. 若输出中显示有失败文件则针对失败文件单独报告给用户并说明失败原因。 4. 压缩完成后统计压缩前后的总体积与压缩比例写入最终回复。 ## 常见异常 - 如果提示缺少 Pillow 库先执行 pip install Pillow。 - 如果目录里没有图片告知用户该目录没有可压缩的图片而不是报错。这段说明有几个细节值得注意description 里我明确了“什么时候用”和“什么时候不用”这是为了让 Agent 能精准匹配用户需求同时避免和其他技能包竞争正文里的步骤全部编号且可操作每一步都对应一个明确的动作异常处理写进了技能包里不需要用户在对话里反复澄清。这比在系统提示词里写一堆“如果出现xx异常请如何如何”要规整得多。2.3 配套脚本让说明书里的步骤真正落地说明书写得再好最后还是要靠代码干活。compress_images.py不需要写得多复杂但有几个工程细节值得分享。第一脚本必须能独立运行、独立测试。不要把逻辑写成只有 Agent 才能调用的函数而是用标准命令行参数接收输入这样你在调试时可以直接跑脚本看效果完全不依赖模型。第二输出要给足信息。脚本执行完我要求它输出压缩前后的文件体积、处理文件数、失败文件列表。这些信息会让 Agent 在最终回复里给出有依据的数据而不是凭空总结。第三异常要写得具体。比如“图片格式不支持”“文件正在被占用”这些错误信息最终会原样传到 Agent 的上下文中写得越具体Agent 越容易给出正确的处理建议。核心脚本的核心逻辑其实就是三件事遍历源目录、按质量参数压缩、写出到目标目录。用 Python 的 Pillow 库几十行就能搞定。2.4 测试技能包模拟真实用户请求做冒烟测试技能包写完后不要直接拿去接对话流程。我习惯先用最小测试集做冒烟测试——准备一个包含不同格式、不同大小图片的测试目录然后手动触发一次 Agent 调用观察它是否选中了正确技能、是否顺利执行脚本。这里有一个容易忽略的点Agent 选中技能包靠的是description和用户意图的语义匹配。如果你的描述写得太业务化比如“执行图片压缩流程”用户换个口语化的问法“把图片变小点”模型可能就匹配不上了。我的经验是在 description 里尽量罗列同义表达“压缩”“变小”“减小体积”“优化尺寸”“压一下”覆盖率越高触发越稳。冒烟测试没问题后再扔几个边界问题给它空目录、不存在的路径、带特殊字符的文件名。这些场景不需要提前写好答案关键是观察技能包在异常情况下会不会优雅地反馈而不是卡在半路让用户干等。3. 技能包的内部结构解析描述词、步骤指令与依赖管理3.1 description 是最被低估的入口设计很多人写技能包把 90% 的精力花在操作步骤上却忽略了description里的几十个字。但我要说description决定了你的技能包有没有机会被使用。为什么这么说因为 Agent 在选择调用哪个技能包时本质上是做一次检索和匹配。它读到的第一个文本就是description。如果你写得含糊比如“负责图片相关事务”那模型面对一个“把图片改成黑白”的需求也可能会唤起这个技能包然后你的脚本可能并不支持灰度化流程就崩了。我建议的写法是先说触发条件再说输入参数最后说边界。正面例子是“用户要求压缩、减小图片体积、调整分辨率时使用输入为源目录路径与输出目录路径不处理视频和PDF”。反面例子是“图片处理工具”。一个好用的技巧是写完 description 后自己试着用五个不同的问法去触发它如果连着两个问法匹配不上就继续补同义词。3.2 操作步骤指令少一点“尽量”多一点“必须”SKILL.md 正文里的操作步骤本质上是在给 Agent 写一份执行脚本。但很多人会不自觉地写成“发挥题”比如“对图片进行高质量压缩确保效果美观”。这种描述的好处是给了模型自由发挥的空间坏处是你无法预测它会怎么发挥。我自己的原则是凡是预期的行为就是“必须”句式凡是允许模型自己做判断的地方才用“可以”句式。举例来说“压缩后必须删除源文件”和“如果压缩后体积仍然超过 100KB可以尝试二次压缩”。前者是硬性规则不允许偏差后者是优化策略给模型留出判断空间。另外步骤指令不要追求“全”要追求“够”。如果一个技能包需要 40 步指令才能讲清楚大概率不是指令没写好而是这个技能的边界划得太宽了。试着把它拆成两个更聚焦的技能包Agent 的调用准确率和执行稳定度都会明显改善。3.3 依赖声明让技能包可以“随身携带”如果脚本依赖第三方库我建议直接在 SKILL.md 里写清楚依赖关系比如pip install Pillow这不是可有可无的信息。试想一下你的技能包被复制到另一个项目里Agent 第一次执行脚本就报“ModuleNotFoundError”如果你在说明书里预先告诉它“本脚本依赖 Pillow如缺失请先安装”模型就能自主完成环境修复而不是卡在第一步换一种方式反复报错。更重要的是版本。依赖库一旦升了大版本可能 API 就变了。我在 SKILL.md 里会额外注明“测试环境为 Python 3.10 与 Pillow 10.x”这样后续维护的人包括未来的我自己能够快速判断问题出在环境还是出在代码。3.4 assets 目录把“参考资料”和“可执行指令”分开我见过不少技能包把所有知识都写进 SKILL.md变成一份几万字的巨型文档。这个思路有问题——SKILL.md 每次被调用都会完整加载占用大量上下文而这些知识里可能 80% 在当前任务里根本用不上。正确的做法是把高频执行指令留在 SKILL.md把低频参考资料放在assets目录。比如在图片压缩技能包里assets/size_guide.txt可以记录“微信封面建议 900×383公众号头图建议 900×500”这类平台规范。SKILL.md 里只需要写一句话“如需平台推荐尺寸请阅读 assets/size_guide.txt 文件”。这样做的收益是双重的日常执行时上下文保持精简只有在模型确实需要参考规范时它才会去读取那个文件。这种“懒加载”机制是让技能包在长对话场景下依然保持高效的关键。4. 调试实录技能不触发、输出不稳定、上下文被塞满怎么办4.1 问题一技能包永远不被触发怎么调都无效这是新手最容易遇到的拦路虎也是最让人抓狂的问题。排查了几个项目后我发现原因几乎都出在description上——它和用户口语表达之间的语义鸿沟太大。举个具体的例子一个做会议纪要的技能包description 写的是“总结会议记录并输出行动项”。用户问的是“帮我把刚才的录音整理成待办事项”模型没有识别出“整理成待办事项”和“输出行动项”是同一个需求于是技能包被晾在一边模型开始自己用通用的总结能力硬答。排查方法很简单把用户可能说的每一种口语表达列出来逐个对照 description 里的关键词。如果不匹配就扩充描述词。不要觉得这是在做“同义词替换”的笨功夫实际上这就是在教模型做更加精确的语义映射。还有一个排查技巧使用支持“思考过程输出”的调用方式如果有推理日志看看模型在选择工具时实际考虑了哪些描述文本。日志是最好的老师。4.2 问题二脚本执行报错但报错信息对模型毫无帮助脚本本身写得没问题真正执行时报了一个 Python 的原始异常AI 完全不知道该怎么处理。这个问题本质上是“错误信息的设计问题”。我自己写的脚本会在关键节点主动捕获异常并输出带上下文的信息。比如except Exception as e: print(f[ERROR] 图片 {filename} 压缩失败原因: {e}请检查文件是否损坏或格式是否支持。)这样 Agent 看到错误信息时知道“哦是某个具体文件坏了”它就能给出更有针对性的建议比如“这个文件损坏了建议换个文件试试”而不是面对一行OSError无从下手。记住一个原则脚本里的每一个报错都应该像写给用户的客服话术而不是写给程序员的堆栈日志。4.3 问题三技能包内容太长还没干活上下文就被吃掉了技能包的说明书动辄上千行每调用一次都会完整进上下文。当多个技能包轮流调用时上下文空间快速告急模型开始“前听后忘”。我的解决方案是前面提到的分层设计指令部分只保留核心流程长篇的规则文档一律移到assets由模型按需读取。另一个思路是把一些“几乎每次都要用的默认行为”从技能包里抽出来放进系统提示词把“偶尔才用一次的特殊流程”留在技能包里。这样每天共用的是系统提示词占用的上下文只计算一次。4.4 问题四多个技能包互相竞争同一个需求会触发错误技能当技能包多了以后会出现“抢单”现象。比如用户说“把这段文字压缩一下”你的“文本摘要技能”和“文本压缩技能”都会匹配上模型可能选了一个语义上并不贴合的。解决方法是给每个技能包的 description 增加边界声明把“不属于本技能处理范围”的情况明确写出来。比如文本压缩技能描述可以加一句“本技能只处理文章内容压缩删减冗余表达不用于生成摘要、不用于代码压缩。”语义边界越清晰模型的选择就越准确。4.5 排查工具与流程小结我做技能调试时喜欢把排错流程固化下来症状可能原因优先排查点技能不被触发description 与用户意图语义鸿沟大扩充同义触发词检查模型推理日志脚本执行报错错误信息不够具体在脚本中加强结构化异常输出上下文占用量大SKILL.md 承载过多低频内容把长文档迁移至 assets 按需读取多个技能包冲突技能包边界描述含糊在 description 中增加非本技能范围说明执行结果不稳定步骤指令自由度太高把“尽量”改成“必须”或“禁止”这个表格帮我节省了大量重复排查时间现在每次新技能包上线我都会按这个顺序预检一遍。5. 进阶玩法技能组合、版本管理与团队共享5.1 技能组合让一个技能在流程中主动调用另一个技能当技能包积累到一定数量你自然会发现它们之间可以串联。比如我的“数据报表项目”里“拉数据”“清洗数据”“转 Excel”就是三个独立技能包但它们在流程上是强依赖关系。实现技能组合的方式并不复杂在某个技能包的 SKILL.md 里直接声明依赖关系。比如“生成 Excel 报表”技能的操作步骤里写1. 如果用户提供的是原始数据文件先调用 data_cleaner 技能完成数据清洗。 2. 清洗后的数据写入临时目录。 3. 调用 python3 scripts/build_excel.py --input 临时目录 --output 目标目录。Agent 在读到这一步时会自主去检索并调用data_cleaner技能包。这种“技能包间调用”的能力非常有价值它让一个复杂的任务不用写在一个巨大无比的单体技能里而是由多个小技能包协作完成每个小技能包依然保持简单、稳定、易调试。设计组合关系时要注意一个原则只允许上层技能声明下方技能的调用不要出现循环依赖。A 调 B、B 调 C 没问题A 调 B、B 又调 A 就是灾难。我习惯在技能的依赖声明里加一个“上游/下游”的注释方便日后维护。5.2 版本管理把技能包当代码库来维护技能包的迭代速度和普通代码一样快甚至更快——因为你今天发现 description 写得不够好明天可能就要更新。所以一定要用 Git 管理技能包的仓库。我做版本管理时坚持三个习惯。第一每个技能包是一个独立的目录有自己的 README 和 CHANGELOG。CHANGELOG 里记录每次变更的内容和原因比如“v1.1 扩大描述词覆盖范围解决口语化问法无法触发的问题”。第二使用语义化版本号SemVer主版本号在技能包结构或核心流程变更时递增次版本号在新增功能时递增补丁号在修复小问题时递增。第三修改前先写测试用例。我最低限度的测试是准备一组固定输入要求技能的脚本在三次运行中给出相同结果并且结果符合预期。这听起来很简单但能拦截掉相当一部分“重构改坏”的情况。5.3 团队共享建立技能包评审机制当团队多人都在向 Agent 项目贡献技能包时就需要一个评审机制来保证质量。我在团队里推行过一个“技能包入库检查单”技能包目录结构是否符合规范SKILL.md / scripts / assets 齐全SKILL.md 的 description 是否包含清晰的触发条件和边界操作步骤是否可执行是否包含异常处理说明脚本能否独立运行是否输出结构化执行日志依赖是否在说明文档中声明是否附带最小测试用例一张检查单解决了很多协作问题。因为技能包的质量标准被显式化之后评审不再是靠感觉而是逐项对照。新成员提技能包之前自己就会对着检查单过一遍大大减少了来回打回修改的时间。5.4 再聊一个我自己踩过的坑最后多提一嘴如果你准备在自己的项目里引入 Skill 机制最大的坑可能不是技术而是“过度设计”。我第一次尝试时恨不得把所有功能都拆成技能包连“输出一句话”都要建一个技能。结果技能包数量上来了Agent 的检索负担反而更大了经常在好几个技能之间犹豫不决响应速度变慢。后面我给自己定了一个简单标准如果一个功能只用一次或者一个流程短到能在系统提示词里用三句话写完就不要单独做技能包。技能包的收益来自复用和隔离一个小而常用的功能做成技能包是值得的一个只在这个项目里用一次、又短又简单的功能做成技能包纯属给自己找麻烦。根据我个人经验从三五个核心技能包开始跑通整个流程后再慢慢扩展是入门 Skill 机制最平滑的路径。希望这篇文章能帮你少走一些我走过的弯路。