★ FEATURED ARTICLE 前两天整理一批行业数据几十个JSON文件字段结构还不一样。我让Agent帮我转成统一格式的Excel表格第一次对话效果不错等换到下一批文件它又把日期字段识别成文本、空值没处理、列顺序完全乱了。我几乎是重新把规则讲了一遍才勉强跑通。这件事让我意识到问题不在于模型不够聪明而在于我没有给Agent一种专业能力的沉淀方式——每次任务都要从头教一遍本质上是在浪费模型的理解力。Agent Skills这个方案恰好就是冲着这个问题来的。用大白话说它把一类重复出现的专业任务打包成一个技能包一份模型能读懂的说明书加上一段确定性的可执行实现再按约定放到Agent能找到的目录里。Agent在需要时读取技能说明调用对应实现把结果拿回来继续推理。它既不是传统意义上的API封装也不是把一大段提示词塞进系统上下文而是介于两者之间的一套工程约定。这篇文章不搬运官方文档我想用自己动手做技能包的实际经历把Agent Skills拆开讲清楚它解决了什么问题、一个技能包内部到底是什么结构、我怎么做了一个能用的、集成到Agent之后踩过哪些坑以及现在我是怎么维护私人技能包库的。适合正在做Agent应用、想减少重复Prompt的开发者看也适合刚接触这个概念、想快速上手的人。1. 从每次都要重新教一遍说起Agent技能的痛点1.1 我踩过的一个真实场景为了把一批客户反馈数据整理成报表我一开始采用的是把所有规则都写进提示词的方式。前几次还管用可一旦字段映射规则超过十几条加上各种边界情况的说明系统提示词逼近三千字模型就开始选择性遗忘——它记得住后面的规则前面的字段映射就乱了你强调日期格式要统一它反而把金额字段的类型改错了。后来我把同样的规则改写成一段Python脚本配合一个简短的能力说明文件交给Agent输出稳定性一下子提了上来。原因并不神秘脚本每次跑出来的结果完全一致模型只需要判断这个任务要不要调用这个技能以及技能返回之后该怎么向用户解释。判断交给模型执行交给代码各干各的反而不容易出错。这种体验让我意识到一个更普遍的问题很多人做Agent应用把精力全花在提示词调优上却忽略了任务本身有大量确定性的、可复用的处理逻辑。这些逻辑完全没必要让模型每次现场推理把它们固化成技能才是更工程化的解法。1.2 技能包想解决的其实是可复用问题一个经验丰富的工程师会本能地判断一项任务是否值得沉淀。如果它反复出现、规则稳定、可以用代码明确表达那就不该每次都临时手写一遍。Agent的学习逻辑也一样与其让模型每次从零理解什么是CSV字段映射什么是日期标准化不如直接给它一个能干活的工具。对比几种常见做法会更容易理解技能包处在什么位置方案优点痛点写死Prompt接入门槛低规则一多容易失效缺少确定性微调模型深度适配领域风格成本高、迭代慢、不适合频繁更新的业务规则传统API封装稳定可控需要外部系统精准传参语义匹配靠人工完成Agent技能包语义判断交给模型执行交给代码需要维护技能描述与代码质量所以技能包不是要取代上述任何一种方案而是补上了让Agent自己决定什么时候用什么工具这一环。它把一个专家的隐性经验——比如数据清洗的步骤、格式转换的边界条件、报表口径的定义——编码成模型可以导航的说明书和可重复执行的代码。这对团队协作的意义更大一个人沉淀的技能其他人不需要重新发明一遍。2. 技能包的核心拆解一份说明 一段可执行实现2.1 为什么不是普通API也不是单纯写死Prompt有人会问一段能跑的代码加一份说明这不就是API文档吗区别在于使用者。传统API的调用方是另一个程序参数、返回结构、错误码都需要事先约定死技能包的调用方是模型模型通过阅读自然语言描述来做语义匹配它看的是这个技能是干什么的、适合什么场景、输入是什么、输出是什么。你可以把传统API想象成电话簿——你得先知道对方叫什么、号码是什么拨过去才有效。技能包更像工具箱上贴的标签箱子里有扳手、螺丝刀和电钻每件工具都有一张卡片说明用途。模型看到卡片自己判断现在要不要打开这个箱子。判断的准确度取决于卡片写得清不清楚。而它和Promp最本质的差异在于确定性。Prompt给模型的是行为准则不同模型的遵循程度不一样同一个模型在不同温度参数下效果也会波动。技能包给的是可执行实体规则一旦写成代码每次运行结果都一样。模型不需要记住所有细节只需要调用并读取结果。这意味着你可以把最繁重的、最容易出错的部分从提示词里抽离出去。2.2 技能包的文件结构SKILL.md 与实现脚本按我接触过的Agent Skills约定一个技能包通常就是一个目录里面至少包含一份说明文件和一个实现脚本。我习惯的结构是这样的json_to_table/ ├── SKILL.md ├── run.py ├── requirements.txt └── examples/ ├── sample_input.json └── expected_output.csv每个文件的职责很清晰文件作用说明SKILL.md能力说明书给模型看的描述技能用途、输入输出、示例和边界run.py可执行实现给代码跑的完成具体的确定性处理逻辑requirements.txt依赖声明声明运行脚本需要的第三方库examples/示例数据帮助模型理解输入输出结构也可以用于本地自测SKILL.md是灵魂。它通常由两部分组成头部是结构化的元信息包括技能名称、简要描述正文是自由格式的说明写得越清楚模型调用得越准。我后面会专门展开讲怎么写一份好用的说明。2.3 模型在运行时怎么选择技能理解运行机制对技能包设计很有帮助。Agent启动时会扫描所有可用的技能包把它们的关键描述加载到上下文中。你可以把它想象成模型面前摆了一排工具箱每个箱子上贴着标签。用户提出请求后模型通过语义匹配判断哪个箱子最合适然后触发对应的执行脚本。脚本运行完成后输出结果会被当成一段工具回复内容交还给模型。模型再结合用户原本的诉求组织最终的回答。整个过程里模型参与的环节只有两个决定调用哪个技能、解释调用结果。至于数据到底怎么清洗、格式怎么转换完全不经过模型推理。这也解释了为什么技能描述的质量会直接影响成功率。如果描述写得含糊模型可能把处理JSON数据理解成什么数据处理都能干于是遇到CSV文件也尝试调用JSON技能后果可想而知。描述越精确、边界越清楚模型的选择就越可靠。3. 动手做一个自己的技能包以JSON转表格为例3.1 明确技能边界什么该做成技能什么不该动手之前得先判断一个任务值不值得做成技能包。我的经验是三个条件规则是否稳定、出现频率是否够高、是否可以用确定性代码完整表达。数据格式转换完全符合这三条字段映射规则固定每周都会用到写代码可以穷尽所有情况。反过来如果任务本身依赖开放性的语义判断比如帮我把这段话改得更生动一点那就不适合做成技能包。它没有明确的对错标准适合直接让模型发挥。还有一类任务虽然规则明确但只出现过一次做成技能包反而增加维护成本。我建议新手从小而窄的任务切入。比如只处理某一种文件格式、只做某一个字段的标准化先跑通一个极简的闭环体会到模型的调用逻辑之后再逐渐扩大技能覆盖范围。一上来就做一个万能数据处理技能大概率会把自己绕晕。3.2 编写说明文件让模型读得懂我把SKILL.md当成给模型看的产品说明书来写。开头用一句话说清楚这个技能做什么接着定义输入格式然后定义输出格式最后一定要写清楚什么时候不该用。--- name: json_to_table description: 将包含结构化的数组的JSON文件转换为可读的表格CSV/Excel适合字段结构相对规整的批量数据整理任务。 --- # 输入 一个JSON文件路径或者一段JSON文本。JSON顶层必须是数组每个元素代表一行记录字段名保持统一。 # 输出 CSV格式的表格文本首行为字段名。所有字符串去除首尾空格空字段输出为空字符串日期统一为YYYY-MM-DD。 # 示例 输入[{name:A,date:2024/01/05}, {name:B,date:2024-01-06}] 输出 name,date A,2024-01-05 B,2024-01-06 # 不适用场景 - 输入不是JSON或JSON顶层不是数组。 - 需要跨文件关联、数据透视、统计分析等复杂操作。 - 字段结构在多条记录之间不一致需要模糊推断的情况。这段description写得不够宽泛反而更安全。模型看到结构化数组和规整这些限定词就不会轻易把它误用于其他场景。我也刻意在不适用场景里写了几条负面约束模型读到之后能更快排除错误选项减少无效调用。3.3 实现方法体兼容性与容错设计脚本本身的写法也有讲究。核心思路是输入尽量宽松输出尽量严格。能处理单条记录和批量记录能容忍多余的空白字符遇到缺失字段不要直接崩溃把它们填充成空字符串再继续。下面是run.py的核心逻辑import csv import json import sys from io import StringIO from datetime import datetime def normalize_date(value): for fmt in (%Y-%m-%d, %Y/%m/%d, %Y.%m.%d): try: return datetime.strptime(value.strip(), fmt).strftime(%Y-%m-%d) except ValueError: continue return value.strip() def convert(json_text): data json.loads(json_text) if not isinstance(data, list): raise ValueError(顶层必须是数组) if not data: return fields list(data[0].keys()) for row in data[1:]: for key in row.keys(): if key not in fields: fields.append(key) output StringIO() writer csv.writer(output) writer.writerow(fields) for row in data: line [] for field in fields: value row.get(field, ) if isinstance(value, str): if date in field.lower(): value normalize_date(value) else: value value.strip() line.append(value) writer.writerow(line) return output.getvalue() if __name__ __main__: raw sys.stdin.read() try: print(convert(raw)) except Exception as exc: print(json.dumps({error: str(exc)}), filesys.stderr) sys.exit(1)这段代码有几个值得注意的地方日期字段先尝试多种格式解析而不是假设输入一定标准字段集合取所有记录里出现过的键避免某一行多了字段就丢失信息错误信息直接打到标准错误流返回给模型的只有干净的成功输出。这些设计都是为了让模型拿到结果时不需要再做二次猜测。3.4 打包与引入目录、依赖与加载约定脚本写完按前面的目录结构放好在requirements.txt里写清楚依赖。在这个例子里用到的都是Python标准库requirements.txt甚至可以留空但我还是会写上注释说明脚本运行环境。对于需要第三方库的技能这里就不能省。引入Agent的方式取决于你用的Agent框架。最简单的是把技能包目录放到框架约定的skills目录下重启Agent后让它自动扫描有些框架需要在配置清单里手动注册一行记录。不管哪种方式我都建议在正式使用前先用examples目录里的样例数据做一次本地调用确认脚本输出符合SKILL.md里声明过的格式。输出格式一旦和说明不一致模型拿到的就是意外的结果可能导致它组织出错误的回复。4. 技能包与Agent工作流的集成三种常见接法4.1 显式装载把技能名写进系统提示词如果某个技能在当前会话里几乎必然会被用到我倾向于显式装载。比如用户打开一个批量报表助手的对话界面我很清楚报表处理技能是核心依赖那就在系统提示词里直接写一句处理报表文件时请优先使用json_to_table技能。这种方式能减少模型纠结的过程也能避免它在多个相似技能之间选错。代价是会占用上下文空间。每多一个显式引用的技能模型在处理不相关问题时也可能扫到这些文字。不过技能描述通常都比较短比起让模型自己摸黑探索这个开销换来的稳定性很值得。我一般只在关键路径上使用显式装载一个会话里控制在一两个技能以内。4.2 自动发现让Agent自己翻工具箱当技能数量超过十个我基本不会在提示词里逐一引用而是让Agent在启动时扫描技能库自动把描述加载成候选列表。这种方式的好处是扩展性好新技能只要按规范放入目录后续会话就能用上。但它对描述质量的要求更高。自动发现模式下模型要在几十个技能里做选择描述如果没有区分度很容易发生看着都像的情况。我遇到过两个数据清洗类技能一个专处理CSV一个专处理JSON因为description里都写了数据文件模型经常选错。后来我把各自支持的格式明确写进描述的第一句区分度立刻上升误调用的频率大幅下降。4.3 技能编排把多个技能包串成一条流水线单个技能解决单个任务多个技能组合起来就是一条流水线。我做过一个内部用的数据处理流程先从PDF里抽取文本再把文本中的表格结构识别出来接着清洗字段最后汇总成统计报表。这个流程里至少有四个步骤可以用技能包表达模型只要按顺序调用即可。实际效果比我想象中要好。因为每一步都是确定性执行模型只需要根据上一步的输出决定下一步的参数。步骤之间的数据用JSON传递格式稳定的话几乎不需要模型做额外的格式转换。不过链条变长之后每一步的输出都要严格执行约定否则后面环节会连锁出错。这也让我养成一个习惯技能包的输入输出尽量统一成JSON相当于给整条流水线定了一个内部标准接口。5. 实测中的坑命名模糊、上下文脆断与过度调用5.1 技能描述写得太宽模型就乱用这是我踩过的第一个坑。起初我把json_to_table的description写得很宽处理各种数据文件提取结构化内容并生成表格。结果用户问一句今天天气怎么样模型都会尝试调用一下“data_processor”技能然后对着报错信息发呆。原因很清楚描述里的各种数据文件这些词给了模型过度泛化的空间。解决办法是准确描述。我现在写description有一条原则用三个要素锁定边界。一是输入类型二是核心动作三是不适合处理的情况。宁可写处理包含结构化对象数组的JSON文本也不要写处理各种文件。窄是技能描述的安全词。5.2 输出格式约定不严后续环节跟着崩第二个坑出在输出端。有一版脚本返回的是Plain Text而不是CSV我忘了在SKILL.md里同步更新输出格式说明。结果模型以为返回的是结构化表格直接把纯文本当成表格引用到最终回复里列间距全乱了。排查了很久才发现问题不在模型而在技能包文档和实现不一致。从那之后我给自己加了一道检查流程每次修改脚本输出格式必须同步修改SKILL.md中的输出说明和示例每次修改实现对Reader的影响都用examples跑一遍回归。技能包的本质是给模型看的手册和给机器跑的代码组成的一个整体任何一边更新了另一边就必须跟着更新。5.3 别把业务逻辑全塞进一个技能包我曾试图做一个一站式数据处理技能把数据清洗、格式转换、统计分析、报表生成全放进去。结果这个脚本越来越长参数越来越复杂模型经常不知道该怎么调用——因为一个技能承担的职责太杂它的描述根本写不清楚。每次修改某个小功能都要担心有没有影响其他部分。后来我把这个大技能拆成了四个独立技能包每个只负责一件事。拆完之后模型调用准确率明显提升我的维护负担也降下来了。这件事给我的教训是技能包应该遵循单一职责。判断方法很简单——如果一份SKILL.md需要分四五个小节来介绍不同功能那它大概率该拆了。5.4 一次翻车记录模型反复调用同一个技能有必要单独复现一次完整排查链路。某天我的Agent突然开始反复调用数据解析技能对一条明显的普通文本提问也执行解析每次脚本都因为输入不是JSON而报错但它还是会再次调用。从日志看模型陷入了一个死循环报错→解释→再调用→再报错。我先查脚本本身确认不传JSON时确实会报错这是预期行为问题不在代码。接着查看该技能的description发现上一轮优化时我加了一句话如果用户提到任何结构化数据都可以尝试解析。这句话成了元凶。模型把都可以尝试理解成都应该尝试于是即使输入明显不是JSON它也会硬调一次来验证。修复方案很简单从description里删除所有都可以任何情况下这类鼓励尝试的词汇替换为仅在输入JSON文本或JSON文件路径时使用。然后关闭了该技能的自动发现改为显式装载确保这轮会话不被过往上下文干扰。排查下来的核心经验是模型会严格按照描述字面意思行动描述里的每一个词都可能被放大解读。6. 让技能包体系真正转起来版本、质量与团队复用6.1 技能包也需要版本管理技能包更新得越频繁越需要版本管理。我见过有人直接覆盖原目录结果几天前还在用的输出格式变了Agent行为也跟着漂移。稳妥的做法是给技能包加版本号并且在SKILL.md头部元信息里记录。依赖某个技能包的Agent应用锁定它声明过的版本范围更新前先在小范围验证。我现在会为每个技能包维护一个CHANGELOG。这个习惯一开始显得繁琐直到有一次回退老版本时救了我——新版本改了日期格式但没有通知下游回退到旧版后立刻恢复了正常。技能包一旦被多个Agent复用它的版本稳定性就和自己维护的核心代码一样重要。6.2 从个人脚本到团队技能库当技能包从个人脚本变成团队资产管理方式也要跟着升级。我采用的是一个集中式仓库所有人按统一规范提交技能包评审的重点不是代码风格而是SKILL.md的描述质量和输入输出契约。一般会请不熟悉这个技能的人读一遍描述如果他能看懂如何使用描述就算合格。同时我会控制技能库的增长节奏。技能包不是越多越好每新增一个都要求它在功能上和现有技能有明显差异。我还建议定期复盘使用频率三个月内没被调用过的技能包要么从库中移除要么重新包装。否则技能库会因为太多相似能力而变得嘈杂模型的选择准确率会显著下降。6.3 哪些场景我建议别用技能包技能包并不是万能的。第一类不适合的场景是极高并发且对延迟极度敏感的服务这类场景直接调用函数库比经过Agent决策再执行快得多第二类是需要深度创意的任务比如写文案、构思产品命名这类任务本身没有标准答案让模型自由发挥比套用固定逻辑更合适第三类是运行环境不允许执行外部代码的场景比如严格受限的沙箱这时候技能包根本无法运行。另外还要考虑一项任务是否值得工程化。如果一个任务只用两次写一段临时脚本就够了做成技能包反而增加维护成本。技能包的价值在于复用而不是把一次性工作做得更漂亮。7. 写在最后的一点体会我现在维护着二十来个技能包覆盖数据清洗、格式转换、文件摘要和日常报表。维护它们不是最大的工作量最难的是坚持写好每一份SKILL.md——描述精确、边界清楚、示例完整。我越来越觉得技能包本质上是在把人的隐性经验显性化。我们做数据处理时脑子里的那套判断规则通过代码固化下来我们怎么跟别人解释做事方法通过SKILL.md固化下来。模型只是这套显性经验的使用者。如果你刚开始接触Agent Skills我的建议很简单挑一个你每周都会重复做、规则又很明确的小任务照着最简单的结构做一个技能包先别管描述要不要写得完美跑通一次完整的模型阅读描述→调用脚本→返回结果链路。你会在那个瞬间理解这套设计到底解决了什么。技能包的学习曲线不长但它对工作方式的影响会持续很久。
阅读完成 · 觉得有帮助？
