这两年做大模型应用我最大的感受是大家卷完模型卷提示词卷完提示词终于开始卷“agent-skills”了。这个标题看着简单但拆开来看信息量其实很大。如果你正在做Agent相关的产品或者正打算把LLM接进真实的工作流里那你一定绕不开一个问题怎么让模型稳定地“会干活”而不只是“会聊天”。答案的其中一个关键就是技能体系。这篇文章不聊虚的直接从我自己的实践出发把我搭Agent技能体系时踩过的坑、总结出的方法论、还有一套可落地的工程方案一次性说清楚。1. agent-skills到底在解决什么问题很多人刚开始接触Agent的时候习惯把它理解成“一个更聪明的对话机器人”。但真正做产品就会发现用户要的不是聊天是把事办了。而要“把事办了”光靠模型自己的知识储备远远不够它必须能调用外部能力按照业务规则执行并且在多步骤任务中保持状态。这些东西合在一起就是技能。1.1 为什么大模型离不开技能体系大模型本身是一个“脑子”但这个脑子有两个硬伤。第一个硬伤是知识陈旧。模型训练完的那一天它的知识就冻结了。你问它最新的产品价格、今天的库存、上个月的用户协议它要么胡编要么说不知道。这时候就需要“技能”去拉取实时数据把外部信息喂给模型。第二个硬伤是不具备行动能力。模型可以告诉你“应该发一封邮件”但它自己发不了它可以给你一段SQL但它连不上数据库。只有当Agent具备调用工具、执行动作的能力时它才从“建议者”变成“执行者”。所以agent-skills的核心本质是把模型的推理能力与外部工具、数据、规则解耦让模型通过“技能”这个中间层来使用它们。以我常给团队打的比方模型像一名刚入职的实习生聪明、反应快但不懂你们公司的办事流程和内部系统。技能体系就是一本“员工手册”告诉这位实习生遇到什么场景该调用什么流程出错了该找谁特殊情况下该怎么处理。没有这本手册实习生只会瞎问、瞎试、瞎撞。1.2 技能、工具、插件的边界到底在哪我观察到一个普遍现象很多人把“技能”“工具”“插件”混为一谈。但实际上如果你要把技能体系做扎实这三者的边界必须分清否则后期维护会是一团乱麻。从我的工程实践来看三者的区别可以这样概括概念本质例子关键特性工具单个原子操作无状态输入输出明确查询天气、发送短信、执行SQL只负责“做”不负责“想”技能面向目标的能力封装可能串联多个工具包含决策逻辑处理退款请求、生成周报、调度会议知道“什么时候做”和“怎么做”插件一组相关技能和工具的打包分发形式电商运营插件、数据分析插件侧重交付与安装是技能的分发载体工具是最底层的一个动作技能是编排好的“动作序列决策规则边界条件”插件则是用来打包和分发这些能力的。举个例子“发送企业微信消息”是一个工具“发送会议纪要给所有参会人并在发送前检查纪要是否完整、是否有待办事项”就是一个技能“企业协作套件”则是一个包含了多个会议相关技能的插件。这个概念理顺了后面设计系统时才不会越做越乱。2. 我眼中一套合格的技能体系应该怎么设计技能体系不是把一堆函数注册进去就完事了。我在最初的一版设计里就吃过亏——把所有能调用的接口都塞给模型结果模型的选择准确率奇低还经常调用错参数。后来我才逐步摸索出一套相对合理的设计方法。2.1 技能的粒度划分是第一道坎技能粒度过粗模型做不到精准控制粒度过细模型选择困难指数级上升。这个平衡怎么拿捏是技能设计里最考验经验的地方。我个人的切分标准是一个技能应该完成一个完整的业务目标并且这个目标通常需要2到5个步骤。少于2步说明这应该是一个工具不是技能多于5步说明这个技能过于复杂应该拆成多个子技能。还是拿退款场景说。如果你给模型暴露了“查订单”“查用户”“计算退款金额”“发起退款”“发送通知”这5个独立工具让模型自己编排它大概率会出问题——要么忘了查用户要么顺序乱掉。但如果只给模型一个“处理退款请求”技能内部去封装这5个步骤模型只需要判断“这个用户的请求是否符合退款条件”复杂度就大幅降低了。这个设计的本质是把需要“确定性”的部分收进技能内部把需要“灵活性”的部分暴露给模型。模型擅长做判断和推理不擅长精确执行多步骤流程。你把执行细节藏起来只让它做擅长的事效果自然好。2.2 技能描述决定模型能否选得对很多人在设计技能时只注重功能实现不注重描述文案。但我实测下来技能描述直接决定了模型选择的准确率甚至比技能本身的实现代码更重要。模型选技能本质上是在做“文本匹配”——技能描述就像是给技能贴的“检索标签”。描述写得模糊模型就会犹豫描述写得笼统模型就会在多个相似技能间摇摆描述里如果有歧义词模型可能直接选错。我一般会把技能描述分成三层第一层一句话说明技能做什么用动词开头清晰明确。第二层说明触发条件即什么时候应该用这个技能。第三层说明边界即什么时候不要用这个技能。举个实际例子一个“生成周报”的技能描述为指定时间段内的项目进展生成周报。当用户要求生成周报、周总结、或每周进展汇报时使用。注意如果用户只需要查看任务列表或单一任务的进展不应使用此技能而应使用“查询任务详情”技能。这段描述里“当...时使用”是正面触发条件“不应使用”是负面边界条件。给模型补上负面条件效果提升非常明显——因为模型排错比选对容易得多。2.3 输入输出声明要做成结构化约束早期我图省事技能的输入参数全部用自然语言描述。比如“订单ID”就写成“订单ID”结果模型经常传错格式。后来改成JSON Schema约束问题直接少了一大半。结构化约束的意思是每个参数不仅要声明类型还要声明格式、枚举值、约束条件、示例值。这样模型在调用时相当于有了一份标准答案可参考出错率会显著降低。举一个订单查询技能参数声明的例子我一般这样定义{ order_id: { type: string, description: 订单编号格式为10位数字示例2024081501, required: true }, include_items: { type: boolean, description: 是否包含订单明细默认false, required: false } }特别注意description这一栏写的时候要用“模型能听懂”的方式而不是“人看着舒服”的方式。比如“订单编号”写成“订单编号”模型的理解是一回事写成“订单编号格式为10位数字示例2024081501”模型的理解就是另一回事。示例值非常关键它像一个锚点能大幅降低模型理解上的随机性。3. 技能的管理与运行时机制设计完单个技能接下来要考虑的问题是技能多了以后怎么管理运行时怎么高效地让模型用起来。这部分的复杂度随着技能数量的增长呈指数上升。3.1 技能注册中心一切皆可检索当技能数量超过50个以后靠人工管理已经不可行了。你需要一个技能的注册中心统一管理所有技能的元数据、版本、状态、权限。一个技能注册中心至少应该包含以下内容技能名称和唯一标识技能描述用于给模型检索和选择输入输出Schema版本号所属领域或分类标签权限级别调用统计和质量评分注册中心最好用独立的数据存储来管理不要散落在代码里。技能一旦注册就要像API一样有生命周期管理——有上线、有下线、有版本回滚。我在实际项目中用的是一个简单的数据表结构配合管理后台操作效果比手动改配置文件好得多。真正重要的是注册中心要为模型检索技能提供基础数据。模型不可能一次读取所有技能的描述——上下文窗口不允许噪声也会淹没信号。所以你需要一个检索层把最相关的技能筛出来交给模型。3.2 技能选择的召回策略如何让模型快速找到对的技能技能选择的本质是一个“先检索、后排序、再选择”的流程。系统先列出候选技能模型再从候选中选一个或几个执行。我实践下来比较稳定的方案是混合检索。关键词匹配加向量匹配取并集再用规则加权排序。这个场景下我用到的工具有不少。关键词匹配用BM25算法实现简单、速度快、精确匹配能力强向量匹配用文本嵌入模型把技能描述和当前用户请求都转成向量计算相似度。两者取并集后按关联度综合排序取Top 5到10个候选交给模型。为什么要混合而非只用向量因为向量检索对同义词和语义相近的匹配效果不错但精准的术语匹配不如关键词。比如用户说的是“OT”over time加班技能描述写的是“Overtime”语义向量能匹配上但直接的关键词匹配更容易命中。两者互补覆盖度最高。排序阶段我还会叠加一些业务规则。比如“用户权限内可见的技能优先”“调用成功率高的技能优先”“最近使用过的技能优先”。这些规则可以在提示词里表达也可以在系统层面过滤我倾向于在系统层面提前过滤——少给模型制造干扰。3.3 技能执行时的上下文管理技能选定之后执行阶段最大的坑是上下文管理。大模型在与技能交互时最怕两件事一是关键信息被上下文淹没二是执行结果太长导致上下文爆炸。我处理这个问题的方法是遵循经典的“观察-思考-行动”循环——每个节点只传必需信息其余全部裁剪或压缩。具体落地时我一般使用这套上下文组装逻辑把“用户目标”“会话历史摘要”“技能描述”“技能执行结果摘要”四部分拼装成模型推理所需的上下文。完整对话历史不传给模型而是先用摘要模型压缩成要点。只有当模型需要回溯细节时才按需检索。技能执行结果超过阈值时自动截断并保留开头和结尾的关键部分——因为大模型对中间内容的遗忘最明显优先保住“头尾”的信息密度。这套方案在长任务、多轮对话场景里尤其好用。实测下来上下文压缩后模型的关键信息引用准确率比全量传递时反而更高——因为噪声少了注意力更集中。4. 实操从零搭一套最小可用的技能系统前面讲了不少设计层面的思考这一节我直接把一套最小可用的技术方案拆开给你看。不一定适合所有场景但胜在落地快、结构清晰可以作为你的第一版底座。4.1 系统架构和目录规划我建议的目录结构是这样的agent-skills/ ├── skills/ │ ├── __init__.py │ ├── registry.py # 技能注册中心 │ ├── loader.py # 技能加载器 │ └── skills/ │ ├── order_query.py # 订单查询技能 │ ├── refund.py # 退款处理技能 │ └── report.py # 周报生成技能 ├── core/ │ ├── llm_client.py # LLM调用封装 │ ├── memory.py # 上下文压缩与管理 │ └── router.py # 技能选择路由 ├── config/ │ └── skills.yaml # 技能元数据配置 └── main.py # 入口这样的分层思路是技能定义与调用逻辑分离注册与实现分离。新增一个技能时只需要在skills目录下新增一个文件并在配置中声明元数据即可不需要改动路由等核心逻辑。4.2 技能基类定义技能的基类我通常这样设计简单但实用# core/skill_base.py from abc import ABC, abstractmethod from typing import Any, Dict, Optional class BaseSkill(ABC): 所有技能的基类 # 技能元数据子类覆盖 name: str description: str input_schema: Dict[str, Any] {} version: str 1.0.0 tags: list[str] [] abstractmethod def execute(self, params: Dict[str, Any], context: Optional[Dict[str, Any]] None) - Dict[str, Any]: 执行技能核心逻辑 pass def validate_params(self, params: Dict[str, Any]) - tuple[bool, str]: 参数校验基类提供默认实现子类可覆盖 import jsonschema try: jsonschema.validate(instanceparams, schemaself.input_schema) return True, except jsonschema.ValidationError as e: return False, f参数校验失败: {e.message} def __call__(self, params: Dict[str, Any], context: Optional[Dict[str, Any]] None) - Dict[str, Any]: valid, msg self.validate_params(params) if not valid: return {error: msg, success: False} return self.execute(params, context)基类里至少要有三样东西元数据供模型检索和选择、参数校验保证执行前格式正确、执行逻辑。参数校验这一步很重要很多线上事故都是模型传参格式错误后技能直接报错导致的。有了Schema校验错误能在入口处就被拦截不会带病执行。4.3 技能注册与加载注册中心本身我采用了“扫描加载”的方式系统启动时会自动扫描skills目录下的所有技能文件自动提取元数据注册进内存中的字典表。# core/registry.py import importlib import os from typing import Dict, Type class SkillRegistry: def __init__(self): self._skills: Dict[str, BaseSkill] {} def register(self, skill: BaseSkill): self._skills[skill.name] skill print(f[注册] 技能: {skill.name} v{skill.version}) def get(self, name: str) - BaseSkill: return self._skills.get(name) def all(self) - Dict[str, BaseSkill]: return self._skills def load_from_config(self, config_path: str): 从yaml配置加载技能 import yaml with open(config_path, r, encodingutf-8) as f: config yaml.safe_load(f) for item in config[skills]: module importlib.import_module(item[module_path]) skill_class getattr(module, item[class_name]) skill_instance skill_class() self.register(skill_instance)所有技能元信息的来源统一从yaml配置读取新增技能只需要改配置不需要改代码。4.4 路由选择让模型替我选技能技能注册好了接下来就是让模型在合适的时机选到合适的技能。我把这个步骤封装成一个独立的“技能路由”模块# core/router.py from typing import List, Dict, Any import json class SkillRouter: def __init__(self, registry: SkillRegistry, llm_client): self.registry registry self.llm llm_client def _retrieve_candidates(self, user_input: str, top_k: int 6) - List[BaseSkill]: 先检索候选技能避免把所有技能都塞给模型 # 简化的混合检索示例 # 1. 关键词匹配从技能描述和标签中匹配用户输入中的关键词 # 2. 向量匹配用相似度计算兜底 # 这里用最简单的方式实现实际项目可替换成向量库 candidates [] keywords self._extract_keywords(user_input) for skill in self.registry.all().values(): score 0 desc_lower skill.description.lower() for kw in keywords: if kw.lower() in desc_lower: score 1 if score 0: candidates.append((skill, score)) # 按得分降序 candidates.sort(keylambda x: x[1], reverseTrue) return [c[0] for c in candidates[:top_k]] def route(self, user_input: str, context: Dict None) - str: 让模型从候选中选择技能返回技能名 candidates self._retrieve_candidates(user_input) if not candidates: return None # 构造技能选择提示词 skill_list [] for i, skill in enumerate(candidates): skill_list.append(f{i1}. {skill.name}{skill.description}) prompt f你是技能调度器。请从以下技能中选择最匹配用户请求的一项。 只输出技能名不要输出其他内容。 可选技能 {chr(10).join(skill_list)} 用户请求{user_input} 最匹配的技能名 result self.llm.chat(prompt, temperature0) result result.strip() # 确保返回的是有效技能名 for skill in candidates: if skill.name in result: return skill.name return None这个简化版本里关键词召回可能比较粗糙实际项目中你可以替换成“BM25 向量库检索”效果会好很多。但核心思路不变深召回、精选择——先靠检索把范围缩小到Top几个再靠模型做精细判断。4.5 完整调用链一个请求是如何走通的整个系统的调用流程捋一下大概是这样的用户输入“帮我查一下订单2024081501到什么状态了”。系统对输入做清洗和意图分析提取关键词“订单”“状态”。路由模块通过混合检索召回3到5个候选技能。LLM根据候选技能描述选择“订单查询”技能。系统调用订单查询技能的execute方法。技能内部完成API调用、数据清洗、结果格式化输出“订单已发货预计明天到达”。系统把结果拼回上下文LLM组织自然语言回复给用户。这套链路清晰、各环节解耦最关键的优势是每增加一个技能不需要改动任何原有逻辑只需要注册、描述、实现三步。5. 踩坑记录与排查思路技能体系做起来的第一个月我至少踩了七八个坑有些问题在日志里根本找不到原因排查起来非常耗时。这里挑几个最有代表性的按我自己的排查还原写出来希望帮你避掉。5.1 模型选了技能但拿到的参数总是错的现象模型明明选对了技能但传参经常不对。要么缺参数要么格式错误要么把用户原话直接当成参数值传了进去。排查发现技能描述里对参数说明不够详细模型不知道该怎么把自然语言转换成结构化参数。解决方案有两步。第一把所有技能的参数Schema改成JSON Schema格式并给每个参数加上description和示例值第二在prompt里增加一段“参数提取”的引导语告诉模型要把用户原话中的信息提取成结构化参数而不是直接复制。这一步做完参数错误率从35%降到10%以内收益非常显著。5.2 技能越多模型选择准确率越低现象技能从30个增加到60个后路由准确率下滑明显模型频繁在相似的技能之间选错。一开始以为是指标词写得不到位后来意识到问题出在“选择难度”上——候选空间大了模型的信息熵就大了出错率自然就高了。这就像让一个新手在电梯里面对60个按钮他肯定比面对6个按钮时更容易按错。解决方案是两步一是加强召回环节的质量确保候选技能数量控制在5到8个以内不要超过10个二是在技能描述中增加“排除条件”给模型明确的负向指示。后来我把60个技能按领域订单、用户、商品、财务分组后在每个领域内部做兜底召回和选择准确率明显回升。5.3 技能执行报错但模型依然对外说“执行成功”现象技能内部调用第三方API失败返回了错误信息但LLM在生成回复时置错误信息于不顾直接告诉用户“操作已完成”。这个问题的根源在于LLM会“自作主张”忽略错误信息哪怕错误提示就在上下文里。它倾向于给出一个“让用户满意”的回答而不是“符合事实”的回答。排查后给出的解法很直接在执行结果的返回结构里增加明确的success和error_message字段同时在Prompt中强调如果技能返回success: false必须如实告知用户失败原因并提供后续建议不得编造成功。这套强制约束之后模型编造成功的概率基本归零。5.4 技能的调用时间太长用户等得不耐烦现象涉及多步骤的技能执行耗时长UI界面一直转圈用户流失率上升。排查发现技能内部多个工具调用是串行执行的每步都要等上一个返回结果。比如查订单、查用户、查物流三个接口串行花了5秒。解法是并行化改造把相互无依赖的工具调用改成并行执行整体耗时从5秒降到2.5秒。更进一步可以加缓存层订单状态这类变化频率不高的数据缓存30到60秒命中缓存时直接跳过API调用。做一个合理的预估串行变并行这部分技能的平均响应时间能压缩一半以上。6. 从能用到好用给技能体系加一点工程化味道技能系统能跑通只是第一步真正能稳定支撑业务还要在工程化上下功夫。这里的“工程化”主要指三件事版本管理、质量评估、可观测性。6.1 版本管理与灰度发布的思路技能的代码会和业务逻辑一起迭代。改一个技能的内部逻辑时很可能影响正在进行的对话或流程。所以技能版本管理非常有必要。我一般这样设计每个技能都有版本号注册中心同时保留当前版本和上一个稳定版本。当新版技能上线后先让10%的流量走到新版本观察调用成功率和质量指标确认没问题后再全量切换。发生问题可立即回滚到旧版本。这部分的基建成本不算高但收益巨大——再也不用因为改了一个技能就提心吊胆了。6.2 技能质量评估如何知道技能到底好不好用评估维度我个人比较关注四个指标指标怎么衡量说明选择准确率路由选对的次数 / 总选择次数衡量技能描述质量解析成功率参数通过校验的次数 / 总调用次数衡量参数Schema质量执行成功率技能内部逻辑正常结束的次数 / 总调用次数衡量技能实现质量结果有效率用户对技能结果满意的比例衡量技能整体价值这四个指标每一个出问题对应的解决方案也各不相同选择准确率低了改描述解析成功率低了改Schema执行成功率低了改代码逻辑结果有效率低了大概率是技能本身的设计方向有问题。6.3 可观测性日志要能还原现场Agent调试的难点在于你很难复现问题——同样的输入模型输出可能都不一样。所以日志系统要做好“现场还原”能力。我强烈建议至少记录以下几类信息用户原始输入和会话上下文召回候选技能列表含得分模型选择结果及对应置信度参数提取结果即模型生成的JSON参数技能执行结果和耗时LLM最终生成回复的完整内容有了这些日志排查问题时会轻松很多。定位逻辑也很简单——先看是不是选错了技能如果没选错再看是不是参数传错了如果参数也没错再看是不是执行时报错了一层层剥开问题基本就能锁定。7. 最后再分享一个小经验我个人在实际操作中发现“技能”这两个字听上去是技术概念做起来却更像产品设计。你的用户会怎么说需求你的业务有哪些边界条件你的模型在什么情况下容易踩坑——这些都不是纯代码层面能解决的事而是需要大量业务理解和经验积累。当你开始为一个又一个真实场景设计技能时你会慢慢找到那种感觉好的技能体系是在给模型画一张清晰的地图让它在合适的路口转弯在错误的入口前停下。模型的能力决定了车的性能而技能体系决定了这条路修得够不够顺。我在做完第一版技能系统后有个非常明显的体会Agent的能力上限焦虑它没太大帮助不如把功夫下在技能体系的打磨上——把每一个技能描述改准确一些把每一个参数Schema设计得周密一些把每一次错误归因清楚一些。Agent就会以肉眼可见的速度变“聪明”。而这份“聪明”其实是你把经验一点点灌进去的结果。