先说个我最近深有体会的事现在的对话式AI模型单聊知识问答已经没什么门槛了真正拉开差距的是它能不能替你把一件事完整办完。你让它查资料它能答你让它订会议室、汇总邮件、跑一遍数据处理脚本多数模型就卡住了——不是模型笨而是缺了一整套可复用、可管理、可观测的执行技能。我最近在做的一个内部项目代号就叫agent-skills本质上是在给Agent装配“手脚”把高频动作沉淀成结构化技能让模型按需调用而不是每次都在对话里临时拼Prompt。这篇就把我在设计、实现和上线这个技能库过程中的完整思路写出来包括技能怎么定义、路由怎么选、线上怎么保证不跑飞踩过哪些坑希望能给同样在搞Agent工程化的朋友一点参考。这套东西最适合两类人一类是已经在用各类Agent框架做业务落地、但对技能组织方式不满意的人另一类是准备从零搭一个“能干活”的助手、又不想重复造轮子的人。我会尽量把原理讲清楚也会给出可以直接抄的配置和代码片段。1. 技能库立项前的三个核心判断1.1 “工具调用”和“技能”其实是两回事我最早也把工具调用直接等价于技能。后来在一个某智能客服项目里被狠狠教育了一次我们给Agent塞了二十几个API工具函数定义写得漂漂亮亮模型也确实会按需调用但整体效果非常不稳定——同一个请求有时走A工具有时走B工具有的工具参数里的枚举值模型总是填错。后来想明白了工具是原子操作技能是有上下文、有前置条件、有后置校验的完整行为单元。比如“查天气”是一个工具但“根据用户城市信息综合考虑今日气温与降水概率给出出行建议”就是一项技能。技能应该封装三样东西触发条件、执行流程、结果校验。仅仅暴露一堆裸工具给模型相当于你请了个实习生却只给他一堆零件不给操作手册他当然会乱来。agent-skills的出发点就是把“零件”升级成“带说明书的模块化工作站”。1.2 技能碎片化是效率的隐形杀手在决定建这个库之前我统计了团队里两个月的Agent调用日志发现一个扎心的事实同样一个“从用户输入的会议纪要素材里提取行动项并写入待办清单”的能力被三个不同业务线分别用Prompt实现了三遍细节各有差异一个支持按日期过滤一个支持按负责人过滤一个两个都不支持。这还只是我们能识别的更多逻辑藏在各种即兴System Prompt里完全没有复用性。所以技能库另一个重要使命是收敛重复把高频、跨业务复用的能力统一收编形成单一事实来源。改一处全线生效不然每改一个Prompt都要去翻几十个Agent配置迟早发疯。1.3 技能必须有“手感”不能只是文档堆市面上很多Agent项目也强调Skills、Tools、Plugins但多数只是把函数列表写进Markdown。我觉得这不够。一个设计良好的技能库应该让Agent有“手感”——描述得足够清晰让模型一眼知道什么时候该用参数足够收敛让模型不用猜返回结果有结构让模型拿到后能直接做下一步决策。我们内部给技能库定义了一个及格线一个完全不了解业务的工程师只看技能的描述文档能准确说出这个技能接收什么、产出什么、出错后会怎样。如果达不到这个标准说明技能设计还停留在“能跑”阶段远没到“好用”。2. agent-skills的技能模型注册、元信息与版本管理2.1 从JSON Schema到技能装配清单技能库的第一版我参考了市面上常见的插件描述格式把每个技能定义为一个JSON文件核心字段包括name、description、input_schema、output_schema、flow、timeout、fallback。其中flow是执行流程的声明可以是单个工具调用也可以是工具序列fallback是失败时的降级策略。后来发现纯JSON在表达分支逻辑时很憋屈尤其是“如果上一步返回的是空列表就切换到另一种查询方式”这种条件判断写在JSON里可读性极差。于是我们升级成了“技能装配清单”的概念技能仍然用统一的元信息表达但内部执行步骤由一段轻量DSL基于YAML描述支持顺序执行、条件跳转和并行调用。这段DSL不需要太复杂够用就行。举一个实际例子技能“查询订单物流状态并生成摘要”version: 1.0 name: order_logistics_summary description: 查询订单物流轨迹并生成面向用户的简洁摘要适合用户在询问“货到哪了”“什么时候到”等场景。 input_schema: order_id: type: string required: true description: 订单编号例如 ORD20240901 flow: - step: fetch_trace tool: query_logistics_api input: { order_id: $input.order_id } - step: check_empty check: $steps.fetch_trace.result.trace_points.length 0 on_true: - step: fallback_hint tool: generate_text input: { template: 该订单暂无物流更新记录请稍后再查询。 } on_false: - step: build_summary tool: llm_summarize input: { content: $steps.fetch_trace.result, style: friendly } timeout: 8s fallback: - tool: generate_text input: { template: 物流查询服务暂时不可用请稍后再试。 }这个文件解决了三个问题一是模型看得懂有描述、有Schema二是执行器看得懂有步骤、有跳转三是人能审查每个字段都有明确含义。我强烈建议任何技能库的元信息都要带版本号下文会细说为什么。2.2 技能注册中心与运行时索引所有技能文件并不是散落在文件夹里就完事我们做了一层轻量注册中心技能启动时扫描目录、解析Meta、校验Schema唯一性然后构建运行时索引。索引的核心是embedding向量因为模型选技能不能靠纯字符串匹配否则“查快递”和“物流查询”这种同义表达就匹配不上了。注册中心会为每个技能生成两套检索键一套是关键词倒排用于精确匹配工具名、常见别名一套是语义向量用于模糊匹配查询时把用户意图embedding之后做混合检索取TopK再交给后续路由判断。这个设计非常关键只靠大模型从几百个技能里硬选延迟和幻觉都受不了先召回一小批候选再让模型做精排成本和效果都会好很多。2.3 版本冲突与灰度上线的血泪教训版本管理这一节我放到了立项初期就强调是因为第一次上线时就翻车了。当时技能库里有个email_sender某次更新把默认签名模板从“运营部小王”改成了“客户成功团队”结果直接影响了另一个依赖旧签名的报表订阅任务上线后当天就收到投诉。问题根源在于技能文件更新了但依赖它的Agent配置没有锁版本。我们的解法是给每个技能定义兼容性契约包括输入Schema的兼容策略新增可选字段为小版本删除字段或改必填为大版本、输出结构的兼容承诺以及显式的depends_on声明。技能库在加载时会做依赖解析发现不兼容的调用方就拒绝装载并报错而不是默默让运行时代错误。这个机制看着琐碎但对维护超过五十个技能、支撑多个Agent实例的场景来说能省掉无数个深夜排查时间。3. 技能库里的四类核心技能模块3.1 外部情报感知型搜索、抓取与RAG增强第一类也是最常用的是让Agent具备“感知外部世界”的能力。笼统地说就是搜索和网页内容解析。我们在技能库里沉淀了web_search和web_fetch两个基础技能但真正复杂的其实是上层的research_compile技能给定一个主题自动拆解子问题、多次搜索、交叉验证信息一致性最后输出带引用的汇总报告。做这类技能时我的体会是必须在DSL层就考虑去重和置信度评分不然模型很容易在网上找到两条互相矛盾的信息然后全靠自己脑补。research_compile里加了一步cross_validate要求同一事实至少有两个独立来源才标记为“可信”只有单一来源的结论会降级为“待核实”。这一步极大改善了问答类Agent在垂直问题上的胡编率。另外RAG增强型技能需要特别关注召回质量指标。我们给rag_query技能增加了可配置的min_score阈值与rerank开关低于阈值时宁可回复“资料库中没有找到相关内容”也不硬答。这一步很多人忽略但我觉得“不知道”远比“胡说”更有价值。3.2 系统交互型API调用、权限收敛与审计第二类是Agent与内部业务系统打交道的技能。单纯封装一个HTTP接口调用是简单的难点在安全模型上。我们把系统型技能的配置里固定挂了三个字段allowed_roles、required_permission、audit_level。Agent只有在用户身份满足权限要求时才能触发所有执行动作都会写入审计日志。这里有个很重要的经验敏感操作不要求模型做权限判断要在技能执行器层面强制拦截。模型判断“用户是否有权删除这条数据”不可靠但执行器里检查Token对应的角色是铁律。技能描述里可以完全不提权限细节让模型聚焦业务权限在入口统一过滤。否则模型很容易被用户的prompt绕过去——不是它坏而是它真的容易忽视那些隐含在长文本里的人名和角色关系。我曾经做过一个数据查询Agent技能query_finance_report在前端校验时漏了数据范围过滤结果有销售同学问出了全公司的薪资汇总。幸好当时还在测试环境但这个教训直接催生了技能库的“强制行级权限”设计——所有查询类技能默认拼接tenant_id条件不允许从参数里传入。3.3 短期任务型轻量逻辑编排与格式转换第三类技能和具体业务强相关但通用逻辑也很清晰比如“把CSV转成结构化JSON并做简单清洗”“按模板生成周报”“批量重命名并归档文件”。这些工作说不上多复杂但很繁琐非常适合沉淀成技能。我会把它们统称为“短期任务型”因为它们通常一次执行就能完成不依赖持续的状态。设计这类技能的技巧是尽量让参数扁平化不要嵌套复杂的对象。模型在填参数时对“一个对象里套着数组数组里又是对象”这种结构非常容易犯错而扁平化参数配合清晰的字段描述出错率会显著降低。例如“批量重命名”技能可以这样定义name: batch_rename_files description: 按规则批量重命名指定目录下的文件适合用户要求“把截图改成按日期命名”等场景。 input_schema: directory: type: string required: true naming_pattern: type: string required: true description: 命名模板支持 {date} {index} {original} 占位符 start_index: type: integer required: false default: 1参数越少越平模型的调用成功率越高这是我做了一百多个技能后最直观的结论。3.4 周期执行型定时触发与事件驱动第四类是把技能从“一问一答”升级到“主动干活”的关键——周期执行和事件驱动的技能。我这边实现了一个轻量调度器技能配置文件里可以声明trigger支持cron表达式或消息队列事件。比如每天早上九点自动执行的daily_brief技能拉取待办、聚合昨日数据、生成简报、推送到指定群。架构上调度型技能和交互型技能共享同一套技能描述与执行引擎差别只在触发源头。好处是模型的调用入口统一技能复用率变高调度器只负责触发不关心模型决策。而且所有周期任务的执行结果都会回流到同一个观测面板运行是否正常一目了然。踩过的坑是时区和失败重试定时任务并发执行时如果某个上游接口响应变慢容易堆积任务。我们在调度器里强制加了max_overlap参数——同一技能同一时间只允许一个实例运行新触发的实例会直接跳过并记一条skipped日志避免雪崩。4. 集成落地让Agent真正把技能用起来4.1 系统提示词里的技能声明与“心智占用”技能库建好接入选型循环后最先遇到的问题就是技能太多了塞不进System Prompt。几十个技能完整描述可能就超过模型上下文窗口更别说还有对话历史和工具结果。后来形成一个折中方案System Prompt里只声明最高频的10-15个核心技能其余技能通过“技能路由索引”方式按需检索。但这里我发现一个非常微妙的问题即便只声明15个技能对模型来说也是不小的“心智占用”。有些模型一看到大量技能清单就开始“炫技”明明一个简单寒暄它也要强行调个web_search来显得自己勤劳。我后来在提示词里写了句很有效的话“仅在用户需求明确且单靠已有知识无法回答时调用技能”配合技能路由的相似度阈值虚调率降了不少。4.2 技能选择路由向量召回还是让模型硬选这是我在架构评审时被问得最多的一个问题。我的答案很直接先用轻量路由缩小候选再让模型做最终选型不要摊大饼。具体实现上我们维护了一个skill_router服务基于技能描述和调用的历史数据构建了技能选择的微调排序模型。当用户请求进来时skill_router先在二十毫秒内从技能库里召回5-8个候选技能然后把候选技能列表和相关描述拼进Prompt让大模型决定用哪个、填什么参数。这套架构的优势在延迟和准确率上都很明显。我们还加了一个人工反馈通道当模型选了技能A但用户后续追问了明显属于技能B的内容时会把这次选择标记为负样本定期重训排序模型。技能路由的准确率会随着反馈变好而不是永远依赖Prompt里的“碰运气”。4.3 与外部Agent框架对接的兼容层不少读者可能已经在用现成的Agent开发框架再搞一套技能库怎么对接是个现实问题。我的建议是写一个薄兼容层对外仍暴露框架的标准工具接口对内转发到技能库执行引擎。这样既能享受技能库的注册、版本、监控能力又不用把现有Agent推倒重来。兼容层的适配器主要做三件事把外部框架传入的参数映射成技能库统一的上下文对象把技能执行结果转换成框架期望的message格式把技能内部的trace_id透传给外部链路追踪保证全链路可观测。整个适配器也就几百行代码但价值在于技能库的演进不会绑架上层框架的选择上层框架的更换也不会浪费沉淀下来的技能资产。5. 线上运行的可靠性保障与实测效果5.1 打断、重试与结果校验三板斧线上运行和Demo最大的区别在于外部系统不可控。会超时会返回脏数据会偶尔直接5xx。agent-skills的运行期因此内置了若干可靠性机制默认不信任任何外部依赖。首先是执行超时控制每个技能都声明timeout执行引擎统一遵守超时就终止并返回友好错误。其次是重试策略对网络抖动类错误自动重试一次指数退避对参数错误不重试直接提示用户修正输入。最后是结果校验每个技能跑完后会拿结果做一次output_schema校验不通过的结果不能直接交给模型防止脏结构污染后续决策。5.2 可观测性设计技能执行全链路追踪技能执行的可观测性是二期才补上的但极其重要。我们给每次技能调用生成了全局唯一的trace_id从用户请求进入、技能路由命中、技能执行到最终响应生成全链路打点。技能执行器内部会记录每一步工具调用的耗时、入参、出参摘要、错误信息。日志平台里专门有一个“技能执行总览”面板可以看到每个技能的被调用次数、平均耗时、成功率、Token消耗以及同一技能的耗时分布趋势。有一次线上告警说某Agent响应变慢我打开面板发现是web_fetch技能在高负载时段成功率骤降根源是其中一个新闻站反爬加重了验证策略。没有这个面板这类问题靠肉眼排查会非常痛苦。5.3 一组来自实际项目的运行数据在支撑某内部运营助手迭代的两个月里技能库沉淀了约四十个技能高峰期日调用超过两万次。技能路由的命中准确率稳定在87%左右加上大模型最终选型后整体技能选择准确率约95%。最常用的三个技能分别是query_order_status、generate_daily_report、search_internal_docs占了总调用量的四成。这些数据提供了一个务实参考技能库不是越多越好二八效应非常明显大量长尾技能其实很少被调用。后来我调整策略对新技能的审批增加了一条硬性要求必须预测至少每周100次调用否则以临时脚本方式运行不进技能库。这个“准入机制”有效防止了技能库膨胀成垃圾场。6. 踩过的坑和值得复用的经验6.1 技能描述写得太详细调用率反而下降第一版技能描述里我恨不得把每个字段的来龙去脉都写进去结果模型反而不爱调用了。分析原因是描述里的干扰信息太多模型抓不住触发时机。后来改成“第一句话讲清楚什么时候用第二句话讲清楚输入输出第三句话讲清楚注意事项”整体调用率提升了20%以上。写技能描述时我给自己定了一个规矩只写模型不确定的信息。比如某个字段的枚举值约束、某个接口对日期格式的硬性要求这些必须写而“这是一个很有用的查询功能”这类废话别写。6.2 参数校验到底放在哪一层早期我把参数校验写在技能内部逻辑里结果模型填错参数后技能库返回的是一堆程序员的报错文案用户体验很差。后来我把校验前置到技能执行引擎的统一入口并且针对常见错误做了人性化提示。比如order_id格式不对时错误信息会直接说“订单编号应为字母ORD开头加8位数字您填写的xxx不符合规则”。顺带一提模型在Time字段上极其容易犯错尤其是“下周一上午十点”这种相对时间表达。我们的方案是所有技能接口统一接收ISO8601绝对时间由Agent框架层在调用前把相对时间换算成绝对时间技能内部不处理模糊时间。这个小改动直接消灭了大约三分之一的时间相关报错。6.3 灰度发布与技能回滚机制技能发布不该是“全量更新”的一锤子买卖。我们的发布流程是新技能或技能新版本先在沙箱环境跑一轮离线用例集通过后进入金丝雀模式只对5%的流量生效观察半小时错误率和调用成功情况再逐步放量到50%、100%。一旦线上发现问题技能库可以一键回滚到上一个稳定版本受影响用户通常不超过五分钟。这套机制看起来重但对于要长期维护的技能库来说几乎是必需品。你可以想象一下一个给全公司客服用的Agent技能逻辑更新出错影响的可不是一个用户而是一整条业务线。宁可在发布时多花点流程也别在事故后收拾烂摊子。7. 复盘之后我重新理解的“技能库”做agent-skills这个项目之前我一度以为Agent能力建设的核心是模型选型、上下文窗口长度、Prompt技巧这些显性因素。做完这一轮之后我的想法变了当模型的底层能力趋同真正决定Agent好用不好用的往往是这些隐性工程——技能是否成体系、参数是否收敛、路由是否准确、故障是否可控。现在的Agent开发其实有点像早年建网站的经历。当年大家追求花哨的特效和动态页面后来才发现扎实的信息架构、稳定的部署和合适的缓存策略才是根本。技能库也是一样它不直接发光发热但它是Agent能稳定、持续、安全地替人干活的地基。最后再说一个让我特别有感触的细节技能库建好之后新来的同事不再需要凭借厚厚的手册去猜Agent能做什么了他直接查一下注册中心里的技能列表就能拼出复杂的自动化流程。这种“能力可见、能力可组合、能力可治理”的状态才是Agent从玩具走向生产工具的标志。如果你也在搭自己的技能体系我建议你从最小的两三个技能开始跑通注册、路由、执行、观测这条链路再慢慢往里添砖加瓦——别急着铺大摊子让第一批技能真正被用起来、养出数据远比堆一堆好看但不常用的技能有价值。
：需求、选材与实测全解析)
