这两年做Agent开发绕不开的一个词就是skills。不管是把模型接入业务系统还是做个人助理只要想让它真正干点事就得给它配上可执行的技能。很多团队最初的做法是在代码里堆if-else后来发现不够灵活再后来接了 Function Calling又发现函数列表一长模型容易选错、参数容易幻觉。我从“agent-skills”这个主题出发把自己撸技能系统的经验完整整理了一遍包括技能怎么定义、怎么封装、怎么编排、怎么评估以及那些从日志里才能翻出来的坑。这套思路适合正在做 Agent 应用开发的工程师、想给大模型接工具的团队也适合准备从零搭建智能体平台的决策者。我尽量不写空话所有内容都围绕“可落地的技能系统”展开给出可以直接抄走的设计方案和代码骨架。1. 技能系统的底层逻辑为什么Agent需要“技能”1.1 从“工具调用”到“技能系统”的进阶先理清一个概念。很多人把 Function Calling、Tool Use、Agent Skills 混在一起说但它们在工程上的难度完全不是一个量级。Function Calling 解决的是“模型知道该调哪个函数”这个问题。你给模型一堆函数定义它输出一个结构化调用请求程序去执行。这是单次交互做完就结束模型不关心结果是否合理也不关心上下文里接下来要干什么。Tool Use 比函数调用更进一步它允许模型在对话过程中反复选择工具、传参、拿到结果、再继续推理。这已经是 Agent 的基础形态了。但 Skills 不一样。一个完整的技能应该天然包含三个东西触发条件、执行动作、结果反馈闭环。它不仅仅是“一个函数”而是“用模型能理解的语言把一段可复用逻辑封装成可触达的能力”。我举一个生活化的例子。给一个人一把扳手他未必会把水管修好因为他需要“管道维修”这个技能给一个Agent一个API它未必能完成报销流程因为它需要知道提交审批、保留凭证、确认金额这些动作的先后关系。技能本质上不是工具本身而是“用工具的完整套路”。这也是为什么直接堆 Function Calling 容易翻车。你把 30 个函数一次性塞给模型它经常选错、漏选、乱传参。而技能系统的核心价值是通过描述、参数契约、执行方式和反馈机制把每一个能力包装成一个“边界清晰、可被精确触发、可被稳定执行”的单元。1.2 技能系统的核心构成从系统架构角度看一套技能系统至少包含五个部分模块职责类比技能描述层告诉模型什么时候该用、怎么用岗位说明书参数契约层定义输入输出结构、必填项、取值范围接口规格书执行层真正跑业务逻辑调用外部服务或代码干活的人反馈层把执行结果转成模型能理解的文本工作汇报编排层把多个技能串成一个流程项目经理我见过不少团队把注意力全部放在执行层写了很多功能函数但对描述层和反馈层毫不上心。结果就是模型触发率很低日志里大量出现“no tool call”或者“幻觉参数”。可以这样理解模型是一个只有大脑的人它眼睛看不见、手也伸不出去只能靠技能系统把感知和行动力补上。如果技能描述含糊等于让这个人摸黑找工具如果反馈层只有一堆原始返回值等于递给他一张乱码纸条。所以我在设计技能时最看重的是“模型能不能一看就懂、一调就中”而不是后端逻辑写得有多炫。2. 技能设计与封装从需求到可复用2.1 技能描述怎么写才能被模型正确触发这是整个技能系统里性价比最高、也最容易被忽略的环节。很多人写技能描述就是一句话“查询天气”然后指望模型自己理解结果经常出现两种问题该触发时不触发、不该触发时乱触发。原因很简单——描述信息量不够。我给技能描述定义了四个要素意图、场景、边界、参数。意图这个技能是干什么的用一句话讲清楚。场景什么情况下应该用最好给出正例和反例。边界什么情况下不能用避免模型硬套。参数完整的入参说明包含类型、范围、默认值、是否必填、参数间依赖关系。用一个反例来说明。如果技能描述只写“get_weather: 获取天气”模型大概率在用户问“今天适合穿什么”时不敢触发因为它不确定该不该调用反过来用户问“南京最近冷吗”模型也可能把这个技能和地理位置查询搞混。更好的描述结构大概是{ name: get_weather, description: 根据城市名称获取当前天气和未来24小时预报。当用户询问温度、降雨、风力、出行建议时使用。不要用于计算历史气候或长期预报。, parameters: { type: object, properties: { city: { type: string, description: 城市名称例如 北京、上海、南京注意不带市字 }, days: { type: integer, description: 预报天数取值1到7默认1 } }, required: [city] } }不要小看“注意不带‘市’字”这种细节。模型在生成参数时非常容易被用户的自然语言带偏用户说“北京市明天天气”模型可能把 city 填成“北京市”。如果后端查询接口要求的是不带后缀的地名这里就会报错。所以参数描述里必须写明格式约束并且在反馈层把异常原因解释清楚让模型有机会自我纠正。2.2 一次真实的技能定义过程我以“会议室预定”技能为例完整走一遍定义流程因为会议室预定这种场景比天气查询更接近真实业务涉及权限、冲突、时间等多种因素。先拆分业务需求。用户说“帮我订明天下午三点的会议室四个人”技能需要做几件事校验用户身份、查询空闲会议室、选择最近的可用房间、创建预定记录、发送通知。如果把这一整个流程塞进一个函数逻辑臃肿且难以调整如果把每一步拆成独立技能模型需要多次调用容易在中间状态丢参数。所以我的做法是拆成三个原子技能query_free_meetings: 查空闲会议室book_meeting_room: 预定指定时段会议室cancel_meeting_room: 取消预定路由和决策逻辑交给模型。用户让“订会议室”模型先触发query_free_meetings拿到候选列表后会自己决定用哪个房间再触发book_meeting_room。这样每个技能职责单一可复用性高比如用户只问“有没有空会议室”只需要走第一个查询技能不会触发预定。在处理入参时有一个很容易踩的问题用户说“三点”到底是指 15:00 还是“三个小时后”经验是不要把这样的计算逻辑丢给模型。我在技能参数里允许传入相对时间比如tomorrow 15:00、now 3h然后由后端代码统一解析。这比让模型自己算偏移值靠谱得多因为模型算时间几乎必错。预定冲突时反馈信息也很关键。如果返回“房间已被占”就结束模型只能干巴巴地告诉用户没房间。更好的反馈是带上相邻时间段的空闲情况比如“该时段已被占用但14:00-15:00和16:00-17:00有空房”这样模型有机会继续帮用户调整。这也是我强调的反馈层设计执行结果不仅是成功或失败还要给模型提供下一步决策的线索。2.3 技能的复用性与组合技能做完不是只能给一个Agent用。设计得当的话一组高度内聚的原子技能可以组合出多种上层应用。我把技能分为两类原子技能只做一件事入参少执行逻辑单一。例如“发送邮件”“查询订单状态”。组合技能在编排层把多个原子技能按固定顺序执行适合处理相对固定的业务规则。例如“售后流程”可以组合查询订单、校验售后范围、创建售后单、通知用户。组合技能可以有两种实现方式。一种是在代码里用工作流引擎硬编码执行顺序另一种是让模型通过推理动态编排。前者稳定但僵化后者灵活但不确定。我的建议是关键路径用代码编排非关键路径交给模型。比如“创建订单必须校验库存再扣款”这种不可跳过的顺序放代码里“根据用户情绪决定道歉方式”这种下游分支放模型里。还需要考虑技能版本。技能逻辑变了旧会话里的Agent还在执行旧版本会导致结果不一致。我在技能注册表里会带上version字段并保留上一版本的回滚入口。做线上变更时先灰度新版本把命中率和错误率对比一周再全量。3. 技能系统落地实操从0到1实现一个最小可用框架3.1 技术选型与架构设计技能系统不绑定特定语言但如果你要从零搭建我推荐 Python。原因不是别的而是生态和调试成本大模型相关的 SDK 几乎都有 Python 体系且内网开发环境一般都能快速装上依赖。我搭了一个最小可用的目录结构可以当作脚手架参考agent-skills/ ├── skills/ │ ├── __init__.py │ ├── registry.py # 技能注册中心 │ ├── schemas.py # 参数校验定义 │ └── weather/ │ ├── __init__.py │ ├── skill.py # 技能执行逻辑 │ └── prompts.py # 技能描述与提示词片段 ├── runtime/ │ ├── dispatcher.py # 调度器负责触发和分发 │ ├── executor.py # 执行器负责调用具体技能 │ └── llm_client.py # 大模型统一封装 ├── tests/ └── config.yaml核心是registry.py和dispatcher.py。前者维护所有技能的结构化定义后者负责把模型输出的函数调用路由到正确的技能对象。这两块做干净了加技能就像填表。选型上有一个取舍要说明用不用 Agent 框架我实际对比过几类方案更成熟的方案适合快速原型验证但进入生产后技能加载、参数校验、日志审计这些能力还是要自己在框架层做二次开发。最终我选择保留调度器自研只复用大模型调用链路的封装可控性会明显更好。3.2 关键代码实现技能注册表与调度器先看注册表。它的作用是把 JSON 里的技能定义加载成可执行对象并提供按名称查询的能力。# skills/registry.py import importlib import json from typing import Dict, Type class SkillRegistry: def __init__(self): self._skills: Dict[str, dict] {} def register(self, name: str, skill_def: dict, module_path: str): skill_def 包含 description, parameters, version 等元信息 module_path 指向包含 execute 函数的模块 module importlib.import_module(module_path) self._skills[name] { definition: skill_def, handler: module, } def get(self, name: str): skill self._skills.get(name) if not skill: raise KeyError(fskill not found: {name}) return skill def list_definitions(self) - list: 返回全部技能定义供 LLM 调用时拼进提示词 return [s[definition] for s in self._skills.values()]调度器的核心职责更直接接收模型输出的 tool_call校验技能存在然后调用handler.execute。# runtime/dispatcher.py from skills.registry import SkillRegistry class Dispatcher: def __init__(self, registry: SkillRegistry): self.registry registry def dispatch(self, tool_call: dict): name tool_call.get(name) arguments tool_call.get(arguments, {}) skill self.registry.get(name) handler skill[handler] # 技能内自行处理参数校验必要时把原样错误抛给模型 try: result handler.execute(**arguments) return {status: success, output: result} except Exception as exc: return {status: error, error_message: str(exc)}每一段都要说清楚为什么这么做。list_definitions把全部技能定义返回给上层由上层拼进 system prompt。如果技能数量超过一定阈值就需要做技能检索。我实测的经验是技能描述总长度超过 3000 token 时模型选择的准确率明显下降。所以生产环境下我会按场景做技能子集划分比如“人事场景”只注入人事相关技能“财务场景”只注入财务相关技能而不是一股脑把所有技能全塞进去。3.3 参数校验与超时、重试的设计参数幻觉是 Agent 开发里最常见的坑。模型传了一个 JSON 格式的入参但字段名是错的、枚举值超出了合法范围、必填字段也缺失了。我的处理方式是在技能执行层做两层校验。第一层JSON Schema 校验用校验库做基础格式检查。from jsonschema import validate, ValidationError def validate_arguments(arguments: dict, schema: dict): try: validate(instancearguments, schemaschema) except ValidationError as exc: raise ValueError(f参数校验失败: {exc.message})第二层业务语义校验。比如日期必须晚于今天、金额不能为负数、城市必须在服务开通范围内。这一层写在技能内部因为只有业务代码知道这些约束。设计超时与重试时不能用一套参数打天下。我把技能分为“快技能”和“慢技能”前者如数据库查询超时时间设为 3 秒后者如调用第三方审批流需要 15 到 30 秒。调度器对慢技能采用异步任务模式不阻塞模型主线程执行完成后用消息或回调把结果带回来。这里有个很多人没注意的细节重试不能无脑叠加。如果是参数错误重试一万次也没用应该把错误信息返回给模型让它修正参数或向用户确认如果是下游服务超时可以重试两次但每次重试间隔要递增比如 1 秒、3 秒避免在服务抖动时打爆下游。我给调度器加了一个简单的重试策略配置RETRY_POLICY { default: {max_retries: 1, backoff_seconds: 1}, idempotent_skill: {max_retries: 3, backoff_seconds: [1, 3, 5]}, }判定技能是否幂等很关键。查询类技能可以安全重试创建类技能如果下游没有做幂等重试可能导致重复下单、重复预定。这种技能应该优先做幂等键而不是依赖重试。3.4 反馈结果如何“喂”给模型执行完技能之后返回结果需要经过一个格式整理过程这一步我把它叫反馈翻译层。几乎所有新手都会忽略它直接把 JSON 原始结构丢回提示词给模型看。后果是模型经常被大量无用字段带偏或者无法从冗长的返回值中提取用户要的信息。比如天气技能的下游 API 返回一个包含 47 个字段的 JSON湿度、气压、紫外线指数、能见度、过敏指数……但用户只问“明天要不要带伞”。我建议在技能内部完成提取只返回一小段文本明天2025-06-20北京小雨转多云气温 22~28℃东南风 2~3 级。 降水概率 70%建议携带雨具。模型拿到这段文字直接就能组织成自然的回答。而且这段文字还隐含了“是否带伞”的结论性信息模型不需要自己再做推理大大降低了中间出错的概率。4. 技能系统的运维与评估别只造轮子还要看它跑得好不好4.1 技能命中率与召回率技能上线后必须持续监控“模型有没有在正确的时机调用正确的技能”。我习惯把每轮对话的 tool_call 记录成结构化日志包含用户原始输入、意图标签、模型选择的技能名、参数快照、执行结果、耗时时长。然后按天统计几个核心指标指标计算方式预警阈值触发率实际触发技能次数 / 应当触发次数低于 90% 时查描述质量命中率命中正确技能次数 / 总触发次数低于 85% 时查技能边界定义参数有效率一次通过校验的次数 / 总调用次数低于 80% 时查参数描述执行成功率技能执行成功次数 / 总调用次数低于 95% 时查下游稳定性这个表格请收藏。实际生产里我见过太多人只看“Agent 有没有报错”却不看“Agent 做的事情是不是用户想要的”。触发率和命中率才是真正的体验指标。如果触发率低多半是技能描述没覆盖用户的表达习惯如果命中率低多半是多个技能之间的边界描述存在重叠。4.2 日志驱动描述优化做技能描述千万别靠猜。我有一个固定的优化循环收集真实失败的 prompt 样本用离线脚本重放调整 skill 描述重新测试命中率。我遇到过这样一个案例用户问“报销单到哪一步了”模型没有触发查询报销进度技能反而触发了创建报销单技能差点造成误操作。日志分析后发现技能描述里写的是“获取报销状态”而用户话术里根本没有“状态”这个词只有“到哪一步”“批没批”“进展”。在描述里补充这些口语化表达后触发率从 68% 提升到了 94%。所以技能描述不是写一次就完而是要和真实用户语料持续对齐。我把这个过程比作给搜索引擎优化关键词只不过这里“关键词”是用户会自然说的话。4.3 常见故障排查速查表把我在踩坑路上遇过的问题整理成一张表方便你快速对照问题现象可能原因排查步骤修复方案模型明明看到了技能却不调用描述与用户表达不匹配或技能数量太多被淹没检查日志里注入的技能列表人工测试不同说法优化描述按场景缩减技能子集调了错误技能多个技能描述边界重叠模型区分不了把相似技能的 description 放一起对比找雷同部分明确正向使用场景和负向排除场景参数值为空或乱写参数描述缺失或反馈层未提供纠错机会查看失败样本中模型生成的参数加强参数格式说明增加业务校验返回可修正的错误信息技能执行结果过时没有考虑到数据时效性检查日志中技能调用时间与数据返回时间差在技能内做缓存策略或让技能感知时间上下文恶意内容注入用户用 prompt 改写试图控制技能行为在调用外部接口前加权限校验分离用户输入与系统指令技能入参白名单化技能循环调用停不下来模型反复调用同一个失败技能在调度层统计单轮调用次数超过 3 次强制转人工或切换其他技能补充一个安全上的硬要求对高风险技能删除、转账、审批、发消息必须叠加用户确认机制且系统指令和用户输入要隔离存储。我在反馈层设计时会特意把“模型建议动作”和“用户确认动作”区分开防止恶意指令通过自然语言注入技能参数。这个话题展开很大但基本原则就一句话技能只能做用户授权范围内的事一旦涉及不可逆操作必须让用户明确确认。5. 实测体会调好Agent技能的几个真正的坑在最后收尾前我想纯粹用个人体会讲几个坑。这些内容不写在任何官方文档里也不在框架的 README 里但每一个都让我付出过代价。第一个坑是技能太好反而容易过度触发。早期我做技能生怕模型看不明白把描述写得极其详细把各种边界场景都写了进去。结果发现只要用户提到一点相关词模型就倾向于触发。后来我做了减法把不相关的场景明确写成“不要用于”效果反而好了。这给我的经验是描述既要做加法也要做减法边界比范围更重要。第二个坑是技能数量与上下文的权衡。技能系统接入的 Agent 数量越大模型需要携带的技能描述越多上下文越长推理速度越慢。为了塞下更多技能强行压缩描述会损害触发准确率。我最后拿出来的方案是按业务域拆分子 Agent每个子 Agent 只挂载自己领域内的技能再用上层的路由 Agent 统一分发。这是一笔很划算的治理投资。第三个坑是反馈层设计比执行层更值钱。技能执行成功只是完成了 30% 的工作剩余 70% 在于怎么把结果表述给模型和用户。我一开始直接把 API 的完整 JSON 抛回去模型经常输出一堆用户根本看不懂的字段名。重写反馈层让技能主动“总结结论”之后用户满意度有了非常直观的提升。第四个坑是不要让技能偷偷改变系统状态。查询技能就只做查询不要顺手写日志、改缓存、更新状态。状态变更必须是显式的。否则一旦模型调用频率异常你很难从技能日志里定位到底是谁改变了数据。关于这个技能系统的后续扩展我现在在往两个方向走。一个是技能的评测集建设把真实用户问题组织成回归测试集每次改技能描述后自动跑一遍命中率防止优化一个技能拖垮另一个技能。另一个是技能复用市场把企业内部已经沉淀的优质技能抽象成标准化模块新项目直接引用避免重复开发。这套打法让我自己团队的交付效率提升了不少如果你也在搭建 Agent 技能体系建议从小处着手先把一个场景的技能做精再复制到更多场景。做技能系统最忌讳的就是一上来就铺很大结果每个技能都是半吊子。