1. 为什么我的Agent总是有脑子没手脚技能库的出发点做Agent项目做到第三个版本我越来越清楚地意识到一个问题大模型本身再聪明脱离了一堆能真正干活的工具它也就是个纸上谈兵的军师。你问它帮我分析一下这份数据它给你回一大篇漂亮话但就是拿不出结果。原因很简单——它既读不了你本地的CSV文件也调不了你项目里的函数更碰不到任何外部服务。这就是我折腾agent-skills这个方向的核心动机。所谓agent-skills本质上就是给Agent配一套标准化的能力配件库把每一个可执行的动作——搜文件、读网页、跑SQL、调API、发消息——封装成带描述、带参数、带调用规约的独立技能单元。Agent在收到用户请求后不是靠模型自己凭空脑补怎么操作而是去检索这份技能库找到匹配的技能卡然后按卡上的说明去调用后端真实函数。说实话我刚入坑的时候也走过弯路。最早我在项目里写了一堆裸函数什么fetch_weather()、read_file()然后直接在system prompt里把它们列给模型看。表面上看没毛病模型确实能调用但一旦函数数量超过十几个prompt就开始失控——描述写长了token吃掉一大截写短了模型分不清什么时候该用哪个。更尴尬的是新加一个功能就得改一遍prompt还要担心改坏之前的调用。所以说skills这套东西不是锦上添花而是Agent工程化之后的必然选择。它解决的核心问题就三个声明标准化、发现自动化、扩展去侵入化。如果你现在正卡在模型能对话但办不了事这个阶段或者已经堆了几十个工具函数但维护起来想骂人那这篇文章基本就是为你写的。我会把我在实际项目中搭建技能库的完整思路、踩过的坑、以及现在跑得最稳的那套结构一次性讲清楚。2. 技能目录结构设计从零搭一个能自我扩展的skills体系2.1 先分清技能和工具的边界很多人以为把函数列个清单就算技能库了其实差别非常大。工具是被调用方技能是带语义的调用方说明书。在agent-skills体系里一个技能应该包含四层信息能力声明这个技能干什么、参数规约调用它需要什么输入、执行体真实逻辑、结果描述返回数据长什么样。我在项目里通常把技能分成三类核心通用类文件读写、网络请求、代码执行、领域业务类查库存、生成报表、发送通知、辅助增强类数据拼装、文本转换、定时任务。这样分类的好处是Agent在做任务拆解时能按领域快速缩小检索范围不至于每次找技能都把全部技能扫一遍——那对context的浪费太大了。目录结构建议这么组织skills/ ├── core/ │ ├── file_reader.py │ ├── http_client.py │ └── code_runner.py ├── domain/ │ ├── inventory_query.py │ ├── report_generator.py │ └── notification_sender.py └── utils/ ├── text_splitter.py ├── data_merger.py └── scheduler.py一开始别贪多每个技能文件保持单一职责。我见过有人把十几个功能塞进一个文件里结果技能描述写了一大篇模型反而搞不清楚入口参数怎么传。宁可文件多一点检索慢个几十毫秒也别让一个技能变成四不像。2.2 每张技能卡必须长这样我在代码里给每个技能配一张元数据卡用JSON格式写在文件顶部或者单独的技能描述文件里。这张卡是整个技能库的核心Agent能不能正确用上这个技能完全取决于卡写得好不好。{ name: domain_inventory_query, description: 根据商品SKU或名称查询实时库存数量与所在仓库位置。适用于用户询问还有货吗、库存多少、哪个仓可以发等场景。, parameters: { type: object, properties: { sku: {type: string, description: 商品编码如SKU-12345}, name: {type: string, description: 商品名称关键词支持模糊匹配} }, required: [sku] }, returns: { type: object, properties: { sku: {type: string}, warehouse: {type: string}, available: {type: integer} } }, examples: [ {request: SKU-12345还有货吗, call: {sku: SKU-12345}, response: {sku: SKU-12345, warehouse: 华东一号仓, available: 32}} ] }注意description这块我踩过最大的坑就在这里。你要用用户会怎么说话来描述而不是用程序员习惯的技术描述。比如本函数通过HTTP GET请求查询外部库存系统并返回JSON结果模型看到这种描述完全不知道用户在什么场景下该调用。后来我改成适用于用户询问还有货吗、库存多少这种场景效果立竿见影——模型匹配准确率从不到七成直接拉到九成以上。examples字段是我自己后来加上的强烈建议保留。模型在小样本场景下非常吃Few-shot这套给一两个典型请求-响应示例比你在描述里写一百句解释都有用。3. 技能执行体编写规范让模型调得准也让你维护得起3.1 输入输出全部JSON化别搞函数重载技能执行体的第一铁律所有参数必走JSON输出也是JSON。别整什么可变参数、默认参数重载这种花活。大模型调用函数时它只能以字符串形式传参进来如果你的函数签名要求一个字典但模型传了一个JSON字符串解析出问题都不知道去哪里排查。我在项目里用的是一个标准流程def execute(self, params_str: str) - str: try: params json.loads(params_str) sku params[sku] result self._query_stock(sku) return json.dumps({code: 0, data: result, msg: ok}, ensure_asciiFalse) except KeyError as e: return json.dumps({code: 1001, data: None, msg: f缺少必要参数: {e}}, ensure_asciiFalse) except Exception as e: return json.dumps({code: 500, data: None, msg: f执行异常: {str(e)}}, ensure_asciiFalse)返回结构统一带code、data、msg三层这样Agent能根据code判断执行是否成功而不是靠猜。code1001表示参数问题code500表示业务异常code0才是成功。这个规约一定要在系统prompt里跟Agent讲清楚否则模型看到返回错误也不知道下一步该怎么办经常硬着头皮把错误信息原样抛给用户——那体验真是灾难。3.2 超时、重试与熔断都放在技能内部另一个容易忽视的点是技能执行体必须自带超时控制和重试逻辑不能指望Agent去处理网络超时。我之前上线一个天气查询技能没做超时设置有一次外部接口卡了40秒Agent就傻傻等40秒用户以为系统挂了。后来所有技能统一加上def _safe_call(self, func, *args, **kwargs): with Timeout(10): return func(*args, **kwargs)超过10秒直接抛异常然后技能内部自动重试一次间隔2秒再失败就返回code500并附带当前服务暂不可用这种用户能看懂的信息。重试逻辑最好做指数退避别一失败就立刻重试那跟不重试没区别。第一次等1秒第二次等2秒最多三次。这个策略不是我自己拍脑袋想的是线上跑崩溃几次之后拿qps曲线对比出来的最优解。3.3 每个技能都要自带小上下文摘要这个设计可能有点非主流但实测收益非常大。我在编写技能的时候除了执行体本身还会在技能卡里加一个import_context模块它专门负责把一个技能相关的上下文信息压缩成给Agent看的前缀摘要。举个例子查库存的技能如果Agent已经通过对话知道用户在华东地区那技能返回结果时可以追加一句用户要求优先展示华东仓库的存量这样模型在汇总输出时就懂得调整权重。这个做法等于在技能层帮Agent做了一次前置信息预处理省得模型自己在长对话里翻来覆去找信息。context_injection: { when: 用户请求中包含华东、上海等地域词, action: 返回结果中优先展示华东仓并在摘要字段注明 }注意这个context_injection别滥用。我最初给每个技能都配了两三条结果Agent容易产生幻觉——它以为是技能返回的真实数据。后来固定规则只允许做排序、过滤、高亮不允许新增任何信息。所以在技能卡里写清楚了这是展示策略而非数据内容。4. 注册中心的自动路由让Agent自己选对工具而不是瞎猜4.1 为什么不能把技能列表直接全塞进System Prompt技能数量少的时候比如只有三五个全塞进System Prompt确实简单高效。但如果你做的是一个稍具规模的项目技能很快会超过二十个。这时候每个技能卡完整展开的描述平均要500~800字二十个就是一万多字每次请求都携带的话光token成本就很可观而且模型注意力会被稀释——它开始分不清相似技能之间的细微差别。我自己项目里的真实数据技能从12个涨到19个之后模型选错技能的概率从4%飙到13%。不是模型变笨了是选择空间变大后描述里的关键词集中度下降了。你说查询库存和查询订单模型有时候真会拿混。所以从第二个版本开始我做了技能注册中心核心思路是先检索、再调用、分两步走。4.2 注册中心的三层路由策略注册中心本质上是一个带索引的技能元数据库。它在启动时加载全部技能卡然后把每个技能的name、description、examples文本做向量化存入内存向量索引。第一步是粗筛。拿到用户请求后先用嵌入模型把请求转成向量从技能索引里捞出Top5相关技能这一步基本在毫秒级完成。粗筛不追求精准只追求别漏掉对的技能。第二步是精排。把粗筛出来的技能卡完整展开连同用户请求原文一起交给Agent让它从这五个里面选一个最合适的。这一步之所以不直接把五张卡全塞进调用提示是因为我们要控制长度、突出候选之间的差异。第三步是参数提取。Agent选定技能后接着让另一个模型调用完成参数提取生成JSON参数串再execute技能执行体。这一步最好单独走一轮不要跟选技能混在一起——思路不一样混在一起模型容易把技能名当参数传。4.3 技能命中日志与反馈闭环注册中心还需要配合一个日志系统记录每次调用的技能名、用户请求原文、Agent本次调用是否在技能卡描述范围内。这个日志的价值在于持续优化技能卡的描述质量。我有一个真实例子技能domain_notification_sender发送通知原描述写的是用于向用户手机或邮箱推送通知消息。日志里发现有好几次用户说提醒我明天开会模型选了这个技能但参数传的是content: 提醒 time: 明天早上9点——明显不对。后来我在技能卡的examples里加了一条当用户要求设置提醒时需先调用scheduler技能创建定时任务再用notification技能发送提醒模型选错的情况立刻少了大半。所以技能卡的描述不是写一遍就完事了要拿真实日志反复改。我基本保持每周翻一次日志、微调两张卡的节奏。5. 实测中的翻车现场与修复方案经验比教程值钱的部分5.1 相似技能互相抢活订单查询和库存查询的混用问题这是我线上跑得最狼狈的一次事故。用户问这个订单现在什么状态系统却调了库存查询技能返回了一串库存数字。查日志发现模型在精排阶段把两个技能都拉进了候选最后选了库存查询因为它的description里出现了状态这个词——我写了适用于查询现货状态。修了两次才修彻底。第一次我只是把库存技能描述里状态改成是否有货、库存数量第二次是在注册中心精排阶段加了互斥规则——当订单查询和库存查询同时进入候选时优先看用户请求里是否出现订单号、快递单号这种订单强特征词。现在这个规则我已经通用化了每个技能卡里增加一个triggers字段列出高置信触发词路由时作为加权重。5.2 技能执行返回太长Agent直接失忆有一次让Agent调用日志分析技能结果返回了一个几千行的原始日志片段模型在生成回答时直接把中间一大段内容截断到context窗口上限前面的工具调用记录全被挤没了——这次对话后续的所有步骤都失去上下文依据。这个问题的根子在技能作者身上不在Agent身上。技能返回体必须做长度兜底。我在所有技能外部统一套了一个后处理函数返回内容超过2000字符时只保留摘要、统计信息和前10条明细并额外返回一个truncated: true标记同时把完整结果写进临时文件并把文件路径放在detail_ref字段里。Agent如果觉得还需要看完整数据可以再调文件读取技能去取。这样既保住了上下文又没丢失信息。5.3 循环调用识别A技能调用B技能B技能又回调A技能还有一个场景比较隐蔽——技能之间存在隐式依赖时模型可能在一次任务里让A技能产出给B技能的数据B技能处理后又触发A技能循环调用停不下来。我第一次遇到时以为是死循环bug查了半天才发现是两个技能卡描述里互相引用了对方的输出格式模型拿A的返回值去驱动B又拿B的返回值去驱动A。解决办法是在注册中心加了一个调用深度计数器单次任务最多执行8次技能调用超过就直接终止并把已获得的阶段性结果汇总返回。另外就是代码审查的时候专门检查技能之间有没有直接引用对方输出的字段发现就改成通过注册中心传递不直接在技能内部硬编码。这套下来循环问题基本绝迹了。5.4 技能描述越改越长小心token收益递减最后给一个忠告技能卡不是写得多就好。我观察到描述超过800字之后每增加100个字的收益就大幅下降甚至出现负收益——模型开始纠结描述里提到但实际参数不支持的分支场景。现在我给自己定了规矩描述300~600字examples至少1条triggers列3~5个context_injection最多2条。超过这个范围就要反思是不是技能本身设计得太复杂应该拆成两个技能而不是硬撑一张卡。这个标准是我被坑了好几次之后才总结出来的做Agent技能库的朋友可以直接拿去当起点。Agent skills这套体系搞完之后我最大的体感是模型不再是一个光会聊天的嘴强王者而是真正变成了一个长了手、会跑腿的实习生——虽然偶尔还需要你在旁边盯着但大部分标准活它都能自己接、自己干、自己给结果了。技能库更像是一套活的说明书随着你往里加东西、改描述Agent的能力边界也跟着同步生长。如果你现在刚开始做这块我建议别追求一步到位先塞五个最核心的技能跑一遍全流程把注册和调用的链路走通再逐步加厚这个技能库。亲手试一次比读十篇教程都有用。