这两年只要聊到Agent落地几乎绕不开一个问题模型能力确实在涨但Agent干活的稳定性和复杂度上限卡在技能的组织方式上。工具注册页几十个函数堆在那里Prompt里塞满各种能力说明结果模型还是经常选错、漏用、甚至把两个工具的调用顺序搞反。我折腾过几轮方案之后把思路收敛到了一个名字上agent-skills。简单说就是不再把能力当成零散工具扔给模型而是把每个能稳定执行的任务闭环定义成一个标准化的“技能”再交给Agent按需调度。这篇文章不是概念科普而是把我自己做技能库设计、注册、调度、排错的全过程拆开讲一遍。如果你正在做Agent功能开发或者刚被多工具编排的稳定性折磨到头疼这篇内容可以直接拿来当参考骨架。从技能的定义标准到匹配打分公式再到一次真实任务的执行日志我会尽量把每一步为什么这么做讲清楚。1. 先想清楚Agent的“技能”到底是什么1.1 技能、工具、插件的边界很多项目里工具、插件、技能这三个词是混着用的。前端按钮叫工具后端接口叫工具第三方服务接入叫插件然后模型函数调用也叫工具。混到最后讨论调度逻辑的时候根本说不清在调度什么。我自己的做法是先做严格区分。工具是最小可复用操作单元。它可以是一次API调用、一段固定算法、一个数据库查询。特征是输入输出明确不需要模型做复杂推理就能执行。插件本质上是适配外部系统能力的代理把外部系统暴露能力包装成工具。技能则是面向一个具体业务目标编排出来的能力闭环它内部可以调用多个工具也可以依赖其他技能并且包含校验、回退、状态处理。举个例子发送HTTP请求是工具接入某个数据平台是插件而“生成一份某项目的周报”就是技能。周报技能内部可能拉取项目进展数据调用模板渲染检查数据完整性最后产出Markdown。如果只把“拉取数据”“渲染模板”作为两个工具暴露给模型模型很大概率会在拉数据之前就开始写结论或者漏掉某个项目模块。把整个过程封装成技能以后模型只需要决定一件事当前请求该不该调用“生成周报”技能。我见过一个项目最初用了22个底层工具模型的工具命中率只有六成左右。后来把22个工具重新编排成了7个技能命中率提高到九成以上而且调用路径也稳定了。核心原因不是模型变强了而是决策维度从二十二选一变成了七选一判断难度大幅下降。1.2 为什么需要一个独立的技能层有人会问能力都封成技能是不是就把模型的灵活性限制住了这个担心有一定道理但实际中遇到的更多问题是反向的灵活性太高导致行为不可控。没有技能层时系统一般长这样一个超大System Prompt里面把所有能做的事、所有工具说明、所有规则全部铺给模型。模型每次请求都重新理解一遍导致几类问题反复出现。第一Prompt过长关键信息被稀释模型对低频工具的感知会退化。第二工具间没有约束关系模型可能调用一个应该先预处理数据的工具。第三完全没有评估单元你只知道模型返回了文本不知道它有没有真的完成“收集数据、分析趋势、生成结论”这一整套动作。第四无法复用换一个业务场景Prompt里的工具段落就得重新写。技能层的核心作用是把不稳定的大模型决策拆成两层。上层是意图路由模型只需要判断“用户想要什么”。下层是技能执行对应一系列定义好的确定性逻辑。这样既保留了大模型的语义理解能力又把关键动作固定成可控流程。你可以把它理解成给一个比较有想法的新人配了一批标准作业程序新人负责判断接哪个活具体每个活怎么做按程序来。同时技能层还带来一个隐藏价值可测试性。普通工具函数可以写单测但Agent行为很难写单测。技能定义一旦完成就能对执行结果做结构化校验。输入Schema、输出Schema、依赖列表、回退策略全部是机器可读的这为后面的自动评估和质量追踪提供了基础。2. 搭建技能库从定义到落地的完整方案2.1 技能标准化定义技能标准化听起来像是一个偏文档的工作实际上它直接决定调度系统的检索和匹配效果。技能定义不是给人看的手册是给模型和路由模块共同消费的数据。我最终收敛出的最小信息结构包含四层身份层、语义层、协议层、执行层。身份层很简单技能ID、版本、所属领域、优先级。这是为了管理用的后续的统计、灰度、回滚都靠它。语义层是整个定义里最容易被忽视但最关键的部分。它包含技能名称、描述、触发条件、适用场景、反例。描述不能写得像功能说明书要写成“意图说明书”。比如描述一个日报生成技能差的写法是“生成日报”好的写法是“当用户需要汇总当日工作内容、产出结果和明日的计划时生成结构化日报支持按项目、按时间段过滤”。这里的关键是回答两个问题这个技能解决什么意图什么情况下不应该调用它。协议层用JSON Schema描述输入和输出。输入字段必须有类型、必填性、约束条件输出字段必须定义成功和失败形态。这不仅是给模型看的也是执行引擎用来做校验的。协议定义得越严格下游做缓存、审计、重试就越简单。执行层是技能真正干活的部分。它定义技能内部如何调用工具、依赖哪些其他技能、是否允许并行、失败时怎么做。执行层可以是代码、工作流描述文件也可以是给模型的一段指令。我给一个实际的YAML示例这是我在项目里用到的技能定义结构id: weekly_report name: 周报生成 version: 1.2.0 domain: report priority: high description: 当用户需要按周汇总项目进展、分析风险并生成汇报文档时使用。 适用于周维度的工作回顾不适用于日报或实时状态查询。 triggers: - 用户提到本周工作汇总 - 需要周报格式的报告 - 项目周例会材料准备 exclude: - 用户只要日报 - 用户只想查某个单条数据 input_schema: type: object properties: project_names: type: array items: type: string description: 需要汇总的项目列表默认全部活跃项目 week_offset: type: integer default: 0 description: 0表示本周-1表示上周 required: - project_names output_schema: type: object properties: report_content: type: string description: 生成的Markdown格式周报 risk_items: type: array items: type: string generated_at: type: string format: date-time required: - report_content execute: engine: workflow steps: - collect_data: tool: project_data_sync params: projects: $input.project_names - analyze_risk: tool: risk_detector params: data: $steps.collect_data.result - render_report: tool: markdown_renderer params: analysis: $steps.analyze_risk.result fallback: - collect_data 失败时尝试使用 cache_reader 技能 - analyze_risk 失败时跳过风险分析并标记 warning这个结构用下来还算干净。每个字段都指向一个明确用途没有冗余。2.2 技能注册与发现机制定义好技能之后要解决的就是注册和发现。我在一开始犯过一个错误把技能放在一个大目录里每次调度都去全量扫描。技能少的时候问题不大但是技能数量上了50个之后全量匹配的性能和准确性都开始出问题。后来我把注册和发现拆成了两条链路。第一条是元数据注册中心负责保存技能定义、版本、状态、健康记录。技能上线之前要在这里做Schema校验、依赖校验、试运行。第二条是检索链路负责在调度时快速找到候选技能。检索链路会为每个技能建立语义索引、关键词索引和标签索引。语义索引用模型为技能描述生成向量匹配时把用户请求也向量化用余弦相似度做初筛。关键词索引覆盖技能名称、触发词、领域标签用来做精确召回。标签索引是人工维护的粗粒度分类比如“报告生成”“数据查询”“任务调度”用来做领域过滤和权限控制。注册中心提供统一的上报入口技能开发完成后调用注册接口即可完成上线。我在项目里用的是这样一个简化接口内部会完成健康检查和索引刷新POST /skills/registry/register Content-Type: application/json { skill_file: skill_definition.yaml, source: team_a, environment: prod }注册成功后系统会给技能分配一个全局唯一ID同时触发索引构建。索引构建完成之前技能不会参与调度这样避免上线半截技能被模型选到。围绕发现机制我还有一个经验不要只依赖语义相似度做最终决策。语义相似度适合召回和排序但不适合做硬性过滤。原因是向量空间里的相近不代表业务意图相同描述里有“日报”和“周报”两个词向量可能非常接近但业务上绝对不能混淆。所以最终调度要结合规则约束。3. 技能调度的核心逻辑如何让Agent选对技能3.1 技能匹配与路由技能库建好之后调度器就是大脑。调度器的任务是把用户请求映射到正确的技能并在多个技能都匹配时做取舍。我的调度流程分四步。第一步请求解析把用户原始输入抽成结构化意图提取关键实体。第二步候选召回从索引里拉出得分最高的前N个技能。第三步打分排序综合语义相似度、上下文匹配度、历史成功率、成本代价计算综合分。第四步阈值决策超过阈值的技能进入执行队列没有超过则走兜底策略。打分公式我调过好几版当前用的是这个score 0.45 * semantic_sim 0.20 * context_match 0.25 * historical_success 0.10 * cost_factorsemantic_sim是用户请求与技能描述的语义相似度范围0到1。context_match表示当前对话上下文与技能触发条件的匹配程度触发条件里有用户刚提到的关键词就给高分。historical_success是过去30天该技能的成功率用来抑制那些总执行失败但表面相似的技能。cost_factor则综合计算调用该技能的预计Token消耗和延迟成本高的技能会被轻微降权。阈值我设的是0.65。低于0.65但高于0.4的请求进入“模糊候选区”系统会让模型二次确认意图或者把请求拆解后重新匹配。这个设计比直接拒绝体验好很多因为很多请求本身就是复合意图拆解后反而能命中多个技能。有一点要注意技能打分不能只看当前请求还要考虑会话历史。用户可能在前面几轮里已经提到了项目范围后面只说“那生成周报吧”这时候单纯看当前这句话语义匹配分不会很高。我处理的办法是维护一个会话上下文向量每轮对话结束后把抽取到的实体和意图合并进上下文再参与匹配打分。3.2 技能组合与编排很多任务不是单技能能搞定的。比如“把最近一周的线上事故梳理成报告并发给负责人”这里面至少包含“查询事故记录”“生成报告”“发送消息”三个技能。调度器需要支持技能组合。我把组合模式分成四类顺序执行、条件执行、并行执行、循环执行。顺序执行最简单前一个技能的输出作为后一个技能的输入。条件执行是看前一个技能的执行结果决定分支走向。并行执行要求技能之间没有数据依赖且累计成本可控。循环执行通常用于批处理场景比如遍历多个项目逐个生成周报。在实现层面技能定义里的execute字段会声明依赖关系和数据类型。调度器执行前会先做依赖拓扑排序确保每个技能的输入都已经被上游技能准备好。如果出现循环依赖注册中心直接拒绝上线。组合执行时最头疼的是失败处理。我见过太多工作流一条链路中间断了整个任务就失败了。实际上很多中间步骤是可以降级处理的。比如刚才说的“事故报告并发送”如果“发送消息”技能失败报告本身已经生成了完全可以降级成返回报告内容提示用户手动发送。这就是我在技能定义里增加fallback字段的原因。编排层面的另一个问题是Token消耗控制。技能一组合上下文容易变得很长。我不想为了让模型理解流程就把所有中间结果全部塞进模型上下文。我的做法是执行引擎自己做数据流转只有最终呈现给用户的输出才进入模型上下文中间数据放在执行状态的内部存储里。这一步能把单次复杂任务的Token消耗降下来不少。4. 实战用 agent-skills 跑通一个完整任务4.1 环境准备与初始化前面讲的都是框架这节把实际操作过一次的完整流程拉出来。假设我要跑一个“站点健康巡检”的任务核心是让Agent每天自动检查几个数据源的健康状态并生成一份巡检报告。环境准备需要几样东西一个调度服务运行环境我用的是Python项目需要装一些基础依赖。一个向量索引服务用来做技能描述检索。还有一个KV存储用来保存会话上下文和技能执行状态。我给一个安装依赖的参考命令pip install skills-sdk requests pydantic openai初始化目录如下技能定义、执行脚本、日志分开放后面排查问题会轻松很多。agent-skills-project/ skills/ health_check.yaml report_builder.yaml alert_dispatcher.yaml executors/ health_check_runner.py report_builder_runner.py alert_runner.py registry/ local_registry.json logs/ execution.log初始化的最后一步是启动索引同步让注册中心感知到技能目录下的所有YAML文件。启动后会看到一行日志输出显示同步了3个技能定义并生成对应向量索引。4.2 技能编写与注册先写“站点健康巡检”这个技能。这个技能做的事情是接收站点列表逐个发起探测请求记录返回码和响应时间然后把结果整理成表格。技能定义如下id: site_health_check name: 站点健康巡检 version: 1.0.0 domain: ops priority: high description: 当用户需要检查多个站点的可用性、响应速度和错误状态时使用。 适用于主动巡检和定期任务不适用于分析历史监控数据。 triggers: - 巡检 - 健康检查 - 站点探测 exclude: - 用户要分析监控趋势 input_schema: type: object properties: urls: type: array items: type: string format: uri description: 待检查的站点地址 timeout: type: integer default: 5 description: 单站探测超时秒数 required: - urls output_schema: type: object properties: results: type: array items: type: object properties: url: type: string status: type: integer response_ms: type: integer healthy: type: boolean summary: type: string required: - results - summary execute: engine: code ref: executors/health_check_runner.py fallback: - 单站点超时后跳过并标记异常 - 全部站点异常时调用 alert_dispatcher 技能对应的执行脚本核心逻辑很简洁import asyncio import aiohttp async def run(input_data): urls input_data[urls] timeout input_data.get(timeout, 5) results [] async with aiohttp.ClientSession() as session: for url in urls: try: async with session.get(url, timeouttimeout) as resp: results.append({ url: url, status: resp.status, response_ms: round(resp.elapsed.total_seconds() * 1000, 2), healthy: resp.status 400, }) except Exception as exc: results.append({ url: url, status: 0, response_ms: None, healthy: False, }) healthy_count sum(1 for r in results if r[healthy]) summary f共检查 {len(results)} 个站点健康 {healthy_count} 个异常 {len(results) - healthy_count} 个 return {results: results, summary: summary}写完定义和脚本之后调用注册接口把技能推上去curl -X POST http://localhost:8000/skills/registry/register \ -H Content-Type: application/json \ -d {skill_file: skills/health_check.yaml, source: ops_team, environment: prod}注册成功后会收到一条包含技能ID和索引状态的响应我看到的是229号技能上线索引构建耗时大概1.2秒。这时候技能库就准备好接受调度了。4.3 任务执行过程实录接下来模拟一个真实请求。用户发来一句话“帮我把首页、订单服务和支付网关都探测一下看看现在正常不。”调度器会先做意图解析把这句话里的实体提取出来站点列表是首页、订单服务、支付网关意图是站点健康巡检。然后去技能索引里召回候选排在最前面的就是“站点健康巡检”技能得分0.87超过阈值。执行引擎接收技能定义里的输入Schema自动构造如下输入{ urls: [ https://home.internal.example, https://order.internal.example, https://pay.internal.example ], timeout: 5 }随后引擎调用执行脚本得到结果{ results: [ { url: https://home.internal.example, status: 200, response_ms: 120.4, healthy: true }, { url: https://order.internal.example, status: 503, response_ms: 800.1, healthy: false }, { url: https://pay.internal.example, status: 200, response_ms: 215.9, healthy: true } ], summary: 共检查 3 个站点健康 2 个异常 1 个 }按照fallback定义异常数大于0会额外触发“告警分发”技能把订单异常的信息推送到告警渠道。调度日志里能看到两个技能先后执行全部成功。这个流程看起来很顺畅但我是踩了不少坑才跑通的。第一次跑的时候技能描述里的触发词写得太具体只写了“健康检查”“巡检”用户换成“看看网站通不通”就匹配不到得分只有0.3直接走了兜底流程。后来我把描述改成了意图导向加上了“可用性”“响应速度”“正常不”这些口语化表达匹配分才上来。这个调整给我一个很深的印象技能描述是给语义模型看的要覆盖用户说话的正常变化而不是只写内部术语。5. 常见问题与排查技巧实录5.1 技能命中率低匹配不到正确技能这是最常见的现象。表现是用户请求明明很明确但调度器给出的最终得分很低技能没有被触发或者触发了错误的技能。我一般按三个顺序排查。第一个检查点是技能描述。描述里如果用的全是抽象术语模型其实很难和用户口语建立关联。比如“获取业务对象的关联数据”这种描述在词面上就和“我想看看这个订单关联的客户信息”重叠度不高。解决办法是重写描述加入用户视角的常见说法。第二个检查点是召回索引。索引没刷新会直接导致新技能和最近调整过描述的技能无法被召回。排查方法是先直接查索引里有没有该技能的向量再看调度日志里召回阶段返回的候选列表。第三个检查点是阈值。阈值设得太高会把正常匹配杀掉。我会用一段时间的调度数据来校正阈值统计触发请求得分分布找一个误杀率和错误触发率平衡的点。当前我的经验值是0.6到0.7之间比较稳。还有一个很隐蔽的问题上下文匹配分权重过高导致带上下文偏置的错误命中。比如用户前面聊了几轮“支付对账”突然问“有哪些工具可以用”调度器可能因为上下文里反复出现支付而把“支付工具列表”技能排到前面。这个场景需要给上下文匹配加时间衰减只参考最近几轮避免长期话题影响当下路由。5.2 技能冲突与依赖管理技能多了以后描述相近的情况会明显增加。“生成周报”和“生成项目周报”在语义上高度重合调度器无法精确区分时两个都会被召回但靠前的可能不是用户真正想要的。我的处理思路分三步。第一步尽量合并同类技能。如果两个技能面向的核心意图一致只是参数不同就合成一个通过输入Schema和触发条件细化来区分分支。第二步确实需要保留两个技能的要在描述里写出明确的排除条件让语义模型能区分“日报场景”和“周报场景”。第三步在调度规则里维护一份人工的冲突消解表当两个技能得分都超过阈值且差距小于0.05时优先选择优先级高的那个。依赖管理的问题主要集中在循环依赖和幽灵依赖上。循环依赖是好查的因为拓扑排序会直接报错。幽灵依赖更隐蔽技能B实际依赖技能A的输出但定义文件里没有声明结果调度器单独执行技能B时数据为空。后来我强制要求在技能定义里写明上游依赖再在注册时扫描执行脚本里的数据引用用自动化检查替代人工记忆。5.3 性能与资源控制技能库大了以后性能问题就来了。调度环节最明显的瓶颈是语义检索每个请求都要把请求文本向量化再和几百个技能向量做相似度计算。优化方向有两个一是给向量索引建ANN索引把检索从全量计算变成近似最近邻但前提是技能数量确实大到全量已经撑不住了二是在语义检索之前先用关键词索引做初筛把候选集合缩到几十个以内再做精确匹配。执行环节的性能问题通常是上游工具响应慢导致整个技能链路被拖住。我在前面介绍过给每个工具调用设置超时合理的超时值是上游P95响应时间加一点缓冲而不是随便设一个固定值。如果上游接口P95已经到3秒超时设2秒就会频繁触发降级。资源控制还有一个容易被忽略的地方技能内部如果维护了大量中间态的临时数据比如大文件或者长文本缓存链路结束后必须显式清理。我给执行引擎加了执行上下文池每次任务结束后统一回收中间数据否则跑一整天任务之后内存会缓慢攀升直到触发告警。我把这轮调试中遇到较多的问题整理成一张速查表供参考现象常见原因排查动作技能始终无法命中描述与用户意图语义跨度大重写描述覆盖口语表达新技能不参与调度索引未同步触发索引重建检查注册状态命中两个相似技能描述边界不清补充exclude条件设置优先级技能链路中间失败依赖声明缺失检查依赖列表补全上游依赖执行结果一直重试上游响应超时调大超时或增加缓存降级内存缓慢上涨中间态数据未清理增加执行上下文回收机制6. 一套沉淀下来的技能设计原则技能库从混乱到稳定这个过程持续了不短的时间最后沉淀出几条我在新项目里会直接照做的原则。第一条单一职责。一个技能只完成一项业务目标不要试图把“查数据写报告发消息”塞进一个技能里。组合是调度器的事不是技能定义的事。集中在单个技能里的逻辑越复杂可测试性和可复用性就越差。第二条描述面向用户意图而不是面向实现。技能描述里应该回答“用户什么时候需要我”而不是“我能做什么”。每次写完描述我都会拿几类真实的用户请求去试召回效果看那些换了个说法的请求能不能被召回。第三条显式声明依赖。技能之间的数据依赖、顺序依赖、冲突关系都要写进定义不要让调度器猜。任何隐藏的依赖都会在未来的某次调整中变成事故。第四条给每个技能设计降级路径。所有技能都必须定义fallback动作哪怕只是返回错误信息和提示语。没有降级路径的技能在网络抖动、服务异动的时候会成为整个Agent的瓶颈。现在再看agent-skills这个项目我觉得它的本质不是技术框架的搭建而是把“模型能力”和“业务稳定性”之间的边界划清楚了。模型做语义理解技能做行为约束两者配合才能让Agent既灵活又可靠。如果你也在重构自己的Agent体系可以从定义第一批技能开始不要急着堆工具先把你最常用的几个任务闭环写清楚再逐步扩展。这个方向走通了以后后面接更多场景就不会慌。