agent-skills这个标题最近在AI应用开发者圈子里出现的频率越来越高。一句话说清楚它是什么它是给AI智能体Agent准备的一套“技能库”机制让大模型不再停留在“会聊天”的层面而是真正具备“会干活”的能力。换句话说当你希望一个智能体去查数据库、发邮件、操作Excel、调用业务API甚至跨系统完成一整条业务动作时你需要一套结构化的方式把这些能力定义好、注册好、暴露给模型去调度这套方式就是agent-skills。它能解决的问题非常具体没有技能体系的agent本质上还只是个高级聊天机器人你问它什么它说得头头是道但让它干实事就抓瞎有了技能体系agent才变成真正能落地的自动化执行者。这篇文章适合正在做LLM应用落地、想做RPA替代方案、想在内部搭建企业级智能助手的开发者也适合那些正准备从“单次调用大模型”升级成“搭建可持续扩展的智能体系统”的团队。我会从概念拆解到架构设计再到完整实操记录和踩坑实录一次性把agent-skills这套东西讲透。1. agent-skills到底是什么从“会聊天”到“能干活”的关键一跃1.1 为什么突然都在谈“技能”这几年LLM应用的发展脉络其实非常清晰。最开始大家沉迷于提示词工程想尽办法让模型生成的文本更准确后来进入RAG阶段开始给模型接上外部知识库解决“模型不知道”的问题再往后大家发现光知道还不够还得能做事于是Agent成了新的焦点。Agent这个词其实早就有但真正在大模型时代被重新定义是因为模型具备了推理reasoning和规划planning的能力。它可以理解用户的目标拆解成步骤然后一步步去执行。但这里有个巨大的鸿沟模型能“想到”该做什么却不代表它“能”做什么。它没有手去点按钮没有权限去查数据库没有通道去调用第三方接口。这些“手脚”就是技能skills。我见过很多团队在刚开始做Agent时最普遍的错误是盼着模型本身“万能”。他们给模型一个很高的期望结果发现模型在关键动作上要么瞎编、要么卡住。问题的根子就在于没有给模型一套可靠、清晰、可调度的外部能力。agent-skills要解决的核心问题就是把“模型想做”和“系统能做”之间那座桥搭起来。从产品角度看技能体系也是Agent从“Demo级”走向“生产级”的分水岭。一个只能回答问题的聊天机器人用户新鲜感一过就扔了而一个能自己完成报销流程、能定时汇总报表、能跨系统同步数据的助手才是真正让用户愿意天天打开的东西。所以“技能”这个词虽然听起来朴素背后却是一整套工程化思维的转变。1.2 技能系统到底解决了什么问题从工程角度拆解一套好的agent-skills体系要解决三个层面的问题。第一层是能力暴露。系统内部有无数API、函数、数据操作但模型不可能都“知道”。技能体系需要把这些能力做成标准的、带描述的、带参数契约的单元让模型可以在运行时有选择地“看到”并调用。这一层做得不好最常见的表现就是模型不知道该用哪个工具或者把一个工具当成另一个用。第二层是执行可靠。模型输出一段调用意图这只是个“意图”离真正的执行成功还有十万八千里。参数类型对不对、必填项有没有漏、外部服务返回了错误怎么处理、超时怎么办这些都需要在技能层做兜底。我经常跟团队说一句话不要让模型直接去操作裸的API那样等于让新手司机直接上高速出事儿是必然的。技能层就是那个驾校教练帮模型把路况理顺、把动作规范好。第三层是治理和扩展。当你的Agent从三五个技能增长到几十个甚至上百个技能时你怎么管理技能的命名规范是什么谁负责审核新技能技能之间的依赖关系怎么处理技能的运行日志怎么统计这些都属于治理问题。没有体系化的思考技能库很快会变成一锅粥最后连你自己都不知道agent到底能用什么。这三层问题其实是递进的。能力暴露解决“能不能调”执行可靠解决“调没调对”治理扩展解决“能不能持续调”。我见过太多团队在第一层做得很兴奋到第二层就被现实毒打到第三层干脆放弃了。所以这篇文章里我会把这三层展开讲透每一层都给出可落地的做法。1.3 技能、工具、插件、函数调用概念的边界很多朋友经常问skills和Function Calling、Tool工具、Plugin插件这几个词到底有什么区别我觉得没必要在概念上死磕但作为架构者脑子里必须有个清晰的边界否则设计会乱。Function Calling是底层机制它指的是模型在推理时输出一个结构化的调用指令通常包含函数名和参数由外部系统去执行。这是“怎么调”的问题。Tool是比Function Calling更上层一点的产品化封装它通常包含了模型侧的调用声明和系统侧的真实执行逻辑。你现在看到的很多Agent框架里注册的tool本质上就是一层“技能”的雏形。Plugin更强调“可插拔”和“生态”比如各种IDE插件、浏览器插件它通常包含UI、配置、生命周期管理是一个偏产品形态的概念。Skills则可以理解为是这一切的“能力单元”它强调的是为了完成某个领域任务而组织的组合能力。一个skill可能内部包含多个工具调用、多步逻辑、错误处理、甚至调用其他skill。它是面向“任务”和“场景”的而不是面向“单个函数”的。我的设计习惯是这样的底层是工具函数负责单点能力中间层是技能负责场景化编排和可靠性兜底顶层的Agent负责理解和规划。这样分层之后模型面对的是“技能”而不是零散的“函数”决策负担小得多成功率也高得多。这个概念边界大家先记住后面实操部分我会按照这个分层来展开。2. 技能系统的架构拆解一套可落地的agent技能体系长什么样2.1 技能注册表让agent知道“有什么可用”技能注册表是整个技能体系的大脑。它的核心作用是维护一份“技能清单”告诉Agent当前环境里有哪些能力、每个能力是干什么的、怎么调用。你可以把它类比成餐厅的菜单——厨师Agent只有看到菜单才知道今天能做什么菜菜单写得好不好直接决定点菜准不准。注册表的设计我通常会包含几个核心元素技能名称skill_name、用途描述description、参数声明parameters、权限要求permissions、执行入口endpoint/handler。技能名称必须遵循统一的命名规范我推荐小写加下划线比如send_email、query_sales_data这样模型更容易生成准确的调用名。描述字段是重中之重后面我会专门讲。注册表还有一个关键问题是动态性。技能系统不能是写死的静态清单否则每加一个技能都要改Agent的核心代码。标准的做法是做“动态注册”——技能在启动时或热加载时向注册表登记自己Agent运行时从注册表拉取最新的可用技能列表。这样做的好处是扩展成本极低新技能上线不影响已经在跑的任务。在实际落地时我建议给注册表加一个版本号和健康状态字段。版本号方便追踪“模型看到的是哪一批技能”健康状态则标识技能当前是否可用。这个看起来很小的设计在排查线上问题时能省下大量时间。2.2 技能描述写给LLM看的说明书我在这个领域花过最多的时间研究和调试的就是技能描述description怎么写。很多人觉得描述嘛写一两句话就行实际完全不是这么回事。模型对技能的选择几乎完全依赖于描述文本的表达质量。一条好的技能描述需要回答清楚几个问题什么场景下用这个技能这个技能的主要功能是什么使用前有什么前提条件如果存在容易混淆的其他技能怎么区分这里我分享一个我自己打磨过的描述模板skills.query_sales_data 当用户需要查询销售数据、订单明细、客户购买记录或生成销售统计报表时使用。 支持按时间范围、区域、产品线、客户维度进行过滤。 注意本技能只负责数据库查询和聚合不负责发送报表邮件。 如需发送邮件请使用 skills.send_email。这个模板虽然不长但信息密度很高。它告诉模型触发场景、支持的能力边界、容易混淆的兄弟技能以及“不负责什么”。最后一条尤其重要因为模型经常会把相邻技能搞混明确写清楚排除项能大幅降低误调用。此外描述里还可以加入“调用建议”。比如有的技能依赖前置数据可以在描述里写明“调用本技能前请先通过query_user_profile获取用户ID”。这种跨技能的协作提示能让Agent的规划能力大幅提升。我在多个项目里测试过优化描述后技能选择的准确率普遍能提升20到30个百分点这在工程上是极其夸张的ROI。还有一点描述要定期审视。因为模型版本升级后对文本的理解偏好会变化业务逻辑变化后某些描述会过期。我见过不止一个团队技能调不准第一反应是调prompt、调模型查了半天最后发现是描述文案跟实际功能已经对不上了。把描述当代码来维护这是agent-skills工程里很重要的一条经验。2.3 参数Schema一份严格但好懂的契约模型选择完技能接下来要做的就是填参数。参数Schema就是中间那份“契约”写得太随意模型容易理解错写得太死板模型又容易因为不会填而放弃。这里的关键是平衡严格性和易用性。我推荐使用JSON Schema来定义参数结构。它足够标准化主流大模型和框架都原生支持。设计Schema时有几个关键原则参数名用语义化命名而不是缩写每个参数必须写清晰的描述和示例值能用枚举值的地方尽量用枚举必填和可选参数要仔细划分默认能推导的值不要逼着模型填。举个例子我见过一个团队的技能定义里有个参数叫period描述只写了“时间范围”结果模型传出了各式各样莫名其妙的格式。后来改成date_range描述写成“查询起始和结束日期格式为YYYY-MM-DD例如2024-01-01至2024-01-31”调用成功率立刻上来了。这个案例其实说明了一个很朴素的问题模型不是人它对你代码里的“常识”毫无感知你在Schema里漏掉的信息它就会自由发挥。除格式之外参数Schema还应该支持服务端校验。模型输出参数后先校验再执行不合法就返回明确的错误信息最好是中文描述让模型能理解并自我纠正。这比把脏参数直接发给业务系统要好得多。我在架构里通常会给技能加一个“校验器”中间层专门处理格式转换和合法性检查。这个层有时候还能做“参数补全”比如用户没提供日期范围时由系统自动填上“最近30天”。2.4 调度执行LLM从“选技能”到“调技能”的完整链路技能系统运转起来之后一次完整调用链路其实是这样的用户输入目标 → Agent规划拆分子任务 → 从注册表中匹配技能 → 根据描述和Schema生成调用参数 → 校验和权限检查 → 执行技能逻辑 → 返回结果 → Agent根据结果决定下一步是继续调用还是输出结论。这套链路里最关键的环节其实是“结果返回”。很多初学者只关注怎么让模型调用技能忽略了技能返回结果的质量。技能执行完返回的内容不应该是原始的JSON堆栈而应该做一层“结果包装”把关键数据、执行状态、错误信息如果失败整理好。这层整理后的结果会直接影响Agent的下一轮判断。还是那句话让模型处理什么格式的数据决定了它能不能处理好。在框架选型上你可以用现成的Agent框架比如LangChain、LlamaIndex、各类国产Agent框架都支持tool/skill注册机制也可以自己实现一套极简调度。我的建议是早期项目完全可以自研一个简单的注册调度循环代码量并不大但你能彻底理解每一环的细节。等规模大了再考虑迁移到成熟框架也不迟。自研的核心理念是Agent循环保持极简把复杂度收纳进技能内部。这样不管是排查问题还是加新特性你都有一个可预期的系统而不是一个黑盒。3. 从0到1搭建你的agent技能库完整实操记录3.1 第一步梳理场景盘点技能边界动手写代码之前先别急着定义技能。我建议先用一张纸或者一个表格把业务场景里所有Agent需要完成的动作全部列出来。比如“查库存”、“下订单”、“生成周报”、“发送提醒邮件”、“检索内部知识库”每个动作写清楚触发条件、输入信息、输出结果。这一步的目的是盘点“技能边界”。很多人上来就定义细碎的技能比如一个技能叫“计算两数之和”这种技能会让Agent的决策空间爆炸。反过来一个技能叫“处理所有跟客户相关的事”这种又太大内部的逻辑会变得不可维护。正确的粒度应该是“一个技能对应一个有明确完成条件、逻辑内聚的任务”。我通常用一句话测试法来判断粒度是否合适这句话能不能说清楚我在什么时候调用这个技能如果能那粒度基本OK。盘点完之后还要给技能排优先级。不要一口气实现所有技能先挑3到5个核心高频场景做试点跑通了再逐步扩展。这既是为了控制风险也是为了验证你的技能体系设计是否合理。我踩过最大的坑就是在第一个项目里一口气定义了20多个技能结果真正被模型调用到的只有五六个其余的全是维护负担。3.2 第二步技能模板与代码组织技能代码的组织方式直接决定了后续扩展的效率。我推荐一个技能一个目录或者一个文件内部统一包含四个部分元信息、入参校验、业务执行、结果包装。如果你用Python可以按这样的模式组织# skills/query_sales_data.py SKILL_META { name: query_sales_data, description: 当用户需要查询销售数据、订单明细、客户购买记录时使用..., parameters: { type: object, properties: { start_date: { type: string, description: 起始日期格式YYYY-MM-DD, example: 2024-01-01 }, end_date: {type: string, description: 结束日期格式YYYY-MM-DD} }, required: [start_date, end_date] } } def execute(params: dict, context: dict) - dict: # 1. 参数校验与默认值补全 # 2. 业务执行逻辑 # 3. 结果包装返回结构化数据或错误信息 ...这种模板化的好处在于新技能开发者只需要关心自己的业务逻辑不用管Agent循环怎么调度、模型怎么感知。而且元信息SKILL_META是纯声明式的很容易做动态注册。代码组织层面我习惯把所有技能放在一个skills/目录下每个技能文件自包含。另外我会建一个registry.py负责扫描技能目录、加载元信息、构建可调用映射。这样做的好处是上线一个新技能只需要往skills/目录里丢一个文件注册表自动感知Agent立刻就能用。这个机制我在团队里推行后新技能的交付时间从“改主代码重新部署”缩短到“提个PR就行”。3.3 第三步参数设计与校验参数设计这一步建议不要偷懒把每个参数都当成产品功能来打磨。我总结过一份参数校验的心法先定必填项、再做类型约束、再给默认值、最后做业务校验。必填项设计的原则是凡是模型可以通过用户对话或上下文推算出来的信息可以放宽为非必填交给技能内部去补全凡是必须从外部获得且无法推算的信息必须设为必填。举例来说查询销售数据时时间范围通常建议非必填默认取最近30天这样模型即使没拿到日期也能完成任务但“目标客户ID”这种无法无中生有的字段就必须是必填。类型约束要细。字符串要限制最大长度枚举值要列全数字要限定范围。这些约束不仅是为了数据合法性更重要是给模型明确的“可生成空间”——模型在一个明确的约束范围内做选择比面对一个开放文本框准确得多。我经常用枚举类型比如“报表类型”这个参数直接给出[daily, weekly, monthly]模型就绝对不会传出一个每礼拜数据这种让下游系统崩溃的值。业务校验是最后一道防线。比如查询日期不能早于数据上线日期、下单数量不能超过库存等。业务校验的结果如果失败不要直接返回一个冷冰冰的报错尽量返回“带纠正建议”的提示比如“库存不足当前最大可下单数量为30”。这种错误信息进入Agent的上下文后Agent可以直接调整自己的计划实现自我纠错。我在多个项目里验证过这种设计能把任务的最终成功率提升10%以上。3.4 第四步本地联调与日志观测技能写完之后本地联调是关键环节。不要“信心满满”直接上生产我建议至少做三层测试。第一层是单技能测试。直接调用技能的execute函数传入各种合法和不合法的参数确认逻辑正确、错误处理符合预期。第二层是模拟Agent调用测试。用一个真实的大模型接口构造几条典型的用户问题把注册表加载上看模型选择技能是否正确、参数生成是否合理、多步调用能不能串联起来。第三层是全链路回归。把常见的10到20条典型任务脚本化每次改代码都跑一遍防止“改了个技能A结果技能B的调用反而坏了”。日志观测方面我特别建议每一条Agent调用链路都记录结构化日志至少包含用户请求、模型选了哪个技能、生成的参数是什么、校验结果、技能执行结果、返回给模型的结果、最终回复。记录这些不是为了事后追责而是为了“复盘优化”。我每周都会抽几条失败链路看看是描述问题、参数问题还是技能逻辑问题然后针对性修改。可以负责任地说Agent类项目性能提升的秘密八成不在改模型而在日志复盘和描述迭代这两件事上。4. 常见问题与排查技巧实录4.1 技能明明注册了agent就是不用这是被问得最多的问题。技能注册表里明明有send_email用户说“帮我发封邮件”Agent愣是不调用或者偏偏去调了别的技能。这种问题九成出在“描述质量”上而不是代码Bug。排查思路是先看日志里Agent到底有没有“看到”这个技能。如果日志里没有该技能的相关提及说明技能描述在整个上下文中不够突出或者描述信息有问题让模型觉得它不匹配。你可以把问题复述一遍观察Agent的完整思路看它是怎么理解用户意图的。根据我的经验最常见的“无用描述”有三种太泛“用于发送邮件”、太技术“SMTP mail sender interface”、缺少触发条件没写清楚“当用户要求发送邮件、通知、提醒时调用”。把描述按我前文说的模板重新打磨一遍大部分问题都能解决。还有一种情况是技能数量太多模型在长文本里被其他技能的描述淹没了。这时需要精简注册表每次只暴露跟当前任务相关的候选技能而不是全量暴露。4.2 参数反复传错问题出在哪模型选对了技能却把参数传得乱七八糟日期格式不对、数字写成字符串、该填的字段空着。这类问题通常指向Schema设计不够友好。我遇到过一个典型场景技能需要两个日期参数但Schema里的描述只写了“开始日期”和“结束日期”没有任何格式说明模型就会自由发挥有时传2024/01/01有时传2024年1月1号。后来我把例子直接加进参数描述里并且把参数约束成format: date问题立刻消失。所以遇到参数错误第一件事不是骂模型弱而是回去看你的Schema是不是“假设模型什么都知道”。另外建议在参数层面引入“宽容解析”。比如日期无论模型传什么格式代码层都尝试归一化金额字符串自动去掉逗号和货币符号。这种“容忍度”设计能有效兜底模型的不稳定输出。但注意宽容解析只能解决格式问题不能掩盖业务值的错误两者要分开对待。4.3 技能多了以后选择冲突怎么办当技能库扩充到几十个以上新问题出现了几个技能描述上相似模型总是选错。比如既有一个query_inventory查库存又有一个query_product_info查商品详情用户问“这个SKU还有货吗”模型可能就去调商品详情而不是库存查询。解法是“分层显式区分”。首先把高度相关的技能归到一个父技能内部由父技能根据参数进一步路由而不是让Agent在顶层做不同技能的抉择。其次在描述里明确写清“与其他技能的区别”。比如query_inventory里写明“只用于查询剩余数量不支持商品名称、规格等主数据信息如需获取商品主数据请调用query_product_info”。还有一招是“收敛意图”。有时候模型选错错不在技能定义而在上游的用户意图就被理解偏了。这时需要优化Agent的系统提示词给出一组典型问题和对应技能的例子few-shot。例子不用多5组就很有效果。我通常会在注册表里给高优先级技能配置一两个“示例触发语”能显著降低选错率。4.4 安全与性能几个容易忽略的坑最后提几个安全和性能上的坑都是我在实战中被“教育”过的。安全方面第一个是权限边界不清。技能一旦暴露给Agent相当于模型获得了该技能的调用权限。必须给技能配置准入控制尤其涉及写操作发邮件、改数据、下单的技能一定要做审批确认或权限分级。我见过有团队让Agent直接对接生产数据库的删除接口一轮prompt注入就直接出事故。第二个是外部输入过滤。Agent在调用技能时有些参数来自于外部文档或第三方系统这类“不可信数据”流入技能后可能造成问题必须在技能入口做内容过滤和长度限制。性能方面最大的坑是“技能调用过长”。如果一个技能内部串了十几个外部API一次调用可能要几十秒而大模型本身的超时机制已经断了最终用户收到的是超时和错误。解法是把长链路技能拆成多步每步快速返回让Agent循环来推进“边推进边汇报”。另一个常见坑是技能内部叠加了对大模型的递归调用比如技能里又调了一次LLM这种设计会让延迟和成本成倍上升除非必要不建议这么做。最后一条建议渐进式发布。新技能上线时先设置一定的灰度比例观测调用成功率、耗时、报错率数据稳定了再全量放开。这套流程听起来不复杂但能把生产事故的概率降低一个量级。写到这里我把agent-skills从概念、架构、实操到排障的核心经验都过了一遍。坦白说Agent类项目的复杂度不在模型选择上也不在框架选型上而在这套看不见的“技能工程”里。技能描述怎么写、参数契约怎么定、日志怎么沉淀、冲突怎么化解每一项都是在真实业务里被反复打磨出来的细节。如果你正准备搭自己的技能体系我的建议很简单先小步验证三个核心技能把描述和日志做好剩下的交给迭代。技能库是会“长”的只要根系扎得正后面枝繁叶茂只是时间问题。