“agent-skills”这个标题乍一看挺抽象但它其实是过去一年里我一直在折腾的一个方向给智能体Agent配一套结构化的“技能库”让AI不仅能聊天还能真正干活。我见过太多项目把一堆工具函数塞进一个巨大的提示词里刚开始跑得通改两次就乱成一团。后来我把思路切换到“技能化”——把每个能力拆成独立的、可描述、可调用的技能单元整个系统的稳定性、可扩展性和调试效率都上了一个台阶。这篇博文我就把整套设计思路、目录结构、描述规范、执行循环和踩过的坑完整写出来给正在做Agent相关项目的开发者参考哪怕你目前只有一个模糊的想法也能照着搭出第一版。接下来的内容全部来自我自己的实测经验不是官方文档的搬运有些取舍和细节只有真跑过一遍才会懂。1. 为什么Agent需要一套“技能库”从单体Prompt到可复用技能的演进先聊聊背景。Agent这个概念火了之后大家最开始的做法都很粗暴把系统提示词写得很长很长把需要调用的函数、参数说明、注意事项全部塞进去。GPT-4级别的模型还能勉强扛住但等到模型换成轻量级或者任务复杂度上来这套方案立刻露馅——上下文窗口被占满、调用格式乱套、加一个新功能就要重写整个提示词。我自己第一次踩这个坑是在做一个数据整理助手。起初只需要读CSV、算平均值、生成图表我把这些函数全部写进提示词效果还行。但用户需求开始分化之后有人要导入Excel有人要清洗异常值有人要按周汇总提示词膨胀到四千多个字模型开始出现幻觉式的函数调用——比如把参数名写错或者凭空捏造一个不存在的函数名。那段时间我天天在做同一件事在日志里翻“为什么模型又调了一个没注册的函数”。技能库的核心思路就是把这些函数逐个封装成“技能单元”每个单元包含清晰的名称、功能描述、参数定义由Agent根据用户意图动态决定“今天要用哪个技能”“怎么组合”。说白了就是让Agent从“背下一整本说明书”变成“对着目录查手册”——后者明显更可靠扩展起来也更轻松而且每套技能写完可以做单元测试不用为了一个小改动把整个提示词翻一遍。这套思路不仅适用于大模型应用开发凡是“AI 工具调用”的场景都适用。你在做的可能是智能客服、内部知识助手、自动化报表甚至是一个会操作浏览器的数字员工底层逻辑完全一致场景越复杂技能拆得越细效果越好。1.1 单体Prompt的瓶颈单体Prompt之所以会失败最大的麻烦在于“模型需要同时记住太多东西”。模型既要理解用户意图又要回忆起所有可用函数还得按正确的JSON格式输出调用指令每一个环节都有出错概率而错误概率会随着函数数量线性增长。另外一个容易被忽略的问题是提示词里为了描述清楚每个函数往往要写上一大段自然语言解释。这段解释在模型眼里和其他上下文没有区别处理时会大量占用宝贵的注意力资源。结果就是模型回答简单问题时可能表现良好一旦涉及复杂一点的组合逻辑就开始答非所问。我实测中印象最深的一次是模型把“筛选日期大于2024-06-01”的参数传成了“日期等于2024-06-01”原因就是它在长提示词里把这两个概念的边界模糊了。1.2 技能库带来的三个直接收益技能库的收益用三个词概括就是可维护、可测试、可演进。可维护新增技能时不用动旧代码只需要在技能目录里加一个文件夹然后注册到技能列表里。旧技能出了问题也只需要改那一个文件不会牵连其他部分。可测试每个技能都可以单独写测试用例输入模拟参数、检查输出格式量化地知道这个技能是“成功的”还是“失败的”不用等到整个Agent跑一遍才发现问题。可演进技能库是一个开放的集合可以随业务需求持续增加。今天加一个“发送邮件”技能明天加一个“查询库存”技能后天加一个“生成周报”技能Agent的能力边界被不断推宽而每一次扩展对已有功能的影响都极小。这个逻辑和写单体服务与微服务的区别很像。你当然可以用单体架构做出能跑的项目但一旦业务复杂到一定程度拆分带来的优势就会完全碾压耦合在一起的代码。Agent的技能库就是这个场景下的“领域模块拆分”。2. 环境准备与仓库骨架先把技能目录设计对后面少走弯路既然决定做一套技能库第一步不是急着写代码而是把仓库的目录结构设计清楚。好的目录结构本身就是一种“文档”新人接手时不用看你解释看一眼目录就大概明白项目的形态。而且目录结构一旦确定后续的自动化注册、批量测试、文档生成都可以建立在它的基础上少做很多重复工作。我推荐的结构长这样agent-skills/ ├── skills/ │ ├── data_processing/ │ │ ├── __init__.py │ │ ├── skill.yaml │ │ ├── implementation.py │ │ └── tests/ │ ├── visualization/ │ │ ├── __init__.py │ │ ├── skill.yaml │ │ ├── implementation.py │ │ └── tests/ │ └── communication/ │ ├── __init__.py │ ├── skill.yaml │ ├── implementation.py │ └── tests/ ├── registry.json ├── agent_core.py ├── requirements.txt └── README.md每个技能占一个独立目录目录名就是技能组的命名空间。目录内部skill.yaml是技能的“说明书”负责描述这个技能是干什么的、参数长什么样、有哪些前置条件implementation.py是真正的执行代码tests/里放的是这个技能独立的测试用例。registry.json是全局的技能注册表它的作用相当于一个“目录索引”Agent在启动的时候会读这个文件把所有可用的技能加载进来。这个文件通常由脚本自动生成不需要手写但为了理解机制还是建议先手工维护一个最小版本看看效果。2.1 技能目录的命名约定技能目录的命名看起来是小事但实际影响很大。命名的核心原则是按能力领域分不按功能点分。比如“data_processing”里放读取CSV、清洗数据、转换格式这些相关的技能而不是建一个“read_csv”目录、再建一个“clean_data”目录。领域聚合的好处是当技能数量达到几十个之后你依然能一眼找到相关的一组技能而不是在一个扁平的列表里来回翻。我最初犯的错就是建了一堆非常细碎的目录——“send_email”、“generate_report”、“parse_json”各占一个文件夹。表面上挺清晰但等技能数量到二十个的时候整个项目文件列表变得极其臃肿而且很多技能之间有隐性的依赖关系被目录结构切得七零八碎。2.2 技能描述文件skill.yaml的最小字段每个技能的skill.yaml里至少要包含以下字段缺一不可name: read_csv description: 从本地或远程路径读取CSV文件返回结构化的行数据供后续处理步骤使用 version: 1.0.0 author: your_name parameters: file_path: type: string required: true description: CSV文件的路径支持相对路径或绝对路径 encoding: type: string required: false default: utf-8 description: 文件编码格式默认UTF-8 returns: type: object description: 包含headers和rows两个字段的对象headers为列名数组rows为二维数组字段的设计原则是“给模型看”。description要写得像是一本手册里的一句话介绍既说明功能也说明适用场景甚至标记出什么时候不该用这个技能。比如读CSV这个技能描述里我会写明“适用于标准CSV格式如数据包含复杂嵌套引号请改用read_text后手动解析”。这个细节看起来微不足道但实测能显著减少模型的误用概率。参数定义部分我会尽量给全type、required、default和description。模型看到完整的参数定义后生成调用时的准确率会高很多。特别是required这个字段一定要标清楚不然模型会倾向于省略它认为“不重要”的必填项结果运行时报一堆缺少参数的错。3. 技能描述的质量直接决定Agent能不能“想得起、用得上”写完了目录结构和描述文件接着就是最考验功力的环节——写一段好的技能描述。我现在可以很坦率地说这段描述写得怎么样直接决定了Agent在真实场景下“想不想得起”这个技能、“会不会”正确调用它。为什么这么说因为Agent选择一个技能的过程本质上就是一次文本匹配它读到用户的需求然后把这个需求和候选技能列表里的description文本做语义匹配。description写得太泛模型会在多个技能之间犹豫写得太窄模型会错过匹配。只有描述“恰好”在一个合适的语义尺度上模型才能一选中。更麻烦的是大多数人写description时习惯于只写“功能”不写“边界”。比如一个数据汇总技能你写“汇总数据”四个字模型当然知道它能汇总数据但它无法区分“什么时候该用它”和“什么时候不该用它”。这种模糊性在单个技能时无所谓技能多了之后就变成了频繁的错误调用。3.1 学会写“带场景信号”的描述我后来采用的方法是在描述里加入“场景信号”。所谓场景信号就是告诉模型这个技能在哪些场景下是答案在哪些场景下不适用。具体的做法是在描述中除了功能说明额外加一句“当用户需要X时推荐使用此技能”。举例description: 从CSV文件中读取结构化数据并转换为内部格式。当用户需要分析表格数据、批量导入记录、或对数据做统计计算时推荐使用。若用户只要求预览文件内容改用read_text更为合适。这句描述同时包含了正面的“推荐场景”和负面的“排除场景”模型在做调用决策时就有了明确的参考系。我在项目里实测加了边界描述之后技能调用的准确率从原来的78%提升到了93%提升幅度相当可观。3.2 参数描述里的注意点参数描述的质量同样关键但我发现不少项目会在这里犯一个比较隐蔽的错只描述参数的“字面含义”不描述参数的“使用期望”。比如一个file_path参数你写“文件路径”这没错但远远不够。更好的写法是“CSV文件的完整路径可以是相对路径相对于项目根目录或绝对路径建议使用正斜杠分隔目录”。这样写的好处是模型在生成参数值时会更规范不用你事后做一堆路径格式的清洗工作。另外一个值得注意的点是枚举参数要尽量给出合法的候选值比如encoding参数可以写“支持utf-8gbklatin-1默认utf-8”。模型有了候选列表就极少会生成一个你根本没编码过的编码值。3.3 版本字段别小看模型会读它最后提醒一句version字段别小看。虽然模型不会真的去检查语义版本号的增量逻辑但这个字段的存在让技能有了“代次”概念。当你升级了一个技能的参数或行为时旧版本技能可能还要兼容运行一段时间通过版本号可以追踪到底哪些请求跑的是旧版本、哪些跑的是新版本。配合日志系统你能很清楚地看到每一次技能调用的版本快照排错效率高很多。4. 执行层设计把自然语言变成可验证的函数调用技能库的“说明书”部分决定了Agent想不想用某个技能而执行层则负责把Agent生成的自然语言指令变成真实、可靠的代码调用。这一步是整个系统的骨干部分设计得好Agent跑起来干净利落设计得不好即使技能描述再完美一到运行阶段照样崩。执行层需要处理的核心流程简单说是四步识别意图、生成调用请求、执行技能、回传结果。每一步都有一些看起来不起眼但实际影响巨大的细节我逐一说明。4.1 用Function Calling还是自由文本解析第一件需要决定的事是Agent和技能库之间的“通信协议”。我推荐直接使用大模型的函数调用能力Function Calling而不是让模型生成自由文本再由程序解析。原因很简单函数调用是模型厂商专门优化过的输出格式准确率远高于让模型自由发挥然后你再用正则去猜。如果你用的是OpenAI兼容接口代码骨架大概是import json from openai import OpenAI client OpenAI(api_keyyour_api_key) def load_skills_from_registry(): with open(registry.json, r) as f: return json.load(f) def call_model_with_skills(user_message, skills): response client.chat.completions.create( modelgpt-4o-mini, messages[ {role: system, content: 你是一个擅长调用技能解决用户问题的助手。优先从技能列表中选择合适的技能。如果多个技能需要组合使用请逐个调用。}, {role: user, content: user_message} ], toolsskills, tool_choiceauto ) return response.choices[0].message这里有个关键细节tools参数里的每个技能需要按照模型厂商规定的格式转换成JSON Schema。我的做法是写一个小脚本读取每个技能目录下的skill.yaml文件再自动转换成模型要求的格式并合并进registry.json。这样既保持了技能定义的“人读友好”又确保了“机器可读”。4.2 技能注册表的动态加载等技能数量多起来后动态加载就比静态加载更实用。所谓动态加载是只把当前对话可能用到的技能传给模型而不是一次性把全部技能塞进上下文。实现动态加载的策略有很多最简单的有两种第一种是基于关键词的预过滤。根据用户的消息先做一个轻量的关键词匹配从全部技能里筛出候选技能子集再传给模型。比如用户消息里出现“csv”或“表格”就加载data_processing组里的技能出现“图”或“chart”就加载visualization组里的技能。第二种是基于模型的二次分类。先用一个快速模型对用户消息做意图分类分类结果直接映射到技能组。这个方案更准确但多了一次模型调用多消耗一点Token和时间。我在实际项目里是先用关键词预过滤做第一道筛选把技能集从几十个压缩到三五个再交给主模型做精确的函数调用。效果很好Token消耗也控制在合理范围内实测下来的成本比一次性传全部技能低很多。4.3 执行器Executor与超时、重试机制拿到模型生成的调用请求下一步就是执行。这块我建议写一个统一的SkillExecutor它负责三件事参数校验、执行调用、结果标准化。这里有一个容易踩的坑——模型生成的参数可能会漏掉必填项或者传成错误类型。绝对不能直接拿参数去调函数要先做一轮校验。class SkillExecutor: def __init__(self, skills: dict): self.skills skills def execute(self, skill_name: str, arguments: dict): skill self.skills.get(skill_name) if skill is None: return {error: f技能 {skill_name} 未注册} validated_args self.validate_parameters(skill, arguments) if error in validated_args: return validated_args try: result skill[implementation](**validated_args) return {status: success, result: result} except Exception as e: return {status: error, message: str(e)}执行器还需要处理“超时”。特别是技能里包含网络请求、大文件处理等耗时操作时没有超时机制一个卡死的技能能把整个Agent卡住。我的做法是统一要求技能实现函数支持超时参数或者在执行器层面用线程和Future做超时控制。重试逻辑同样重要。如果一次调用失败尤其是网络类的错误自动重试一两次往往就能解决问题。但重试要有限制我一般最多重试两次并且两次之间间隔几秒避免对下游接口造成压力。4.4 工具调用循环让Agent按需“多步走”一个真实的用户需求很少能靠单个技能一步解决。更常见的情况是“读取CSV - 清洗数据 - 生成图表”这条链路。这时候执行层就需要一个工具调用循环模型生成一个调用执行器执行结果回传给模型模型再决定是否调用下一个技能、最终给用户一个综合回答。这个循环的逻辑不复杂但有一个必须注意的边界防止死循环。我在项目里遇到过一次模型在一个失败结果上反复重试同一个技能整整转了十几轮。后来我给循环加了一个硬性上限——最多连续调用8次工具超过次数就终止循环并让模型基于已有信息直接回答。这个改动看似粗暴但有效避免了绝大多数情况下的失控问题。我还加了一个“相同调用去重”机制如果模型准备调用的技能名和参数与上次完全一致且上次已经返回过一次失败结果就跳过执行直接提醒模型换了方向。这个小逻辑能让Agent的行为收敛很多用户侧的感受就是“AI变聪明了不再执迷不悟”。4.5 结果回传的Token控制执行结果的回传看起来只是把返回值加到上下文里但这里存在一个Token隐患。有些技能执行完会返回很大的数据对象比如读取了一个1万行的CSV直接把全部数据塞进上下文模型会被数据淹没下一轮调用也开始变慢变贵。我常用的方案是给技能定义一个“摘要输出”返回给模型的信息不是原始数据而是数据的摘要。比如读取CSV时不回传所有行而是回传“共10000行列名分别为...前5行预览为...”。这样模型既知道了数据结构又不被完整数据拖垮。预览的行数可以根据需要调整我一般给到5行够模型理解格式。5. 实测一次完整的多技能编排读取、处理、产出数据理论讲再多都不如跑一遍真实案例来得直观。我用一个数据整理的实际场景完整走一遍从用户输入到最终回答的流程。这个案例来自我在项目里的真实测试所有关键环节都保留。用户输入的是“帮我读一下data目录里的sales.csv按月份汇总销售额然后把结果画成折线图保存到output目录。”这个需求明显不是一个技能能搞定的。它至少涉及读取文件、数据处理、绘图保存三个步骤。如果Agent不支持多技能编排用户得手动分成三条指令分别操作体验就很差了。有了技能库整个过程应该自动完成。5.1 第一步意图理解与技能初筛我先把技能列表里所有的name和description打印出来和用户输入做对照。data_processing组里有一个read_csv技能描述里有“读取并解析CSV文件返回结构化数据”data_processing组里还有一个aggregate_by_month技能描述是“按指定时间字段对数据进行月粒度聚合返回月度汇总数据”visualization组里有line_chart_save技能描述里包含“生成折线图并保存到指定路径”。三个候选技能正好覆盖用户需求里的三个环节。但这里要注意技能初筛只是帮你把候选集缩小真正决定调用顺序和参数的是模型本身。我的代码在检测到用户输入里有“读”“CSV”“按月份”“折线图”等关键词后会把这三个技能加入候选然后交给主模型做函数调用决策。5.2 第二步模型生成首轮调用主模型接收到用户请求和候选技能后生成的结果大致是这个形式{ name: read_csv, arguments: { file_path: data/sales.csv, encoding: utf-8 } }执行器拿到这个调用校验参数无误后执行。read_csv的实现会读取文件、解析表头和数据行然后返回一个标准化结构。到这一步我故意不让实现函数返回完整数据而是返回摘要信息和行数据的前几行预览因为后面的aggregate_by_month技能并不需要完整的原始数据它自己会重新读取文件。5.3 第三步模型的循环决策执行结果回传给模型后模型看到read_csv成功继续生成第二个调用{ name: aggregate_by_month, arguments: { file_path: data/sales.csv, date_column: date, value_column: amount } }这里模型很聪明地选择了重新读取文件而不是依赖上一步返回的预览数据。原因是我的read_csv返回了完整的路径和结构信息模型可以判断出后续技能需要的是原始数据文件而不仅仅是摘要。于是aggregate_by_month被执行返回月度汇总结果。这个结果不大可以完整塞进上下文{ status: success, result: { month: [2024-01, 2024-02, 2024-03], total_amount: [10000, 15000, 12000] } }回合继续模型生成第三个调用{ name: line_chart_save, arguments: { data: {months: [2024-01, 2024-02, 2024-03], values: [10000, 15000, 12000]}, output_path: output/sales_trend.png } }绘图技能执行成功生成了折线图文件。模型收到成功状态后认为任务已经完成于是停止调用直接给用户输出“已完成。按月份汇总的销售额折线图已保存至 output/sales_trend.png一月到三月的销售额分别为1万、1.5万、1.2万。”5.4 从实测中总结的三个经验这一整套跑下来我最有感触的三点单独拿出来说第一技能的“返回值设计”要和后续技能的口径对齐。比如read_csv返回摘要信息aggregate_by_month自己重新读文件这套设计的核心是“不同的技能各自负责自己的输入完整性”不要依赖技能间的隐式状态传递。否则一旦其中一个技能升级另一个技能的输入就会悄悄坏掉。第二模型在组合技能时偶尔会把上一步的“样例数据”当作真实数据传给下一步。比如read_csv返回了前5行预览模型有可能会把这5行数据当成整个数据集去聚合。我的对策是在read_csv的描述和返回值里明确标注“preview”字样并且让aggregate_by_month不接收预览参数只接收文件路径。用参数约束的方式堵住误解。第三多技能编排流程一旦固定下来一定要写一个集成测试把“读取-处理-绘图”这个链条整体跑一遍。普通的单元测试只验证单个技能的正确性集成测试验证的是“模型是否会按正确的顺序调用技能”。这个测试的意义是让你在调整某个技能描述或参数时不至于悄悄破坏整条链路。6. 上线前的测试与调试经验我踩过的那些坑希望你绕开最后一个重要的部分是关于测试和调试。技能库的好处之一是“可测试性”强但如果不系统地去测这个好处就完全发挥不出来。我强烈建议在上线前整理一套针对技能库的测试策略至少覆盖以下三个层面每一层我都有惨痛的教训。6.1 单技能测试给每个技能建“黄金样本”单技能测试指的是不经过模型直接用代码调用技能实现函数检查输入输出是否符合预期。这一步的关键是建立一个“黄金样本集”也就是一套手工标注的标准输入输出对。比如对aggregate_by_month这个技能我会准备三份测试数据一份正常的月度分布数据一份存在日期缺失的数据一份销售额字段含空值的数据。对每一份数据手工算出预期输出然后写进测试用例。以后不管谁改了这个技能的代码只要跑一遍测试集就能立刻发现行为是否被破坏。这个测试集看起来工作量大但值得做。因为它提供了技能行为变更的“安全网”让我在改代码时敢放手改而不用提心吊胆地担心某个角落里的功能悄悄出问题。6.2 集成测试固定住调用顺序和参数口径集成测试的核心是验证“模型 技能库”这套系统在端到端场景下能否跑通。一个比较容易上手的做法是用预设好的用户问题和期望的技能调用序列做成一组测试用例。比如上面的“读取CSV并绘图”用例期望的调用序列是read_csv - aggregate_by_month - line_chart_save。测试运行时我先把模型替换成一个模拟器让它严格按照预设序列返回调用请求验证执行器能正确处理链路上的每一步然后再加上真实模型验证真实模型在候选技能列表下是否会生成和预设序列一致的调用。两层都过了才算这条链路是稳的。集成测试最大的价值是能尽早暴露出“技能描述写得不清晰”“参数口径不一致”这类单技能测试根本发现不了的问题。6.3 性能与安全性别忽视“技能被滥用”的可能性最后一个层面是性能和安全性这一块是很多个人项目和早期项目最容易忽略的。比如“用户能否通过自然语言让Agent执行一个高危操作”这不是一个伪命题。如果你的技能库里有一个“删除文件”的技能哪怕你根本没想到让模型调用它只要它出现在技能列表里模型就有可能在某个特定提示下调用它。我给技能系统加了三层防护第一层是技能分级。将技能分成“只读、写入、高危”三个等级高危技能默认不注册进Agent的候选列表除非用户显式授权。第二层是执行前的人机确认。对于写入或删除类的技能在执行前返回一个“确认请求”用户同意后才真正执行。第三层是操作日志。每个技能的调用记录时间、输入参数、执行结果、模型ID全部落盘方便事后追踪和审计。性能方面我建议在技能执行器加一个耗时统计中间件把每次技能调用的耗时、Token消耗记录下来。这些数据能帮你找到最耗时的技能决定是否需要对某个技能做缓存优化或者把某些高频技能替换成更轻量的实现。6.4 调试日志的格式设计调试日志的质量在排查Agent问题时起决定作用。技能库的日志我建议至少要包括以下字段{ timestamp: 2024-06-01T10:00:00Z, session_id: abc123, user_message: 读取sales.csv并按月汇总, selected_skills: [read_csv, aggregate_by_month], skill_call: { name: read_csv, arguments: {file_path: data/sales.csv}, result_summary: {rows: 1000, columns: 5} }, latency_ms: 1200, tokens_used: 1350 }这套日志结构让我在排查线上问题时能按“会话”维度追踪整个调用链用户说了什么、模型选了哪些技能、每个技能执行了多久、消耗了多少Token。定位一个“模型选错了技能”的问题日志里一眼就能看到。回到技能库这件事本身我最大的体会是这套设计把“不确定性”收敛到了可控范围内。模型仍然是不确定性的源头但通过结构化的技能定义、清晰的描述边界、严格的执行校验和完整的测试分层我能让系统在绝大多数情况下表现得稳定可靠。如果你正准备给Agent项目加技能库我的建议很直接不要一上来就追求大而全先挑两三个核心场景跑通链路把技能描述的质量调好把执行器和日志搭好再慢慢扩充。技能库这个体系架构成本远比你想的低但收益会在项目规模变大后越来越明显。