从标题“agent-skills”切入先明确这篇文章的落点它不是讲某个具体Agent框架怎么配参数而是讨论Agent技能体系Agent Skills这一层抽象——它解决什么问题、怎么设计、怎么落地以及我在实际项目中踩过的坑。这个热词最近在圈子里讨论度很高很多人把它当成“给Agent加几个工具函数”来理解但我个人的体会是如果只是把功能函数堆给Agent你得到的不是技能而是一堆难以调度的碎片。真正值得做的是把技能当作一套独立于Prompt和模型之外的工程资产来管理。1. 为什么我坚决不在Prompt里硬塞技能智能体技能库的出发点1.1 Prompt越长Agent越“笨”这不是错觉我先说一个最直观的体验。早期做一个自动化调研Agent时我把十几个功能点全部写进System Prompt让模型自己判断什么时候该调哪个。结果很典型场景一多模型开始“选择困难”明明是搜索任务它非要先去调用数据清洗函数更麻烦的是Prompt里塞的技能描述越长模型对技能本身的理解精度就越低——这不是玄学是Transformer注意力机制的自然后果上下文越长关键信息被稀释得越厉害。所以真正规范的Agent工程化项目普遍会做一个“外置技能层”把能力从Prompt里抽出来以标准结构定义成技能由调度器Router/Scheduler负责匹配和调用。这也是“agent-skills”这个词组被反复讨论的核心原因——它强调的是一套可注册、可发现、可组合的能力资产体系而不是Prompt里的一段话。1.2 技能体系要解决的四个真实问题以我自己的理解Agent技能库不是“把函数集合起来”那么简单。它至少要解决四个层面的问题能力的可发现性模型或者调度器怎么知道现在有哪些技能可用每个技能的触发条件是什么边界是什么接口的可理解性一个技能需要哪些输入参数参数之间的约束关系是什么输出格式如何约定编排的可组合性多个技能之间怎么串联怎么拆分成子技能怎么处理执行顺序、依赖关系和失败回退资产的可持续性技能如何演进如何做版本管理如何测试和评估如何跨项目复用大多数团队在建Agent时第一个想到的是“多封装几个好用的工具函数”。这没错但距离“技能体系”还差很远。工具函数是水管技能体系是管道设计图纸——没有图纸的水管能出水但没法稳定供水。提示如果你现在只在Prompt里写了“你可以使用以下工具”并且工具数量已经超过5个那就可以认真考虑引入技能库设计了。2. 技能库的核心抽象把“调用”变成“声明”把“逻辑”变成“资产”2.1 技能的最小完整结构长什么样先别谈复杂框架。我建议从“一个技能就是一个带声明的函数”开始。具体来说技能的注册表里每条记录至少包含下面这些字段# skill_schema.py from typing import Any, Callable, Optional from pydantic import BaseModel, Field class SkillParameter(BaseModel): name: str Field(description参数名) type: str Field(description参数类型如string/integer/object) required: bool Field(defaultTrue, description是否必填) description: str Field(description参数说明用于让LLM理解该传什么) enum: Optional[list] Field(defaultNone, description枚举取值范围可空) class SkillDefinition(BaseModel): name: str Field(description技能名称全局唯一如web_search) version: str Field(default1.0.0, description技能的语义化版本号) description: str Field(description技能描述用于路由匹配的重要文本) parameters: list[SkillParameter] Field(description参数声明列表) execute: Optional[Callable] Field(defaultNone, description实际执行函数的引用) timeout_seconds: int Field(default30, description超时时间) permission_level: str Field(defaultsafe_read, description权限级别) state: str Field(defaultstable, descriptionalpha/beta/stable)这套结构解决了两件事让LLM“看懂”技能其中description和parameters两项是给模型看的写得好不好直接决定路由准确性这一点后面我会细说。让系统“掌控”技能version、timeout_seconds、permission_level这些是给运行时看的负责约束执行行为。2.2 为什么每个技能必须带“版本号”和“权限级别”很多初学Agent的人会问技能不就是个内部函数吗有什么好版本管理的我分享一个真实教训。有一次我重构内部数据查询技能把旧的数据库字段名换成了新的命名规范但当时没有做版本区分直接覆盖了原技能定义。结果存量会话还在按旧参数名调用新会话开始按新参数名调用。新旧混跑结果就是部分Agent返回字段为空的“幽灵结果”排查了很久才发现是技能签名变了。从此之后我的技能注册表里强制加上version字段而执行器会记录每个会话使用了哪个版本的技能做到可追溯。权限级别同样重要。Agent是自主行动的它不会每次执行都跟你商量。如果一个“文件读取”技能没有权限约束那Agent在某种Prompt注入下就可能读取到敏感文件。所以我在技能定义里引入permission_level凡是涉及写操作、外发数据的技能统一走approval模式——需要人工确认后才真正执行。2.3 函数签名和技能声明的本质区别我的理解是这样的普通函数签名是给程序员看的要求精确、严谨技能声明是给LLM这个“不太严谨的执行者”看的要求清晰、直白、覆盖模糊语境。比如一个查天气的函数签名可能是def get_weather(city_id: str, date: str) - dict: ...而同一个功能作为技能声明时描述大概要写成这样{ name: get_weather, description: 查询指定城市在指定日期的天气情况。当用户提及多云、下雨、气温、出行建议等与天气相关的请求时应优先调用本技能。城市名称需转换为标准城市ID。, parameters: [ {name: city_id, type: string, description: 标准城市ID例如北京为101010100, required: True}, {name: date, type: string, description: 日期格式YYYY-MM-DD默认为今天, required: False} ] }注意看这里的description不再只是“查询天气”而是包含了触发条件、典型请求示例、参数转换规则。这些细节直接影响了LLM判断“该不该选这个技能”和“参数该怎么填”。3. 技能的核心属性确定性能力与认知能力的双轨设计3.1 两种能力的分工逻辑我在项目实践中逐渐认识到一个关键点Agent技能体系里能力可以分为两类它们的构造逻辑完全不同。第一类是确定性能力Deterministic Skills。这类技能的结果是稳定、可预期的查数据、发请求、算数学、做格式转换、文件操作。它们的共同点是“结果正确性可验证”。比如输入两个数求和结果就是固定的。这类技能的核心价值是可靠性它们的实现方式是明确命令式的代码逻辑。第二类是认知能力Cognitive Skills。这类技能的结果具有一定开放性和主观性写总结、做翻译、整理要点、提炼主题。它们通常不是通过普通函数来实现而是通过对LLM的封装调用来实现——本质上也是一种技能但内部执行了“模型推理”的过程。由此可以得到一个重要结论技能不应只封装普通工具函数也需要封装可复用的“模型调用模板”。很多团队把这部分混在业务代码里实际上把它抽象为技能之后复用成本才会真正降低。3.2 技能级上下文给每个技能一个“私有工作区”在技能设计里一个容易被忽略的属性是技能上下文Skill Context。不同的技能在执行时对上下文的需求不同。举例来说一个“周报生成”技能不需要知道用户之前的全部对话它只需要接收原始工作记录列表而一个“代码解释”技能则需要拿到目标代码片段、运行环境信息、相关报错日志。如果所有技能都共享一个巨大的完整上下文结果就是无关信息被塞进模型输入不仅浪费token还干扰判断。更合理的做法是在技能定义中加入context_schema字段用于描述该技能实际需要哪些上下文片段调度器按需过滤后再传给技能执行函数。class SkillContextSpec(BaseModel): include_user_intent: bool Field(defaultTrue, description是否包含用户当前意图) include_recent_history: int Field(default0, description需要包含最近几轮对话历史) include_agent_state: bool Field(defaultFalse, description是否包含Agent当前状态) additional_datasets: list[str] Field(default[], description额外注入的数据集ID列表)这个设计我越想越觉得重要技能封装的不只是“如何做”还有“需要知道什么”。没有上下文规约的技能库在复杂任务面前一定会出现信息过载或信息缺失。4. 技能的路由逻辑为什么不能只靠“让模型自己挑”4.1 从“模型自由发挥”到“分层决策”早期阶段为了让Agent决定调用哪个技能我直接把技能列表全部塞给模型模型输出一个JSON指明要调用哪个函数。这在技能数量少、相似度低的时候没问题。可当技能列表到了几十个、还出现功能重叠的技能时问题就来了——选错技能的概率显著上升。我后来改成分层路由核心思路是把技能决策从一步拆成两步先用规则粗筛再用模型精排。第一层是规则索引层。根据用户意图里的关键词、实体类型、当前页面上下文从技能库里候选出5个以内技能。这一步不追求精确但追求召回率避免模型从几十个技能里做单选题。第二层是语义匹配层。把候选技能的description和用户的原始请求一起交给LLM让模型做最后的“匹配判断”。这个阶段输入很短模型不容易被干扰。这个双阶段路由的思路本质上是“规则兜底 语义兜底”的组合。规则层的准确率低一点没关系关键是缩小了模型的选项空间从而大幅降低了误选概率。4.2 相似技能的消歧靠“反例说明”技能库里出现相似功能是常态。比如“搜索新闻”和“搜索天气新闻”这两个技能表面上看都跟新闻检索有关但前者是通用新闻检索后者是限定天气领域。LLM在做选择时如果两个技能的描述都足够“像”就容易选错。我的解决办法是在技能描述里增加反例说明negative examples。例如“搜索新闻”的描述中加一句“如果用户明确要求搜索关于天气、气象预报的新闻请改用weather_news_search技能不要调用本技能。”这样模型的决策依据就更清晰了。我建议凡是定义一个新的技能写描述时同时写两条正例“什么情况下调用它”和反例“什么情况下不要调用它”。4.3 路由失败时要做什么技能的“降级链”技能调用失败后Agent不能直接停摆。在我的技能框架里每个技能都支持声明失败降级链fallback chain如果技能A失败按顺序尝试技能B、技能C或触发一个专用的“兜底回复”技能。class SkillFallback(BaseModel): on_error: str raise # raise/ignore/fallback fallback_skills: list[str] Field(default[], description按优先级排列的备用技能) fallback_message_template: str Field(default, description给用户的提示模板)这个设计看起来简单实际价值很高。有一次线上Agent在面对“查询本周销售数据”时数据源技能暂时不可用按降级链自动切换到了“读缓存报表”技能用户完全没有感知到异常。如果没有降级链这个会话大概率就报错结束了。5. 可组合性从单技能到技能链与子技能嵌套5.1 技能链的定义与运行所谓技能链就是按预定义顺序执行多个技能前一个技能的输出作为后一个技能的输入。这有点类似流水线但每个节点都是一个独立技能可以单独被替换或测试。我举一个慢病随访项目的例子。一次随访分析包含三个步骤先拉取电子病历数据再抓取近期检验指标最后由模型生成健康建议。如果不做成技能链这三步就得在Agent主流程里手工写死逻辑侵入性很强换个场景又要重写一遍。拆成技能链之后是这样配置的# follow_up_skill_chain.yaml chain_name: follow_up_analysis steps: - skill: fetch_medical_record output_key: medical_record - skill: fetch_lab_results input: { patient_id: $user.patient_id } output_key: lab_results - skill: generate_health_advice input: medical_record: $steps.fetch_medical_record.output lab_results: $steps.fetch_lab_results.output output_key: advice default_timeout: 120这个YAML文件本身也可以注册为一个“复合技能”也就是说技能链对上层调度员而言就是一个技能可以被更高层级的链继续嵌套。这就是可组合性的核心——任何一个技能节点既可以是原子技能也可以是一个子链。5.2 子技能嵌套与命名空间子技能的嵌套会带来命名空间的问题。我规定所有技能名采用domain:skill_name的格式。比如medical:fetch_record、finance:parse_report。这样两个不同领域里即使有相似的技能名也不会互相覆盖。嵌套时还要注意数据隔离父技能链里已经产生了若干中间结果子技能不能无限制地读取所有中间结果只能通过显式的input绑定获取数据。这样做的原因是为了可调试性——如果子技能能随意读取链条里任何数据一旦出错很难定位问题是哪个节点造成的。基于这套设计我的Agent才能从“一次对话调用两三个工具”进化到“一次任务自动编排七八个技能”而整体代码结构依然清晰。6. 技能的描述规范与评估体系一套需要长期迭代的“内部标准”6.1 描述写作的几个实操细则技能描述质量直接决定了路由准确率。我总结出一套描述写作细则第一句明确说明“这个技能做什么”用动词开头控制在15字以内。第二句说明“什么场景下需要调用它”列举常见触发短语。第三句说明“什么情况下不要调用它”给出反例。参数部分每个参数必须给出格式示例最好给出取值范围。输出描述简要说明返回结构方便后续技能或LLM正确消费输出。基于这个规则一个合格的技能描述示例技能sales_daily_report 描述查询指定日期的销售日报数据。 当用户提到“今天的销售怎么样”“昨日营收”“销售日报”等时应调用本技能。 如果用户需要的是趋势对比、周报汇总请改用sales_trend_analysis技能不要调用本技能。 参数 date (string, 必填)日期格式YYYY-MM-DD如2025-01-20 region (string, 可选)区域编码华北HB华东HD默认全部区域 输出包含总销售额、订单数、客单价、环比数据的JSON对象6.2 技能评估从“能用”到“好用”的正反馈闭环评估技能的好坏单靠直觉是不够的。我建立了一套评估清单每次新技能上线或技能描述调整都跑一遍调用准确率构建一组测试请求统计该请求是否被正确路由到目标技能。参数填充完整率统计LLM调用技能时是否按参数规范填了所有必填项。执行成功率技能实际执行过程中异常退出或超时的比例。输出可消费率返回值能否被下游节点或LLM成功解析。回归风险增加新技能后是否导致旧技能的路由准确率下降。其中“回归风险”最容易被忽略。技能描述调整会影响整个路由空间分布新增一个描述相近的技能旧技能的命中率就可能下降。所以每次技能库更新后我都会跑一次全量回归评估。6.3 技能迭代的版本节奏技能定义进入稳定期后变更应该走版本化流程。我把技能的生命周期分为几个阶段alpha内部验证、beta小范围试用、stable进入稳定目录、deprecated废弃过渡期。每一个版本变更都记录在技能的changelog字段里。这一点在多人协作的团队中尤为重要。没有版本控制的技能库三个人同时维护时很容易出现“你以为你改的是测试版、其实生产环境也在用”的混乱。7. 实战场景复盘从零搭建Agent技能库的完整过程7.1 场景背景与技能清单设计我用一个真实的项目来做完整复盘一个面向用户的“智能旅行规划Agent”。这个Agent要完成的任务包括根据用户偏好推荐目的地、查询航班和天气、规划每日行程、生成旅行物品清单、预算估算。如果把这些都塞进PromptAgent很快就会卡壳。我按流程梳理出了技能清单技能名称类型说明travel:query_destination确定性查询目的地候选列表travel:query_flight确定性查询航班信息travel:query_weather确定性查询天气信息travel:build_itinerary认知性生成行程计划封装LLMtravel:estimate_budget确定性估算预算travel:generate_packing_list认知性生成清单封装LLM这里特意把“行程计划”做成认知技能是因为它的输出不是唯一解需要模型结合偏好做创造而“查询天气”则必须是确定性技能不能允许模型自由发挥。7.2 候选技能预筛的实现基于意图实体抽取在路由层我实现了一个轻量的预筛模块不依赖重型模型。它先做一个实体抽取从用户输入中提取“目的地”“出行日期”“人数”等结构化信息然后用一套规则引擎根据实体类型去匹配技能。例如输入中出现“天气”或“温度”实体 → 候选技能包含travel:query_weather输入中出现“机票”“航班”实体 → 候选技能包含travel:query_flight输入中出现“行程”“攻略”“安排”实体 → 候选技能包含travel:build_itinerary这个规则层完全可解释、可调试。如果出现更新高的实体类型只需加规则不需要重训模型。7.3 LLM精排小模型就能胜任预筛后候选技能通常不超过4个。我把候选技能的description和用户原始意图拼接成一短消息交给一个参数量较小的模型让它输出最终选中的技能名和参数JSON。这里有个经验精排阶段不需要用最贵的大模型。因为决策空间已经很小小模型在限定范围内的表现已经很可靠。这样既保证了性能又控制了成本。7.4 技能执行与上下文回填技能执行后结果不能直接原样丢给主对话模型。我在框架里加了一步结果压缩回填如果技能返回结果很长比如航班搜索结果几百条先由格式化模块截取Top5并按固定结构精简再作为上下文交给主模型。这样做的原因还是那个词上下文污染。技能返回的原始数据如果全量塞给主模型主模型会被细节带偏同时还会超出上下文窗口。压缩回填让主模型始终面对的是“摘要后的事实”而不是“原始的数据洪水”。7.5 复盘结论技能库让迭代成本断崖式下降这个智能旅行Agent在交付后大约迭代了三个版本。每个版本的改动分别是新增了一个“预订酒店”技能、修改了“生成清单”的提示模板、调整了航班查询的排序逻辑。如果没有技能库这三个改动分别要动主流程代码、Prompt、工具调用层牵一发动全身。改了之后还要重新回归所有场景。但技能库模式下每个改动都只影响一个技能节点回归测试也只需要跑该技能关联的场景。8. 技能仓库的组织方式从个人脚本到团队协作落地8.1 技能仓库的目录结构技能积累多了以后组织方式不能靠随便放。我建议用这样一个目录结构管理技能仓库skills/ common/ # 跨领域通用技能 web_search/ skill.yaml # 技能声明文件 execute.py # 执行逻辑 test_cases.json # 测试用例 travel/ # 按领域聚合 query_flight/ skill.yaml execute.py test_cases.json finance/ parse_report/ ...每个技能目录自带“声明文件 实现文件 测试用例”这是技能资产化的最低配置。没有测试用例的技能不应该进入共享库。8.2 技能注册中心与依赖管理团队协作时技能不能只靠本地文件夹。我建议用一个简单的注册中心可以是Git仓库 索引文件的方式记录每个技能的元信息、状态、维护人。同时技能之间的依赖关系也要显式管理。比如“行程规划”技能内部依赖“目的地查询”技能。当被依赖的技能更新时依赖方需要跑回归测试。# skill.yaml name: travel:build_itinerary depends_on: - travel:query_destination - travel:query_flight - travel:query_weather8.3 共享仓库的准入标准我规定一个技能要进入共享仓库至少要满足三个条件有完整的声明文件包括描述、参数、输出说明、反例。有测试用例集覆盖正常场景、边界场景、失败场景。有维护责任人技能变更时有人负责评估影响面。这三条看着简单执行起来会挡住不少“看起来能用但不规范”的技能。而这正是共享仓库能否长期健康运行的关键。9. 技能库的演进方向从“技能”到“技能图谱”9.1 静态注册表不够了当技能数量超过百余个纯扁平的注册表管理就会变得困难。这时我开始考虑技能之间的“关系图谱”。技能之间其实天然存在三种关系上游依赖技能B的执行需要技能A的输出。功能互斥技能A和技能B解决的是同一个需求的不同方案不能同时触发。概念近邻技能A和技能B在语义上相关但功能不同。把这些关系做成图谱调度器在做路由时就可以结合关联关系做更合理的编排。比如用户问“旅行预算”调度器不仅能找到query_budget技能还能根据图谱关联到query_flight技能因为预算计算需要航班价格数据。9.2 技能的动态加载与热更新我现在正在尝试的方向是让Agent技能库实现动态加载——技能不需要全部注册进上下文而是按需发现、按需载入。这可以大幅缩减模型每次请求的输入体积。具体做法是先在系统层设置一个“迷你技能索引”只包含技能名一句话描述当路由层判断需要某个技能时才把该技能的完整声明载入。这个思路有点类似操作系统的分页机制索引常驻内容按需换入。它能解决大规模技能库下的性能瓶颈也是Agent工程化比较前沿的话题之一。10. 技能库设计里容易踩的七个常见坑10.1 描述过长导致路由失真有些开发者为了“全面”把技能描述写成上千字的小论文。结果是注意力被无关细节占据模型反而忽略了关键触发词。我的经验是技能描述控制在150~300字核心触发条件必须放在前两句并保持精简。10.2 没有做“技能冲突检测”新技能上线前必须检查是否与已有技能存在功能重叠。可以用简单的向量相似度算一遍如果相似度过高要么合并要么在描述中明确写清分工边界。10.3 技能的输入校验太宽松很多技能执行前不做参数校验LLM填错了参数执行函数直接异常。我建议在执行函数入口统一加一份基于声明的自动校验逻辑参数缺失、格式错误、超范围时直接返回友好错误而不让底层堆栈抛异常。10.4 忽略技能执行的审计日志Agent技能调用如果不记录日志出问题几乎无法追踪。我的日志设计至少包含技能名、版本、调用时间、输入参数摘要、输出状态、耗时。这些数据还是后续评估技能质量的原始素材。10.5 过度追求“万能技能”“一个技能覆盖所有相似需求”的做法短期方便长期反而容易让路由准确率下降因为技能的边界模糊了。10.6 多人维护时没有锁机制共享技能库建议采用“修改提议 评审合并”的流程不要让所有人直接向主分支提交变更。技能定义变更影响的是所有使用方必须谨慎。10.7 没有做“废弃技能”的清理技能库像代码库一样会积累大量废弃技能。废弃技能不清除路由空间会越来越混乱。建议为每个技能设置有效期或活跃度标记长期不使用的技能进入deprecated状态最终移除。11. 从单个技能到协同智能体技能库的更高价值11.1 技能库是Agent之间协作的“通用语言”在单Agent场景下技能库解决的是“Agent如何有效调用能力”的问题。而在多Agent协作场景下技能库的意义进一步放大它是多个Agent之间沟通能力的“通用语言”。试想一个内部运营体系一个Agent负责数据采集一个Agent负责内容生成一个Agent负责发布执行。它们之间不需要讨论“怎么采集”“怎么生成”只需要约定“调用哪个技能传什么参数”。技能库成了Agent的能力接口契约极大降低了协调成本。11.2 技能的可观测性是“Agent可靠性的基础”多Agent协作一旦出问题责任定位非常难。如果每个Agent的技能调用都遵循同一套声明、日志、版本格式那么问题排查就可以变成“按技能调用链追溯”而不是靠猜。所以在我看来建设Agent技能库不是阶段性的优化任务而是一项持续积累的工程资产。它像代码库、模型库一样是AI应用团队的核心竞争力之一。最后说一点个人实践层面的体会Agent技能库做得好不好长期看取决于维护纪律。今天多花一点时间写清楚技能描述、设计好测试用例、登记好版本记录未来就能少花几倍的时间排查调用混乱的问题。这个东西不需要一开始做得多宏大但一定要在最开始时就把“边界清晰、可测试、可度量、可追溯”这四条底线立住。