那段时间我正好在做一个内部数据分析Agent功能倒是不复杂但技能函数越堆越多从最初的十几个一路涨到八十多个。真正让我警醒的是一次线上失误模型在众多工具里挑了一个相近但错误的函数去执行把周报数据算成了残缺口径排查了小半天才定位到是“技能太多、决策模糊”导致的。那一刻我意识到手里的东西已经不叫“工具列表”了它已经膨胀成一个需要专门治理的体系。而这个体系就是包括我在内很多做Agent的人这两年反复讨论的“agent-skills”——智能体技能库。agent-skills的核心并不是“写一堆函数然后注册给模型”而是把每一个可复用能力抽象成带有明确边界、准确描述、可编排逻辑的技能单元并设计一套让模型更容易选对、更容易调用的调度机制。本文适合两种人看一种是从小项目过渡到中型Agent系统明显感觉到“函数一多模型就乱选”的工程师另一种是刚接触Agent开发、想知道技能库和普通工具调用到底差在哪的学习者。我会把我在真实项目里的拆解思路、踩过的坑、以及借鉴开源社区经验后的取舍尽量完整地说一遍。1. 为什么技能层会成为Agent系统的瓶颈从工具列表到技能库的演化1.1 函数调用为什么一开始很顺后来总是“开错门”最早的Agent原型通常只有几个函数。比如查天气、发邮件、算个日期差模型在上下文中扫一眼函数名和参数基本不会出错。这个阶段的函数调用体验极其顺畅因为候选集极小函数的意图和边界一目了然。但当函数数量突破三四十个问题就来了。模型不是真的理解每个函数的逻辑它只是在“读描述猜意图”。描述写得含糊参数含义不完整边界条件没有交代模型就会在相似技能之间犹豫。最典型的一幕是你明明提供了“查询销售明细”和“导出销售报表”两个能力模型却在需要明细时调用了导出报表最后生成一个文件而不是一个可分析的数据表。这个问题的本质是随着函数增多模型的选择成本指数级上升而大多数项目的函数组织方式还停留在“平铺一堆函数描述”的阶段没有做信息分层和决策降维。平铺意味着所有函数争夺模型的注意力在多步任务里早期步骤的错误选择还会传导到后续所有步骤形成连锁错乱。1.2 agent-skills解决的核心矛盾可复用、可编排、可解释我理解“agent-skills”并不是一个严格的开源项目或某个固定技术规范而是一类解决方案和思考方式的统称把能力组织成可复用、可编排、可解释的“技能集合”。它实际上应对三个核心矛盾。第一个矛盾是复用。传统工具函数往往是单项目内联编写这次用完下次重写或者赶紧复制粘贴到新项目里改一改。技能库则要求每个技能独立成体带清晰的调用契约、输入输出说明和参考示例跨项目复用变成复制配置而不是重写代码。第二个矛盾是编排。单个技能只能解决单点问题但真实任务几乎都是多步骤的。agent-skills要求技能本身就具备“可供其他技能调用”的意识也就是每个技能知道自己能输出什么、输出结构是什么其他技能能据此衔接。这一层设计决定了多Agent协作或单Agent技能链能否跑通。第三个矛盾是可解释性。当系统出错你需要知道模型为什么选这个技能、技能的判断依据是什么。技能库里的每条描述都是模型的“决策依据”把描述和schema写得清楚就相当于把模型的决策过程透明化。我见过不少项目最后靠“技能描述评审”来降低故障率效果比增加prompt说教好得多。1.3 技能库和“一堆工具函数”的真正区别从超市货架到专属厨师用一个生活化的类比来说工具函数列表就像超市货架所有商品都摆在一起你想买什么都得自己一个个找而技能库更像是你有了一位专属厨师他知道你的口味、会按菜品搭配食材、也知道哪些食材不能同时用。这不是仓储模式的差异而是“组织方式”的差异。在代码层面普通工具函数只是一个def和docstring而技能单元至少包含四部分技能的“用途说明”一句话说清它解决什么问题输入输出契约参数的名称、类型、单位、取值范围以及返回的数据结构边界和限制条件什么情况下不适合调用、前置条件是什么、有没有副作用一到两个示例最好包含真实参数和真实返回帮模型建立具体感知。这个差异不是形式化的而是直接决定模型调用准确率的关键。我在一个二十多个技能的中型测试集里做过对比只写一句话docstring的技能组模型在复杂任务里的调用准确率大概只有五成上下补齐了上面四要素的技能组同样任务能到七成五左右。倒不是说那一家模型不行而是信息量不足时选择本身就是个瞎猜的过程。2. 技能拆分粒度与抽象边界我自己总结的三条拆分准则2.1 准则一按“不可再分的最小可用动作”拆分而不是按场景拆分很多人在设计技能时习惯按业务场景切分比如“数据分析技能”“运营助手技能”“报表生成技能”。听起来很清楚但落到实际调用就会发现问题场景类技能往往内部夹杂了多个步骤模型必须在一次技能内部完成分支判断可这种判断逻辑塞在代码里外部根本不可见既难测试也难复用。我的第一准则是按“最小可用动作”拆分。所谓最小可用就是这个动作独立调用后能产生一个有意义的完整结果不需要调用方再补充关键信息。举个例子“查询指标数据”是合适的技能因为它有自己的输入参数和明确返回但“生成数据分析报告”就不太合适因为它大概率需要组合查询、计算、排版多个动作如果硬做成一个技能返回值结构会很复杂而且复用性极差。实际操作中我倾向用一个问题检验某个技能是否拆分到位如果另一个开发者想在完全不同的项目里复用这个技能他需要不需要看内部代码只要需要看内部代码就说明技能抽象还不够干净内部可能藏着不该有的逻辑耦合。2.2 准则二技能描述与服务承诺分离——描述说清“可依赖的边界”第二个准则是我在多次误调用之后反省出来的技能描述里必须写清楚“它承诺什么”和“它不承诺什么”。很多工具函数描述只写功能不写边界模型就会把这个技能当成万能钥匙。“可依赖的边界”是一个很实在的东西。比如一个“发送告警通知”的技能它内部可能依赖短信通道、邮件通道、站内信通道。如果某个通道不稳定技能要不要重试要不要接入备用通道如果描述里没有说明可靠性承诺模型调用后收到一个失败返回就可能自作主张认为操作失败然后反向生成错误结论。我在技能元数据里增加了几个字段效果很好expect调用成功后返回数据的形态latency大致耗时时长让调度器对耗时敏感任务有预期side_effect是否有非幂等副作用比如发邮件、改数据库、扣减额度fallback失败后系统是否自动切换其他技能。这些字段不参与模型对话而是进入调度层做前置约束。简单说模型负责“要不要用”调度器负责“能不能用、用了之后怎么处理结果”各司其职准确率高很多。2.3 准则三按领域聚合而不是按函数来源聚合第三个准则跟团队协作方式有关。早期我们按“谁写的函数”来归类技能某某写的一组函数放一起。这种聚合方式维护成本高到让人崩溃——每次人员变动技能目录就得大改。后来我改成按领域聚合比如“指标查询”“数据写入”“用户触达”“权限校验”每个领域是一个独立命名空间领域边界内由固定的负责人维护。这样做的好处有三个领域内技能的命名可以保持一致的风格方便模型识别关联某个领域的下线或升级不会影响其他领域做领域内扩展时新增技能能复用已有技能的公共依赖。举个具体例子我重构过一个旧项目。原来有80多个散兵游勇式的函数五花八门的命名和docstring风格。按最小可用动作拆分并按领域聚合之后变成了61个技能分布在7个领域里。数量并没有大幅减少但因为每个技能都有了清晰的领域归属和接口契约模型的调用准确率体感上提升了特别多——至少不会出现模型在“数据查询”和“数据导出”之间反复横跳的情况。重构前后对比组织形态技能数量命名风格边界描述跨项目复用度平铺函数80混乱多数没有很低领域技能库61统一四要素齐全较高3. 技能描述词的写作模型选对技能的真正胜负手3.1 我给技能写说明书的固定模板有段时间我执迷于调整底层的prompt架构觉得模型选错技能是prompt不够强。但后来做了个对照实验发现同样的prompt只优化技能描述就能带来接近二十个百分点的准确率变化。从那时起我意识到技能描述不是给人看的文档它是模型的决策输入重要性完全不亚于任何system prompt。我现在给每个技能写说明时固定使用同一套模板既方便自己写也方便模型形成稳定的阅读预期。模板大概长这样技能名称: 技能用途: (一句话说清楚这个技能解决什么类型的问题) 适用场景: (什么任务、什么业务背景、输入数据大概长什么样) 输入参数: (每个参数的名称、类型、单位、取值范围、是否必填) 输出结构: (返回数据的结构、字段含义、可能的状态码) 边界条件: (哪些情况下不应该调用这个技能/前置条件/副作用) 示例: (一个完整的输入输出示例)结构化的目的是减少歧义。模型在决策时本质上做的是文字匹配它需要从技能描述里找到跟用户问题高度相关的关键词。如果描述太口语化匹配就会不精准如果描述太学术化那匹配又过于死板。这个模板是我在大量实验后平衡出来的信息密度。3.2 描述词里该写什么、不该写什么该写的大家从模板基本能看明白我重点说说不该写的。第一不要写内部实现细节。模型不关心你的函数是用Pandas还是用SQL查的数据也不关心你的代码是异步还是同步。写这些只有两种结果要么增加无关上下文浪费模型注意力要么诱导模型对性能产生错误预期。第二不要写情绪化或主观性的词。比如“这个接口很强大”“支持各种丰富功能”这种话看上去是在强调能力实际上会让模型把技能想象得比实际更通用然后选了一个不该选的场景调用它。技能描述应该像设备参数铭牌客观、精确、无修饰。第三不要大量堆同义词。模型做语义匹配你写“查询、检索、获取、捞取”确实能扩大匹配面但也会提高误选率。技能名和描述里保持同一套核心动作词汇匹配会更稳定。我给一个真实案例。一个“获取用户最近登录记录”的技能早期描述写的是“可以查看用户最近登录时间、登录地点、登录设备类型支持时间区间过滤也可以用来判断用户活跃度”。模型确实能在该选的时候选到它但也在一些“判断用户活跃度”的任务里优先选它而实际上那类任务应该先跑聚合统计技能。后来我把描述改成“获取单条或批量用户最近N天的登录记录输出明细数据列表”加上一个示例误选率明显下降。差异就在于“判断用户活跃度”这种带分析性质的场景描述被我从技能描述里彻底拿掉了。3.3 实测对比模糊描述 vs 结构化描述调用准确率差距有多大我另一个项目里做了一个专门的描述实验数据集是一个内部构造的模拟任务集包含三个方面给模型分配“查询订单”“修改订单状态”“取消订单”“导出订单报表”四个高相似技能。第一版只用一句话docstring比如“查询订单信息根据订单号获取订单详情”第二版用完整四要素模板并且在边界条件里明确写了“仅用于查询不修改任何状态”。结果是第二版的调用准确率高了将近三十个百分点尤其是“修改订单状态”和“取消订单”这两个高相似技能之间的区分度提升非常明显。虽然没有做到百分百稳定但已经能支撑中等复杂度业务。这里有个细节容易被忽略模型往往会优先选择“名称上更像关键字”的技能而不会细读描述里的边界。所以如果你有两个技能名称高度相似比如“get_order”和“get_orders”再好的描述也很难纠正模型的名称偏见。我能给的建议就是技能命名的第一步就要做差异化管理名称本身就自带决策信号。4. 实现一个可迭代的技能注册与调度机制从代码层面落地4.1 用装饰器构建技能注册器让技能像插件一样即插即用理念说了一堆落到代码层面第一步是把技能变成一种可自动发现的资源。我推荐用装饰器模式做一个轻量注册器这样每次新增技能不需要改任何调度代码技能自己带着元数据注册进来。# skill_registry.py from dataclasses import dataclass, field from typing import Callable, Any, Optional class SkillRegistry: def __init__(self): self._skills {} def register(self, skill: Skill) - None: self._skills[skill.name] skill def get(self, name: str) - Optional[Skill]: return self._skills.get(name) def all(self) - list: return list(self._skills.values()) def filter_by_domain(self, domain: str) - list: return [s for s in self._skills.values() if s.domain domain] dataclass class Skill: name: str domain: str description: str func: Callable parameters: dict returns: dict boundary: dict field(default_factorydict) examples: list field(default_factorylist) _registry SkillRegistry() def skill(**metadata): def decorator(func): metadata.setdefault(name, func.__name__) metadata.setdefault(func, func) _registry.register(Skill(**metadata)) return func return decorator使用起来很简单。每个技能文件里用函数定义一个可执行能力用skill注解补充四要素元数据然后程序启动时自动导入所有技能模块即可。4.2 调度层的两级路由先做领域路由再做Top-K候选排序有了注册器之后最大的问题是怎么从63个技能里选出一个给模型。如果把所有技能描述都塞进一次推理调用上下文会爆炸而且候选越多模型越容易选错。我的做法是搭建两级路由。第一级是领域路由用一个轻量分类任务判断用户意图属于哪个领域只把该领域的所有技能描述作为候选集。领域数量一般五到十个每个领域下十个技能左右上下文压力和选择难度都大幅下降。第二级是技能排序在领域候选集内部做一个“相关内容检索”或由模型做顶层选择。这一步可以纯用向量检索把技能描述embedding化用用户查询的向量做相似度检索取Top-K。也可以走“模型二选一”的路线把候选技能逐对比较找出最合适的一个适合候选集比较少的场景。# dispatcher.py from sklearn.metrics.pairwise import cosine_similarity import numpy as np class TwoLevelDispatcher: def __init__(self, registry, domain_classifier, embedder): self._registry registry self._domain_classifier domain_classifier self._embedder embedder def route(self, query: str): domain self._domain_classifier(query) candidates self._registry.filter_by_domain(domain) if not candidates: return None query_vec self._embedder.embed(query) scores [] for skill in candidates: skill_vec self._embedder.embed(skill.description) scores.append((skill, cosine_similarity(query_vec, skill_vec))) scores.sort(keylambda x: x[1], reverseTrue) return scores[:3]很多文章喜欢直接给“模型外加一个ReAct循环”但我在实战里强烈的建议是不要把技能选择交给纯模型自由发挥而是用一部分工程逻辑先缩小范围。模型擅长做比较和决定不擅长从超大集合里做信息检索。两级路由规避了模型的弱项让它集中精力做决策整体稳定性会高很多。4.3 上下文压缩与技能索引构建怎么在不损失信息的情况下省Token技能描述全部展开之后token占用也是个实际问题。一个中等技能的描述加示例大概要五百到八百token六十多个技能全给就是四万token级别这还没算用户问题和其他上下文。我用的方案是三层压缩调度层只使用“精简描述”每项技能只需要一百token以内的短说明用来做领域路由和候选筛选候选技能被选定后调度器把完整技能描述参数schema示例注入模型上下文真正执行时调度器把函数返回结果做摘要处理只把关键字段发回模型做下一步决策。这个方案的收益有两个常规步骤里模型上下文只有两三千token响应速度和成本都稳定技能描述被真正调用时一定会展开完整版不会影响执行阶段的准确性。实际操作中我会给每个技能维护两个版本的描述完整版用于执行短版用于索引。它们之间的映射关系直接写死在技能元数据里新增技能时一并维护不额外增加调度成本。5. 从开源生态里借鉴技能库设计时的取舍哪些值得学哪些我踩了坑5.1 技能即文档可执行入口这是业界相对统一的共识我调研过几个比较受欢迎的开源Agent项目发现大家在技能层上的设计几乎都收敛到同一个思路技能是一个带结构化文档的可执行入口。有的项目叫skill有的叫tool有的叫capability叫法不一样内核非常接近。核心共识我总结成三条每个技能必须有完整的能力描述每个技能必须定义清楚的输入输出契约技能之间不能互相隐藏状态所有跨技能的数据传递都走显式参数。这三个共识对我自己项目的改造是决定性的。后面我把很多“程序员惯性思维”的去掉了比如喜欢用全局变量传结果、喜欢让函数隐式依赖某个上下文对象。技能作为一个独立执行单元显式输入输出是必须的因为模型不知道你的全局状态它只能看见传入的参数。5.2 一些过度标准化的“技能格式”会拖垮小团队开源社区也有另一条路线把技能格式定义得特别重比如带版本管理、技能依赖图、跨Agent共享技能包、技能市场等概念。大厂项目可能有能力这样跑但小团队和小项目学这套东西基本属于自缚手脚。我自己试过给技能加“技能依赖声明”“多版本并存”这类功能结果就是维护成本上升实际价值很低。原因很简单小团队的技能库体量通常就几十个真正的知识来自业务逻辑而不是一套复杂的元数据体系。过度设计会让团队把精力花在“填格式”而不是“写清楚技能说明”上。我的取舍是保留技能的必要结构化信息名称、领域、描述、参数、边界、示例去掉和业务无关的形式化约束。凡是格式里有“为了未来可能要XX而预留的字段”我全都砍掉。真到了需要版本化的时候用git本身就够了。5.3 什么时候不需要agent-skills我的判断标准这也是我想给初学者的一句实话如果你的Agent只有三五个技能做的事情单线化不需要把工程做重。很多技能库里推崇的做法比如领域路由、技能评分、多级调度在技能少于十个时反而会成为负担纯模型自由调用又快又准。我的建议是当技能数量超过二十个或者出现两个明显语义相近的技能时才考虑引入一套技能管理体系。过早引入只会增加样板代码和调度延迟跟“用螺丝刀代替锤子”没有区别。换句话说agent-skills是一剂对症的药不是越早吃越好的保健品。6. 上线后那些真正的意外技能冲突、技能链烂尾与上下文污染6.1 同名技能与命名空间冲突问题比想象中来得更快上线后的第一个意外来自一个很基础的点——技能重名。两个不同领域的开发同学各自写了一个“获取用户信息”的技能注册时后加载的直接把先加载的覆盖了。更坑的是覆盖时没有任何报错因为注册器就是个字典字典天然只保留最后一个key。排查了很久才发现问题。后来我给注册器加了两层防御注册时检测同名但不同domain的技能并抛异常程序启动时对所有领域做一次技能名唯一性检查。同时强制所有技能名称带领域前缀比如user.get_info和order.get_info从源头消灭重名可能。这类问题在单体项目里几乎不存在一旦做技能库就必须要提前防。6.2 技能A调用技能B的技能链如何控制深度、防止烂尾多技能编排是agent-skills的高价值场景但也是最容易失控的地方。我遇过的经典烂尾是技能A调用了技能B技能B的输出结构跟技能A预期的不一致导致技能A内部逻辑直接崩了。这个问题的根因不在于技能写错了而在于技能链的契约传递。技能A只声明了自己跟用户之间的输入输出没有声明它要调用的下游技能的数据格式。后来我在技能设计里增加了一层“技能间调用约定”如果一个技能需要调用其他技能必须在描述里注明“本技能执行过程中将调用XX技能并依赖其返回的XX字段”。但这层约定写起来繁琐实际能用自动工具生成一部分手动维护另一部分。更稳妥的做法是尽量把技能链控制在一到两个层级内超过三层的编排就考虑提取成一个新技能把调用细节封装在内部。模型不需要感知链条它只需要知道入口和出口执行逻辑放在代码里反而更稳定、更好测。6.3 技能执行结果不回流导致的重复动作上下文污染的真实案例另一个高频问题是技能执行成功了但返回结果太大或格式太复杂模型在后续步骤里没有把结果当作已知条件又重新调用了一次技能。重复调用本身不致命但如果技能有副作用比如发送通知、修改数据重复执行就是事故级别的问题。我用的方案是给调度器加一个执行记忆模块。每个技能执行完调度器会记录“技能名输入摘要输出摘要”并把它注入后续轮次的上下文供模型参考。模型看到同样的技能和参数已经执行过通常会直接引用输出摘要而不是再次调用。输出摘要不要直接塞原结果我会用固定模板生成一段结构化摘要比如“查询已完成返回6条记录总额3200状态均为已支付”摘要保持在三四十个token以内。这个方案能解决大部分重复调用问题但有一个前提技能必须是幂等或可重入的。否则记忆模块记录的“已执行”本身就可能误导。所以技能设计时凡是能做成幂等的操作我都尽量做成幂等确实有副作用的操作在描述里显式标注并让调度器对这类技能做额外确认。6.4 技能库沉淀与维护把它当成一个长期资产来运营最后想聊一个跟代码关系不大但体验很深的事技能库不是一次性建设它是跟着业务演进的长期资产。我每个迭代周期都会做一次技能描述重新审读就像清理冰箱一样把过期、重复、描述不清楚的技能找出来处理掉。一个技能如果连续两周没被调用我会考虑把它下线或合并一个技能如果经常被误选我会优先调整它的描述而不是增加调度规则。据我观察很多团队第一次把技能库搭好之后非常兴奋但三个月后技能库就变成了另一个“屎山”。区别就在有没有人愿意持续维护那些看起来不起眼的描述词和边界条件。这个工作没有技术难度但价值极高因为它直接决定了模型每一次决策的质量。我现在宁可少写一个功能也要把已有技能的描述打磨到位这一步是agent-skills项目成败的隐形分水岭。