坦白讲，第一次看到“agent-skills”这个词，是在某次内部技术分享的草稿里。当时团队正在为一个大模型对话系统增加“让模型自己决定调哪些工具”的能力，试来试去发现最麻烦的不是模型不会调，而是我们不知道该把什么能力“交给”模型。一个朋友提议：像给员工写岗位说明书一样，给模型写技能说明书。于是整个思路就顺了——与其在代码里堆满if-else判断用户意图，不如把这些可复用的子能力拆成一个个独立技能，让模型自己看着办。这就是我对agent-skills的理解：一套面向智能体（Agent）的技能封装与调用范式，把大模型完成复杂任务所需要的能力沉淀成可组合、可复用、可单独测试的小模块。
这篇文章不是讲某个开源框架的API怎么用，而是聊聊我自己在模拟项目里从零搭建这套技能体系时的完整思路：为什么需要拆技能、技能和普通函数的边界在哪、怎么让大模型正确选择技能、以及技能多了之后会遇到哪些让人头疼的问题。适合正在做智能体应用、为大模型接工具、或者被“模型行为不稳定”折磨的开发者参考。
1. 智能体为什么要“技能化”：从一次失败的对话说起
先讲一个我自己的真实经历。早前做某跨平台系统的智能客服模块，计划是让大模型直接回答用户关于订单、物流、售后的问题。最初方案很天真：把所有能力函数一股脑注册给模型，让Function Calling自己选。结果上线没两天就出了岔子——用户问“我的快递到哪了”，模型竟然调用了“退款申请”函数，因为它在上下文里看到了一个“refund”相关字段。更离谱的是，有一次模型为了查一个订单号，连续调了三次不同的查询函数，因为每次都拿不到完整参数。
复盘之后发现，问题根本不在模型，而在我们“交付能力”的方式。如果每个函数都是松散、局部的操作，模型缺乏对“这个能力在什么场景下用、需要什么前置条件、输出会怎样影响后续动作”的整体认知。这就好比一个新人入职，你只告诉他“这个按钮可以退款”“那个接口能查状态”，却不告诉他完整的岗位职责——他当然会乱按。
Agent Skills要解决的核心问题，就是把零散的函数调用，升级为结构化的“能力词条”。每个技能不只是代码，还附带足够多的上下文说明：它解决什么问题、输入输出长什么样、什么时候用、什么时候坚决不可以用。模型看到的不是“函数列表”，而是一份“技能岗位说明书”。这种转变带来的直接效果是：选型准确率大幅提升，因为技能自带决策边界。
skill这个词在开源社区里的流行，也和这套思路高度一致。它本质上是在强调：Agent不是靠一个巨大的Prompt控制世界，而是靠一个个可以独立打磨的“小工具包”组合出复杂行为。就像人类员工不可能靠一本员工手册完成所有工作，而是靠培训、经验积累和各种专用工具。
1.1 技能与普通函数的本质区别
可能有人会说：“这不就是把函数写得规范点吗？跟文档注释有什么区别？”如果只看表面，确实像。但深度用下来，技能化至少带来四个普通函数注释完全覆盖不了的变化：
一是选择维度更丰富。函数调用时，模型只根据参数和描述做决策；而技能可以额外声明触发条件、使用场景、输出格式，甚至可以声明“与其他技能的组合关系”。这让模型在多技能候选中有更强的排歧依据。
二是可测试性大幅提升。普通函数好坏靠单元测试验证，但技能好不好要靠“场景模拟”验证——即给模型一个完整对话上下文，看它是否能选对技能、是否能正确传参。技能化天然把“模型决策”从业务逻辑中分离出来，让测试更有针对性。
三是组合能力成为可能。技能A的输出可以直接作为技能B的输入，前提是两者的Schema设计成兼容的。普通函数也能串，但很少有团队会为一个函数专门标“产出物类型”。技能化会强制你定义这些接口关系。
四是迭代策略不同。改一个函数可能影响所有调用方，但改一个技能的描述或参数，受影响的是模型在特定场景下的选择行为。你可以针对某个场景单独优化一个技能，不需要大范围重构。
从这些差异可以看出，技能化不是函数换个马甲，而是把“让模型用能力”这件事从工程维度提升到了设计维度。
1.2 技能库的两种常见形态
我对技能形态的粗分类是“单步技能”和“编排技能”。单步技能是最小颗粒，比如“查询订单状态”“计算两个日期差”“生成随机ID”，这类技能通常直接对应一个工具调用，返回结构化结果即可。编排技能则是多个单步技能的串联，比如“订单全生命周期查询”技能内部可能依次调用了订单详情、物流轨迹、售后状态三个基础接口。
实际项目中，我比较推荐把编排技能尽量做薄，甚至不要急着沉淀。因为编排逻辑往往和具体业务场景强绑定，过早固化会让技能失去复用价值。我见过一些人把一个月度报表生成流程整个封装成一个“报表技能”，结果换了一个数据库就得重写。更合理的做法是只沉淀“取数”“算同比”“渲染图表”这类原子技能，把编排交给大模型自己通过多轮调用来完成。
这种“薄技能、厚组合”的思路，也为后面讲技能注册和上下文管理埋了个伏笔。
2. 技能注册表设计：让大模型一眼看懂该怎么选
Agent技能要能被正确选择，关键在注册表的信息结构。我自己在模拟项目X里经过四轮重构，最后稳定下来的技能元信息结构包括五大块：标识与版本、目标场景描述、输入输出结构、使用约束、示例对话。这五个字段各有各的坑，下面拆开讲。
2.1 技能名称与描述：名字里藏着选择陷阱
技能名不能太宽泛，也别太狭窄。一个典型的反面教材是我早期命名“get_data”——听起来什么都能干，模型一遇到需要数据的情况就给这个技能发指令，参数却完全对不上。后来强制要求技能名必须由“动作+对象”构成，比如“fetch_order_detail”“calc_price_difference”，并且在描述第一行写明“仅用于XXX场景，不要用于YYY”。
描述长度也很有讲究。太短，模型抓不住边界条件；太长，会占用上下文窗口，而且容易让模型“过度联想”。我们的经验是控制在50到100个中文字符之间，覆盖三点：这是干什么的、什么时候用、什么时候千万别用。举个例子：
“查询单个订单的全链路状态。适用于用户明确询问订单进展或物流节点；当用户仅询问退货或退款时，请调用售后类技能而非本技能。”
这种描述在Function Calling场景下能显著降低误调用。可能有人觉得中间那句“千万别用”很多余，但实测它的作用是压制模型的错误倾向——大模型在选择工具时存在明显的“惯性联想”，明确设置禁区比反复强调适用范围更重要。
2.2 输入输出Schema：接口边界决定技能能否被复用
输入输出Schema设计是整个注册表里最费心的地方，它直接决定技能能否被其他技能复用。我一般遵循三条原则：
第一，所有输入参数必须有默认值或者显式optional标记。模型不是可靠的参数补全器，哪怕它觉得某个参数“应该”有值，也可能漏传。宁可让技能内部做一次默认处理，也不能让调用因为缺参直接报错。
第二，输出必须包一层统一结构。不要直接返回一个裸字符串或者数组，而是统一为“{success, data, message}”这样的信封结构。这样不管调用方是人还是另一个技能，都能按固定模式解析结果。我在早期没这么做，后来写编排逻辑时不得不写各种兼容解析分支，痛得很。
第三，枚举值和取值范围要写具体。比如“status”字段，绝不能写“string”，要写成“['PENDING', 'SHIPPED', 'DELIVERED', 'RETURNING']”。大模型看到可枚举值后，错误传递参数的概率会低很多，同时也能在调用前就把明显错误筛掉。
2.3 技能入库后的描述更新机制
技能注册表不是写完就冻结的文档。实践下来的最佳效果是给它建立一个“观测-反馈-更新”的闭环：每天导出模型选择技能时置信度较低的cases，人工抽看是描述模糊导致的误选，还是技能本身边界和用户意图冲突，然后针对性地改描述或调整Schema。
这种更新频率在一周两三次左右比较合适，太频繁会导致模型刚适应的选型行为又被扰动，太少则会让错误反复存在。所有描述变更必须走版本记录，因为技能的行为直接影响线上对话效果，需要能够随时回滚。
3. 把技能“讲”给大模型：两大路线的取舍心得
技能定义好了，怎么交付给模型使用其实是另一道坎。我试过两种路线——纯函数调用式（Function Calling）和系统提示词注入式。
3.1 路线一：Function Calling注册，精准但依赖模型能力
Function Calling是目前把技能暴露给模型最主流的方式。每个技能映射为一个JSON Schema工具描述，模型在需要时生成一个结构化调用请求。优点是对模型选择行为的约束力更强，不依赖自然语言理解，匹配度较高。这也是很多成熟框架默认采用的方式。
但这条路线有两个现实痛点。一是上下文窗口消耗不容忽视：每个工具描述几千个token，注册20个技能就接近十万字符，对话轮数一多，可用上下文迅速吃紧。二是它对模型本身的工具选择能力要求很高，小参数模型很容易在多技能候选里“花眼”。我会建议在模型推理能力不够强时，不要一次性注册太多技能，及时摘除低频技能，只保留高价值集合。
3.2 路线二：System Prompt注入，灵活但容易失控
另一种做法是把技能说明写成自然语言段落，放进系统提示词里。好处是模型理解更“自然”，特别适合那些无法用严格Schema表达的启发式技能，比如“遇到用户情绪激动时优先安抚再处理工单”。而且写入Prompt的内容可以带演示案例（few-shot），模型模仿效果会更好。
坏处也非常明显：技能描述长了之后，模型会“遗忘”早期技能；而且不同技能之间的优先级关系在纯文本中很难表达清楚。我做了一个混合方案：把高频、强结构的技能走Function Calling，把策略类、判断类的软技能写进System Prompt。两者互不干扰，实测下来比单用任何一种都稳。
3.3 避免技能之间“争抢”：优先级与冲突消解机制
技能多起来之后，最搞笑也最头疼的问题是两个技能同时想被选中。比如“查物流”和“发催件提醒”，如果用户说“帮我看看快递怎么还没到”，两个技能看起来都沾边。模型选错后，用户看到的结果就是答非所问。
我的解决方式是在技能描述里显式加入“冲突优先级”说明。比如在“发催件提醒”技能描述里写：仅在用户明确要求催促或投诉时选用，普通查询请调用物流查询技能。同时从逻辑上保证查询类技能的触发条件被更优先满足。这种约定俗成的做法，比在代码层面强行做路由简单可靠得多，也符合大模型偏好“文本规则”的特性。
4. 手写一个真实技能的全流程：网页标题与环境信息采集
光讲框架太空了，我把模拟项目X里写过的“网页正文提取与结构化摘要”技能拿出来，完整走一遍从定义到落地的流程。这个技能虽然不算复杂，但麻雀虽小五脏俱全，很适合作为参考样板。
4.1 技能定义文档
{ "name": "fetch_page_summary", "description": "抓取指定网页的正文内容并生成结构化摘要。适用于用户提供网址并请求概括、提取要点、生成摘要等场景。禁止用于需要登录或明显违反访问条款的页面。", "parameters": { "url": {"type": "string", "description": "需要抓取的完整网页地址"}, "max_length": {"type": "integer", "description": "摘要最大字数，默认300"} }, "output": { "title": "string", "content_type": "string", "summary": "string", "keywords": ["string"] } }注意这里的描述明确把“禁止用于需要登录的页面”写进去了。这个边界不仅对模型有提示作用，也让调用方能够前置判断。有些页面其实能抓到登录墙后的内容，但用了会有合规风险，规范起见技能层面直接拒绝。
4.2 技能核心实现（Python）
import requests from bs4 import BeautifulSoup def fetch_page_summary(url: str, max_length: int = 300): headers = {"User-Agent": "Mozilla/5.0 (compatible; AgentSkills/1.0)"} try: resp = requests.get(url, headers=headers, timeout=10) resp.raise_for_status() except Exception as e: return {"success": False, "data": None, "message": f"抓取失败: {str(e)}"} soup = BeautifulSoup(resp.text, "html.parser") title = soup.title.get_text(strip=True) if soup.title else "" # 移除脚本、样式等噪声节点 for tag in soup(["script", "style", "nav", "footer", "aside"]): tag.decompose() paragraphs = [p.get_text(strip=True) for p in soup.find_all("p")] content = "".join(paragraphs) # 简单摘要生成，实际项目可换用大模型做抽象提取 if not content: return {"success": False, "data": None, "message": "页面无可提取正文"} summary = content[:max_length] + ("..." if len(content) > max_length else "") return { "success": True, "data": { "title": title, "content_type": "text", "summary": summary, "keywords": [] }, "message": "ok" }这段代码里有两个刻意为之的细节。第一，返回结构统一为success/data/message三层信封，方便后续编排技能时直接判断成功失败。第二，抓取失败不会抛异常，而是返回一个结构化的错误信息，让大模型可以根据message内容决定是重试还是换一个技能。其实在实际的某个图像处理Demo上我还试过更复杂的版本，加入了对返回结果的语义校验，但核心原则都一样。
4.3 注册与本地联调观察点
技能写完后，把它注册到测试环境，用几个构造好的对话样本跑一遍，观察模型选择该技能前后是不是做了多余的描述或参数修正。如果模型选得很犹豫，通常说明描述里还缺一个关键“触发词”。
这个启动环节我最看重三个指标：选择准确率、参数命中率、结果可用度。选择准确率指正确技能被选中；参数命中率指传入参数是否合法且完整；结果可用度则是看输出给用户的内容，是原样抛JSON还是经过加工。 注意，这三个指标不是上线前测一次就结束，而要在每次技能库扩容后都回归一遍。技能多了后，旧技能的选择概率会被新技能稀释，你要让自己对每个技能的“真实命中率”心里有数。
5. 技能库膨胀后的三个典型故障：上下文膨胀、互相干扰、遗忘
当技能数量超过15个之后，问题就会集中爆发。我经历过的最典型故障是这三类，这里逐个说清楚根因和应对手段。
5.1 故障一：上下文膨胀让模型“看不清”技能列表
在Function Calling模式下，技能描述最终都会拼装成模型输入的一部分。大量技能描述叠加，上下文体积很快就撑起来了。模型在超长上下文中对末尾技能的注意力会明显下降，于是高频技能反而可能被忽略。我试过在50个技能时，模型对靠后技能的调用率几乎跌破三成，等于白注册。
应对方式分两步。第一步是强制“召回式注册”，只在每轮对话开始前，用一个检索模型判断用户意图可能涉及哪几个技能，然后只把Top-5到Top-8的动态注册给模型。第二步是为每个技能写“短版本描述”，用于召回阶段匹配，全量版本则在真正调用时才传入参数细节。
这套机制类似人类查通讯录：你不需要把一万个联系人的详细资料常驻在脑子里，只需要知道哪个人是干什么的，拨号时再调取详细号码。Agent技能管理同样如此。
5.2 故障二：技能边界重叠引发的“抢活”
两个技能如果描述太相似，模型会随机选一个，结果时好时坏。比如我早期有“查天气”和“建议出行装备”两个技能，用户说“明天上海冷不冷”，两个技能都符合触发条件。后来我给“建议出行装备”加了一个强约束：“只在用户明确询问服装、装备建议时使用”，并在示例中补充了“查询温度请调用查天气技能”。加完这个约束，误选率直接降了一半。
边界重叠这个坑很难靠Schema完全避免，需要持续从线上日志里抽样本检查模型选择轨迹。我现在每两周会做一次技能冲突检测：把两个技能描述放入同一个测试Prompt，让模型只依据描述做二选一，看模型是否稳定选择预期的那个。选不准，就说明边界描述还得打磨。
5.3 故障三：模型“遗忘”技能的存在
模型在长对话里不会忘记你说过的话，但它会随着上下文拥挤、任务复杂化而降低对工具信息的注意力，尤其当技能描述是放在最开始位置的System Prompt中时。遗忘的典型表现是：模型直接凭借训练知识回答，而不调用技能获取实时数据。
补救手段主要有三种：把关键技能的关键触发词在每轮对话中重复一遍，这就是“关键词提醒”；或者在中间节点插入轻量系统消息，提醒模型哪类情况必须技能调用；还有就是给技能编上“人工路由兜底”，如果检测到模型明显未调技能，但用户问题又属于已知技能域，则由规则引擎强制触发一次技能调用。三种里最有效的是第三种，但需要额外做一层意图检测，对不同项目来说成本不一。
6. 给技能做“上岗考核”：离线评估与回归测试的简易方案
技能不是写完就算交付，它需要像员工一样定期背调。我常用的考核方式不复杂：准备一组“话术样例库”，每个样例标注应当调用的技能和期望传参，然后批量让模型执行调用选择，统计出选择准确率和参数命中率。
6.1 样例库结构与标注策略
我的样例库按场景集群组织，比如“订单查询场景”“物流催件场景”“价格比较场景”。每个场景下放20到50条用户话术，覆盖正常表达、模糊表达、边界表达、故意诱导四种情况。边界表达是考核重点，例如用户说“我要把快递退了”，正确动作是调售后技能，但模型很容易被“快递”这个词引到物流查询。
标注策略上也有一条值得分享的心得：不要只标“正确技能名”，还要标注“错误技能名”。因为回归测试时，我们不仅想知道模型对不对，更想知道它是否偏向某个特定错误选项。像“用户要退货时模型总是选物流查询”，这个信号会提示你该在售后技能描述里加强“仅用于”的约束。
6.2 回归测试的触发时机与自动化
技能库每一次重要变更都必须跑一轮回归。我把回归测试嵌进了发布流程：任何一个技能描述或Schema的改动，都自动触发样例库全量跑批，输出准确率对比报告。如果某项指标比上周下降超过5个百分点，系统会拦住这次发布，要求补充异常原因说明。
这套机制刚开始部署时，有些同事嫌麻烦，觉得改动一个参数就要跑两百条测试太慢。但实际用了三个月后，所有人态度都变了——因为它确实拦住了不少“看起来没问题、上线就翻车”的改动。自动化回归的价值，不是保证每次上线都完美，而是让你对技能的稳定性变化始终有数。
6.3 几个容易被忽视的评估陷阱
第一个陷阱是“样例库老化”。用户话术会随业务变化而更新，半年不维护样例库，评测结果再漂亮也只是幸存者偏差。每隔一段时间，应当人工抽取线上真实对话，替换老旧的样例。
第二个陷阱是“只看选择准确率”。选择对了但参数传错，用户一样得不到正确结果。完整的考核必须包含参数命中率的校验，而且要对关键参数（比如订单号、日期、金额）做额外专项抽检。
第三个陷阱是“忽略技能内部执行失败的比率”。有时候模型选对了技能，但技能自身因为依赖的接口变了而频繁返回失败。这时候考核模型没有意义，你该去修技能内部的适配逻辑。 这提醒我：把技能看作一个带依赖的下游服务，它的健康状态需要单独监控，而不是和模型选择行为混为一谈。
7. 演进方向：技能市场、版本管理与人机协同的新可能
做到后期，我开始认真思考一套更成熟的项目结构如何设计，核心是想解决“技能如何在不同项目间复用”“技能版本如何管理”“非技术背景的人如何参与技能校准”这三个问题。模拟项目X里用了一套约30个技能的完整体系，输出稳定性和开发效率都有了明显提升，但目前只验证了一部分思路。
技能市场化的核心是“出色技能描述本身就可以当作可交易的知识资产”。以后各业务团队可以把已验证的高质量技能（连同测试样例和评估报告）打包成可共享的资源包，新项目无需从零构建，直接导入相关技能集，适配一下局部参数就能使用。这个概念有点像函数库的开放生态，只是更强调语义和场景导向上的一致性。
版本管理也是被低估的一块。技能描述微调与技能代码变更耦合在一起，往往说不清楚到底是哪里导致行为变化。理想的版本策略是技能文件形态统一为“JSON定义+代码实现+评测报告”三件套，任何变更都生成一个新的技能版本号，变更记录纳入测试报告对比。实践上哪怕做不到全自动，单纯坚持手动维护这份三件套，也能让排障时间缩短不少。
至于非技术背景的人参与校准，我认为是个真正的加分项。客服团队、销售团队对用户意图的判断往往比开发者更敏锐，如果技能描述可以用相对通俗的规则语言编写，那么业务人员也能直接指出“这句话用户其实是想退款”并修正技能边界。我已经在尝试把技能描述从纯技术Schema改成“策略提示词+参数表”的写法，这个方向上确实值得更多人投入精力。
智能体的能力边界不是由模型单方面决定的，而是由你愿意给它沉淀多少高质量技能决定的。agent-skills表面上是技术工程，实质上是知识管理——把散落在对话行为、代码逻辑、业务经验里的能力，逐步固化成了可以不断迭代、迁移、复用的资源。希望这篇分享能帮你少走我走过的弯路。
