1. 为什么 Agent 需要一套技能而不是让模型自由发挥我接手过不少智能体项目有一个现象特别普遍demo 阶段看起来很惊艳什么问题都能答可一旦接到真实业务里就原形毕露。问它今天天气它能编一个让它查个数据库SQL 写出来运行就报错让它按固定格式输出报表十次里有八次格式对不上。原因其实不复杂——语言模型本身是个通才但通才不等于靠谱的执行者。模型的知识是静态的它不知道你们公司的接口长什么样不知道你本地有哪些工具也不知道查一下销售数据这句话背后到底对应哪条 SQL、哪个数据源。这时候就该技能登场了。所谓 agent-skills本质上是把模型不擅长、但业务里反复要做的那些事固化成标准化的执行单元。每个技能封装了三样东西模型该怎么理解任务指令、该调用什么工具工具集、以及怎样算干成了验证逻辑。我打过一个比方模型是刚入职的实习生脑子快、悟性好但什么都不懂技能就是老员工总结好的工作手册——遇到什么情况翻哪一页调用哪个系统输出格式是什么遇到异常找谁。没有手册实习生只能瞎猜有了手册他才能稳定交付。这套思路和我早期做的 workflow 编排系统有本质区别。workflow 是把整条链路硬编码模型只能在节点里做填空技能则是把一个较小的任务单元交给模型自主完成给它边界、给它工具、给它验收标准至于中间怎么走模型自己决定。一个是流水线上拧螺丝的机械臂一个是拿着工具箱的熟练工。后者在面对真实世界的变化时鲁棒性高得多。如果你正在做 Agent 应用尤其是要接到真实业务里用的 Agent我的建议是尽早引入技能化设计。不要指望靠堆 prompt 让模型变靠谱也不要一上来就奔着全自动编排去。先把高频动作拆出来做成技能再让 Agent 去组合这些技能。这套思路适合各类基于大模型构建的应用比如客服机器人、数据分析助手、自动化运维工具、个人知识库问答系统。凡是任务边界清晰、执行路径多样、需要调用外部工具的场景都值得用技能化方案重做一遍。2. 从任务拆解到技能落地完整走一遍四步流程有了技能化的意识下一步就是动手。我在多个项目里反复打磨过技能落地流程最终稳定下来一套四步法拆任务、定契约、写实现、挂注册。前两步决定技能设计得对不对后两步决定技能跑得稳不稳。任何一步偷懒后面都会在线上环境里还债。2.1 拆任务用目标树找到真正的技能粒度拆任务是整个环节里最考验经验的一步。拆粗了技能内部逻辑太复杂模型在一个技能里要决策太多事准确率直线下降拆细了技能数量爆炸Agent 选择技能时本身就变成了一场豪赌每次调用都有选错的风险。我常用目标树来拆。从用户意图出发逐层往下问完成这个目标必须做到哪几件事。举一个实际例子要给业务方做一个经营周报自动生成的 Agent。从目标出发至少拆出四个子目标拉取数据、分析异常、生成结论、排版输出。这四个子目标里拉取数据还可以再往下拆——查订单表、查用户表、查退款表但一般到第四层我就停了因为再往下就成了单纯的工具调用没必要再包一层技能壳。技能粒度的判断标准我总结成一句话一个技能应该能让模型在一次思考循环内完成。所谓一次思考循环就是看到任务-理解-决定调什么工具-执行-拿到结果-判断是否完成这一个完整过程。如果模型需要在这中间做多次大方向的判断说明技能拆粗了。比如生成周报是粗粒度技能模型要先想数据从哪来、再想怎么分析、再想如何排版中间任何一步都可能出错而查询订单汇总是细粒度技能任务边界一目了然。2.2 定契约输入输出是最重要的接口设计技能的输入输出契约比技能内部实现重要得多。我见过太多人把精力花在优化技能内部 prompt 上结果技能的输入描述写得含糊导致模型根本不知道该传什么参数进来。一份合格的技能契约至少要包含技能名称、一句话描述、输入参数列表、输出结构约定。其中一句话描述是给模型看的重要线索它决定了模型在什么场景下会想起调用这个技能。我见过一个反例团队做了个查询天气的技能描述写的是获取某地区的天气信息结果模型在用户问明天去杭州穿什么衣服时完全没意识到该调用它。后来把描述改成获取指定城市未来若干天的天气预报用于出行建议、穿衣推荐、活动安排等场景调用率立刻上去了。技能描述要让模型对得上号不是写给人看的文档而是写给模型看的检索索引。输出结构同样要严格定义。我坚持所有技能返回统一封装的 JSON 结构哪怕内部实现可能调用了五花八门的 API。这样做的好处是Agent 上层逻辑可以用同一套解析器处理所有技能的输出不用为每个技能单独写解析逻辑。输出结构里一定包含状态字段、业务数据字段、错误信息字段。状态字段区分成功、失败、部分成功业务数据字段放真正有用的结果错误信息字段必须有人类可读的描述——这对后面的排查至关重要。2.3 写实现prompt、工具、验证三条腿走路技能内部实现通常由三部分组成指令模板、工具声明、验证逻辑。指令模板不是简单把需求写清楚它要解决三个问题告诉模型这个技能的边界哪些事能做、哪些事不做、提供领域知识比如业务术语、数据字典、规定推理路径先做什么后做什么。写指令模板时有个心态要摆正你是在给模型写操作手册不是写需求文档。需求文档描述要什么操作手册描述怎么做。工具声明则是给模型提供可用的工具清单。以我的经验工具不是越多越好。模型在工具选择上远没有我们想象的聪明给它 20 个工具它反而不知道选哪个经常出现工具调用错误的情况。宁可让每个技能只挂 3 到 5 个最核心的工具把那些不常用的工具通过调用另一个技能的方式间接实现。验证逻辑是最容易被新手忽略的部分。技能执行完模型告诉你说成功了你怎么知道是真成功了所以每个技能的末尾都必须有一段自动检查比如调用数据库返回的行数和预期是否一致、生成的文件是否真的存在、写入的数据能否查回。验证逻辑应该能拦截至少 80% 的假成功情况。我见过一个数据同步技能模型自信地返回同步完成结果因为目标库表结构变动数据根本没写进去但模型拿到的是旧版接口的成功响应就直接照抄了。加一道验证查一下目标表的行数立刻就能发现问题。2.4 挂注册让 Agent 能发现你而不是你去找 Agent最后一步是把技能挂载到 Agent 的技能注册表里。注册表的作用类似于服务发现机制——Agent 启动时读取注册表把所有可用技能的描述加载进上下文运行中根据用户请求动态选择技能。注册表的基本单位是技能描述字典我推荐这种结构{ name: query_daily_revenue, description: 查询指定日期范围内各门店的营收汇总用于经营分析、周报生成、异常监控等场景返回按日聚合的营收金额与订单量, arguments: { type: object, properties: { start_date: {type: string, format: date}, end_date: {type: string, format: date}, store_ids: {type: array, items: {type: string}} }, required: [start_date, end_date] } }字段都很好懂唯一要提醒的是 name 的命名规则。技能命名建议用动词开头的英文蛇形命名比如query_daily_revenue、send_slack_message、generate_markdown_report。命名规则要一致否则模型在生成工具调用参数时容易混淆。注册的时候还要注意一个细节技能描述里不要塞太多细节。注册表里只有描述没有内部指令和实现。内部指令是在模型决定调用技能之后才由技能执行器注入到上下文里的。如果一开始就把所有技能的完整指令都塞给模型上下文窗口很快就会被撑爆模型也会被海量信息干扰。3. 技能库工程化设计的几个关键决策存储、调度与上下文裁剪当技能数量从 5 个涨到 50 个你会突然发现问题从怎么写技能变成了怎么管技能。这就像家里东西少的时候不需要收纳东西多了之后收纳方案决定了生活质量。技能库的工程化设计我重点说三个决策点存储结构怎么设计、动态调度怎么选、上下文怎么裁剪。3.1 存储结构文件优先数据库后置技能怎么存储很多人第一反应是放进数据库但我的建议是前期优先用文件目录。每个技能一个目录目录下放skill.py实现逻辑、prompt.md指令模板、requirements.txt依赖包、tests/测试用例。这样做的好处有三个支持版本管理、部署简单、调试方便。技能本身就是代码理应跟代码一样走 Git 管理评审、回溯、多分支开发全都顺理成章。目录结构长这样skills/ ├── core/ │ ├── base.py │ ├── registry.py │ └── executor.py ├── builtin/ │ ├── web_search/ │ │ ├── __init__.py │ │ ├── prompt.md │ │ ├── skill.py │ │ └── test_web_search.py │ └── code_interpreter/ │ ├── __init__.py │ ├── prompt.md │ ├── skill.py │ └── requirements.txt └── custom/ └── query_revenue/ ├── __init__.py ├── prompt.md └── skill.py等到技能数量真的多到文件检索成了瓶颈、或者需要做技能权限控制和多人协作时再考虑把技能元数据搬到数据库里。但即便那时技能的执行逻辑代码也仍然建议留在文件系统里数据库只存索引和描述信息。3.2 动态调度什么时候靠模型选什么时候靠规则路由技能调度的核心问题是用户请求来了到底让 Agent 自己选技能还是用规则直接路由到某个技能我的结论是分场景分阶段。初期技能不超过 20 个的时候我强烈建议让模型自主选。模型选技能的过程本质上是一次意图识别加工具选择现代模型做这件事的准确率其实相当高只要技能描述写得好。而且这样最灵活用户可以任意组合多个技能完成一个复杂任务。但当业务场景已经非常明确、用户请求路径基本固定时就应该用规则路由前置兜底。比如在我的内部工具里所有以/report开头的用户消息直接路由到周报技能组不再让模型选择。这样做的原因很实际减少一次大模型消耗、避免选错风险、响应速度更快。规则路由和模型选择的边界我一般从两个维度判断——请求是否高频且模式固定以及误选造成的代价是否大。两者任一成立就值得上规则路由。更稳妥的方案是规则优先、模型兜底的混合模式。请求进来先尝试规则匹配匹配不到再交给模型做技能选择。这相当于给技能调度上了一道保险丝。3.3 上下文裁剪只让模型看到该看的东西这是技能库设计里最容易被低估的问题。当你给 Agent 挂了 50 个技能每个技能的注册描述就算只有 200 字总数也会达到 1 万字加上系统提示词、对话历史、工具返回结果几个来回下来上下文就爆了。上下文裁剪的核心思路是分层加载。第一层是常驻的只放全局指令和少量基础技能描述第二层是候选的根据用户当前意图筛选出可能的技能子集把描述加载进来第三层是动态注入的模型决定调用某个技能后才把该技能的完整指令模板、工具清单加载进来。这个分层设计可以做一个简单的技能匹配器把技能描述和用户当前请求同时做嵌入向量化用向量相似度找出 Top-K 个候选技能。K 我一般取 5 到 8。这个方案不完美但实用性很高指令覆盖的风险远低于把所有技能一股脑塞给模型。3.4 技能执行器与超时控制技能如果同步执行一旦某个技能内部调用的外部 API 卡住整个 Agent 就挂在那里空转。所以技能执行器必须内置超时机制。我在设计执行器时对技能执行的每一层都设置了超时工具调用层、验证层、指令拼接层。外层超时通常设为 30 秒内部工具调用超时设为 10 秒。超时之后怎么办不是简单返回超时错误而是要让模型有一定恢复能力。我尝试过的最小可行方案是捕获超时异常把错误信息重新注入上下文让模型决定是换一个技能还是换一个工具参数重试。注意这里给模型重试机会的次数要限制最多 2 次否则模型会在同一个坑里反复打转。class SkillExecutor: def __init__(self, timeout30): self.timeout timeout def execute(self, skill, args): try: return asyncio.wait_for(skill.run(args), timeoutself.timeout) except asyncio.TimeoutError: suggestion { status: error, error: f技能 {skill.name} 执行超时{self.timeout}s, suggestion: 尝试换用其他技能或调整参数后重新执行 } return suggestion这套执行器虽然简单但在线上环境扛住了很多异常场景。核心思路就是技能执行结果永远是一条结构化消息成功时有数据失败时有建议模型拿到这条消息后能继续往下走而不是卡死。4. 技能失效的真实案例与完整排查链路技能写完、上线、跑起来一切看起来都很顺。但用不了多久你就会发现技能失效的场景五花八门而且多数失效不是代码 bug而是模型行为偏离预期。这一章我挑三个真实踩过的坑完整还原排查链路你可以直接借鉴这个排查思路。4.1 案例一技能描述信息不够模型绕过了它第一个案例是我做的库存查询技能。上线后通过日志发现用户在问这个商品还有货吗时模型根本没有调用库存技能而是凭空编造了一个库存数字出来。排查链路是这样的先翻对话日志确认模型确实没有发起工具调用然后看技能描述发现描述里写的是查询指定商品在指定仓库的库存数量而用户的问题是这个商品还有货吗——库存和有货之间模型没有建立起对应关系。修复方案是在技能描述里增加常见问法别名当用户询问是否有货、剩余数量、可售数量、库存数量时均使用本技能。同时把技能名称从query_stock_level改成更贴近用户语言的check_product_availability。改完之后调用率从 40% 涨到了 80%。从这次踩坑得到的经验是技能的调用率首先取决于模型的语义理解语义匹配度不够高再好的实现也白搭。4.2 案例二工具参数校验缺失模型传了非法输入第二个案例更隐蔽。一个生成报表的技能内部调用了一个第三方 PDF 渲染接口模型在传参数时给了负数页数接口直接 500。诡异的是技能没有报错因为技能内部只检查了接口返回码 200 才认为成功500 被当作非成功处理但错误信息没有透传模型收到的是一条泛化的工具调用失败。排查链路是先从执行器日志看到技能最终返回了工具调用失败但没有具体原因然后单独复现第三方接口调用发现是负数页数导致参数校验失败最后回到技能定义发现page_size参数缺少最小值校验模型的参数约束全靠 Chat Completions API 的 JSON Schema 声明而声明里只写了 integer 类型没写 minimum 约束。修复就是补上最小值和最大值约束并在技能内部对所有工具调用增加一层显式参数校验。这次教训让我养成了一个习惯任何技能的对外输入都必须在自己的代码里再校验一遍绝不盲目信任模型的输出。4.3 案例三外部依赖变了技能还在按旧逻辑干活第三个案例是不定期的隐性失效。一个定时抓取第三方网站数据的技能连续几周输出都是空的但技能状态一直是成功。排查过程比较曲折先看技能验证逻辑发现它只用HTTP 200判断抓取成功而目标网站改版后200 返回的页面里已经没有数据字段了再看解析逻辑发现解析规则还是旧版选择器匹配不到任何元素返回空列表。这个案例暴露出的核心问题是验证逻辑只验证了请求成功没验证数据有效。后来我修改了验证逻辑新增一条规则——如果解析结果为空且连续出现多次自动把技能状态标记为异常并触发告警。同时把外部依赖的变化纳入监控定期检查目标页面结构与解析规则的匹配度。对于任何技能如果它依赖外部系统一定要思考外部系统变了技能怎么感知到。我的排查思路可以沉淀为一套实用的方法论当你遇到技能失效时按以下顺序检查先看日志里模型有没有调用技能没调用是语义匹配问题调用了但结果不对看技能内部有没有异常被吞掉异常处理正常但数据仍旧不对把验证逻辑打开看验证什么。按照这个链路走完80% 的问题都能定位。5. 技能的评测与持续迭代不回归就等着翻车我在很长一段时间里都是写完技能就上线直到被现实狠狠教训过一次。那次我给一个查询技能升级了新版本手工测了几个 case 感觉没问题结果上线后发现一个老功能挂了——新版本改坏了旧逻辑。从那时起我意识到技能也需要像软件工程一样建立评测集、做回归测试。5.1 怎么构造一份靠谱的技能评测集评测集不能靠拍脑袋写几个问题它需要覆盖技能的典型场景、边界场景和异常场景。以查询营收的技能为例场景类型测试用例示例期望指标正常场景查询本月各门店营收返回非空数据格式正确边界场景查询未来日期数据返回无数据而非报错边界场景查询一年前的历史数据能返回结果或明确提示数据范围异常场景传入非法门店 ID返回错误信息且不崩溃组合场景昨天到今天的数据对比时间筛选条件正确生效评测集里的每个用例都要预先标注期望的输出特征不一定是一个精确值但必须是可以自动判断的断言比如返回数据条数大于 0状态字段为 success包含 store_id 字段。有了断言评测才能自动化才能进 CI/CD 流程。5.2 回归测试的自动化和准入准出标准技能的回归测试最好是全自动的。每次技能迭代跑一遍完整评测集用通过率来判断能不能上线。以我的标准核心技能的通过率要高于 90%非核心技能也要高于 80%。低于这个线说明这次改动引入的回归太大需要重新调整。自动化回归有个现实问题调用大模型有成本、有延迟。所以评测集不一定要全量跑可以分两级。第一级是冒烟集20 个核心用例每次提交代码都跑控制在 1 分钟以内第二级是完整集跑全部用例每天晚上跑一次第二天早上看报告。这样既保证了及时性又控制了成本。我还建议把评测结果和技能版本号关联起来。每次技能更新后能直接看到这个版本在评测集上的通过率曲线是提升了还是恶化了。如果你的技能偶尔会表现不稳定同样的用例有时通过有时不通过那就需要找出那些偶发失败的用例分析是模型扰动导致的还是外部依赖抖动导致的。5.3 迭代节奏什么时候该重构技能什么时候该新建技能最后聊一下技能的演进。技能库不是一成不变的随着业务发展你会不断面对该改旧技能还是该写新技能的抉择。我的判断标准有三条如果旧技能里塞进了太多互不相关的任务拆成多个技能如果多个技能之间有大量重复逻辑抽一个公共技能如果旧技能描述怎么改都很难被模型正确调用重新设计它而不是在旧结构上打补丁。尤其要警惕技能膨胀。我在一个项目里见过 300 多个技能其中一半以上是可以被合并的变体。技能库过于庞杂直接影响模型选技能的准确率因为候选集太大、描述差异化不够模型很容易在相似的技能之间犹豫或选错。定期的技能梳理是件必要的工作我一般是每月做一次用调用频率和描述相似度两个维度来排查调用频率极低的技能退回开发库描述相似度高于 0.75 的技能组重新合并设计。6. 从单体 Agent 到技能网络复用与协作的真正价值技能化走到最后你会获得一个意想不到的收益——技能可以在多个 Agent 之间复用甚至跨项目复用。这件事的想象空间比单个 Agent 的可用性提升大得多。6.1 技能的三个抽象层级我把技能分成三层原子技能、组合技能、业务技能。原子技能是最小执行单元比如发送邮件查询数据库调用外部 API通用性最强任意项目都能用。组合技能是几个原子技能按特定路径编排比如生成周报等于查询数据 分析异常 生成正文 渲染 PDF这种技能在不同项目之间也能复用只要业务逻辑相同。业务技能则和具体业务强绑定比如计算跨境电商平台的税费这类技能复用范围窄但价值最高。设计技能时要有意识地划分层级。不要一上来就写业务技能先沉淀原子技能。原子技能复用得越多后续组合技能的开发成本越低。我现在的习惯是维护一个私人技能模板库所有项目的技能都从这个库里派生。6.2 多 Agent 协作里的技能共享机制在一个大型系统里跑多个 Agent 时技能共享就更关键。我的做法是技能仓库独立部署所有 Agent 都从同一个技能注册中心拉取技能元数据而不是各自在自己本地维护一套。这样做让每个 Agent 可以按需加载自己需要的技能子集。比如客服 Agent 加载订单查询、退换货处理、物流跟踪这些技能运营 Agent 加载报表生成、用户分群、活动效果分析这些技能。两个 Agent 的技能集合有重叠但各自只加载一部分。技能实体的升级只需要发布一次所有引用了该技能的 Agent 下次调用时就自动用上了新版本不用逐个改。但共享也带来了新的问题技能变更影响面扩大。以前一个技能只服务一个 Agent改坏了只影响一个现在技能仓库里的技能被多个 Agent 引用一次不谨慎的发布可能导致全线崩溃。所以技能发布必须带上版本号和向后兼容策略。我把技能的接口变更分成两类兼容性变更只改内部实现、指令模板对外契约不变和平级变更修改了输入输出结构。兼容性变更走标准发布流程平级变更要检查所有引用方同步修改后才能发布。这个检查不建议手工做在技能注册中心建立一个引用关系图发布时自动提示受影响范围。6.3 构建技能的职业发展视角从个人发展角度看投入时间去打磨一套技能库其实是在积累一种可以复用的职业资本。你写过的最好的那几个技能换个项目、换个公司照样能用顶多改改接口参数。这套方法论本身也是通用的——任何用大模型做应用的人都会面临同样的问题模型不听话、任务不稳定、外部依赖多变。技能化不是银弹但它是目前我看到的最靠谱的工程化手段。6.4 最后分享一次实操中的体会回到 agent-skills 这件事本身如果让我最后总结一句我会说别把它想得太玄技能就是把那些你希望模型稳定做好的事情给它一个确定的边界和路径。模型负责聪明你负责让它不犯错。技能库的建设不需要一步到位你可以先从两三个最高频、最痛的任务开始跑通流程再逐步扩充。但有几个习惯建议你从第一个技能就养成描述写仔细、验证不偷懒、评测出了就坚持跑。这几件事做得越早后面还的债越少。我现在每接手一个新项目第一件事就是问业务方哪三件事最需要稳定输出然后先把这三件事做成技能。等这三件立住了再往四面延展。这不是最炫酷的做法但一定是最扎实的路径。 Agent技能化：从任务拆解到工程落地的完整指南
1. 为什么 Agent 需要一套技能而不是让模型自由发挥我接手过不少智能体项目有一个现象特别普遍demo 阶段看起来很惊艳什么问题都能答可一旦接到真实业务里就原形毕露。问它今天天气它能编一个让它查个数据库SQL 写出来运行就报错让它按固定格式输出报表十次里有八次格式对不上。原因其实不复杂——语言模型本身是个通才但通才不等于靠谱的执行者。模型的知识是静态的它不知道你们公司的接口长什么样不知道你本地有哪些工具也不知道查一下销售数据这句话背后到底对应哪条 SQL、哪个数据源。这时候就该技能登场了。所谓 agent-skills本质上是把模型不擅长、但业务里反复要做的那些事固化成标准化的执行单元。每个技能封装了三样东西模型该怎么理解任务指令、该调用什么工具工具集、以及怎样算干成了验证逻辑。我打过一个比方模型是刚入职的实习生脑子快、悟性好但什么都不懂技能就是老员工总结好的工作手册——遇到什么情况翻哪一页调用哪个系统输出格式是什么遇到异常找谁。没有手册实习生只能瞎猜有了手册他才能稳定交付。这套思路和我早期做的 workflow 编排系统有本质区别。workflow 是把整条链路硬编码模型只能在节点里做填空技能则是把一个较小的任务单元交给模型自主完成给它边界、给它工具、给它验收标准至于中间怎么走模型自己决定。一个是流水线上拧螺丝的机械臂一个是拿着工具箱的熟练工。后者在面对真实世界的变化时鲁棒性高得多。如果你正在做 Agent 应用尤其是要接到真实业务里用的 Agent我的建议是尽早引入技能化设计。不要指望靠堆 prompt 让模型变靠谱也不要一上来就奔着全自动编排去。先把高频动作拆出来做成技能再让 Agent 去组合这些技能。这套思路适合各类基于大模型构建的应用比如客服机器人、数据分析助手、自动化运维工具、个人知识库问答系统。凡是任务边界清晰、执行路径多样、需要调用外部工具的场景都值得用技能化方案重做一遍。2. 从任务拆解到技能落地完整走一遍四步流程有了技能化的意识下一步就是动手。我在多个项目里反复打磨过技能落地流程最终稳定下来一套四步法拆任务、定契约、写实现、挂注册。前两步决定技能设计得对不对后两步决定技能跑得稳不稳。任何一步偷懒后面都会在线上环境里还债。2.1 拆任务用目标树找到真正的技能粒度拆任务是整个环节里最考验经验的一步。拆粗了技能内部逻辑太复杂模型在一个技能里要决策太多事准确率直线下降拆细了技能数量爆炸Agent 选择技能时本身就变成了一场豪赌每次调用都有选错的风险。我常用目标树来拆。从用户意图出发逐层往下问完成这个目标必须做到哪几件事。举一个实际例子要给业务方做一个经营周报自动生成的 Agent。从目标出发至少拆出四个子目标拉取数据、分析异常、生成结论、排版输出。这四个子目标里拉取数据还可以再往下拆——查订单表、查用户表、查退款表但一般到第四层我就停了因为再往下就成了单纯的工具调用没必要再包一层技能壳。技能粒度的判断标准我总结成一句话一个技能应该能让模型在一次思考循环内完成。所谓一次思考循环就是看到任务-理解-决定调什么工具-执行-拿到结果-判断是否完成这一个完整过程。如果模型需要在这中间做多次大方向的判断说明技能拆粗了。比如生成周报是粗粒度技能模型要先想数据从哪来、再想怎么分析、再想如何排版中间任何一步都可能出错而查询订单汇总是细粒度技能任务边界一目了然。2.2 定契约输入输出是最重要的接口设计技能的输入输出契约比技能内部实现重要得多。我见过太多人把精力花在优化技能内部 prompt 上结果技能的输入描述写得含糊导致模型根本不知道该传什么参数进来。一份合格的技能契约至少要包含技能名称、一句话描述、输入参数列表、输出结构约定。其中一句话描述是给模型看的重要线索它决定了模型在什么场景下会想起调用这个技能。我见过一个反例团队做了个查询天气的技能描述写的是获取某地区的天气信息结果模型在用户问明天去杭州穿什么衣服时完全没意识到该调用它。后来把描述改成获取指定城市未来若干天的天气预报用于出行建议、穿衣推荐、活动安排等场景调用率立刻上去了。技能描述要让模型对得上号不是写给人看的文档而是写给模型看的检索索引。输出结构同样要严格定义。我坚持所有技能返回统一封装的 JSON 结构哪怕内部实现可能调用了五花八门的 API。这样做的好处是Agent 上层逻辑可以用同一套解析器处理所有技能的输出不用为每个技能单独写解析逻辑。输出结构里一定包含状态字段、业务数据字段、错误信息字段。状态字段区分成功、失败、部分成功业务数据字段放真正有用的结果错误信息字段必须有人类可读的描述——这对后面的排查至关重要。2.3 写实现prompt、工具、验证三条腿走路技能内部实现通常由三部分组成指令模板、工具声明、验证逻辑。指令模板不是简单把需求写清楚它要解决三个问题告诉模型这个技能的边界哪些事能做、哪些事不做、提供领域知识比如业务术语、数据字典、规定推理路径先做什么后做什么。写指令模板时有个心态要摆正你是在给模型写操作手册不是写需求文档。需求文档描述要什么操作手册描述怎么做。工具声明则是给模型提供可用的工具清单。以我的经验工具不是越多越好。模型在工具选择上远没有我们想象的聪明给它 20 个工具它反而不知道选哪个经常出现工具调用错误的情况。宁可让每个技能只挂 3 到 5 个最核心的工具把那些不常用的工具通过调用另一个技能的方式间接实现。验证逻辑是最容易被新手忽略的部分。技能执行完模型告诉你说成功了你怎么知道是真成功了所以每个技能的末尾都必须有一段自动检查比如调用数据库返回的行数和预期是否一致、生成的文件是否真的存在、写入的数据能否查回。验证逻辑应该能拦截至少 80% 的假成功情况。我见过一个数据同步技能模型自信地返回同步完成结果因为目标库表结构变动数据根本没写进去但模型拿到的是旧版接口的成功响应就直接照抄了。加一道验证查一下目标表的行数立刻就能发现问题。2.4 挂注册让 Agent 能发现你而不是你去找 Agent最后一步是把技能挂载到 Agent 的技能注册表里。注册表的作用类似于服务发现机制——Agent 启动时读取注册表把所有可用技能的描述加载进上下文运行中根据用户请求动态选择技能。注册表的基本单位是技能描述字典我推荐这种结构{ name: query_daily_revenue, description: 查询指定日期范围内各门店的营收汇总用于经营分析、周报生成、异常监控等场景返回按日聚合的营收金额与订单量, arguments: { type: object, properties: { start_date: {type: string, format: date}, end_date: {type: string, format: date}, store_ids: {type: array, items: {type: string}} }, required: [start_date, end_date] } }字段都很好懂唯一要提醒的是 name 的命名规则。技能命名建议用动词开头的英文蛇形命名比如query_daily_revenue、send_slack_message、generate_markdown_report。命名规则要一致否则模型在生成工具调用参数时容易混淆。注册的时候还要注意一个细节技能描述里不要塞太多细节。注册表里只有描述没有内部指令和实现。内部指令是在模型决定调用技能之后才由技能执行器注入到上下文里的。如果一开始就把所有技能的完整指令都塞给模型上下文窗口很快就会被撑爆模型也会被海量信息干扰。3. 技能库工程化设计的几个关键决策存储、调度与上下文裁剪当技能数量从 5 个涨到 50 个你会突然发现问题从怎么写技能变成了怎么管技能。这就像家里东西少的时候不需要收纳东西多了之后收纳方案决定了生活质量。技能库的工程化设计我重点说三个决策点存储结构怎么设计、动态调度怎么选、上下文怎么裁剪。3.1 存储结构文件优先数据库后置技能怎么存储很多人第一反应是放进数据库但我的建议是前期优先用文件目录。每个技能一个目录目录下放skill.py实现逻辑、prompt.md指令模板、requirements.txt依赖包、tests/测试用例。这样做的好处有三个支持版本管理、部署简单、调试方便。技能本身就是代码理应跟代码一样走 Git 管理评审、回溯、多分支开发全都顺理成章。目录结构长这样skills/ ├── core/ │ ├── base.py │ ├── registry.py │ └── executor.py ├── builtin/ │ ├── web_search/ │ │ ├── __init__.py │ │ ├── prompt.md │ │ ├── skill.py │ │ └── test_web_search.py │ └── code_interpreter/ │ ├── __init__.py │ ├── prompt.md │ ├── skill.py │ └── requirements.txt └── custom/ └── query_revenue/ ├── __init__.py ├── prompt.md └── skill.py等到技能数量真的多到文件检索成了瓶颈、或者需要做技能权限控制和多人协作时再考虑把技能元数据搬到数据库里。但即便那时技能的执行逻辑代码也仍然建议留在文件系统里数据库只存索引和描述信息。3.2 动态调度什么时候靠模型选什么时候靠规则路由技能调度的核心问题是用户请求来了到底让 Agent 自己选技能还是用规则直接路由到某个技能我的结论是分场景分阶段。初期技能不超过 20 个的时候我强烈建议让模型自主选。模型选技能的过程本质上是一次意图识别加工具选择现代模型做这件事的准确率其实相当高只要技能描述写得好。而且这样最灵活用户可以任意组合多个技能完成一个复杂任务。但当业务场景已经非常明确、用户请求路径基本固定时就应该用规则路由前置兜底。比如在我的内部工具里所有以/report开头的用户消息直接路由到周报技能组不再让模型选择。这样做的原因很实际减少一次大模型消耗、避免选错风险、响应速度更快。规则路由和模型选择的边界我一般从两个维度判断——请求是否高频且模式固定以及误选造成的代价是否大。两者任一成立就值得上规则路由。更稳妥的方案是规则优先、模型兜底的混合模式。请求进来先尝试规则匹配匹配不到再交给模型做技能选择。这相当于给技能调度上了一道保险丝。3.3 上下文裁剪只让模型看到该看的东西这是技能库设计里最容易被低估的问题。当你给 Agent 挂了 50 个技能每个技能的注册描述就算只有 200 字总数也会达到 1 万字加上系统提示词、对话历史、工具返回结果几个来回下来上下文就爆了。上下文裁剪的核心思路是分层加载。第一层是常驻的只放全局指令和少量基础技能描述第二层是候选的根据用户当前意图筛选出可能的技能子集把描述加载进来第三层是动态注入的模型决定调用某个技能后才把该技能的完整指令模板、工具清单加载进来。这个分层设计可以做一个简单的技能匹配器把技能描述和用户当前请求同时做嵌入向量化用向量相似度找出 Top-K 个候选技能。K 我一般取 5 到 8。这个方案不完美但实用性很高指令覆盖的风险远低于把所有技能一股脑塞给模型。3.4 技能执行器与超时控制技能如果同步执行一旦某个技能内部调用的外部 API 卡住整个 Agent 就挂在那里空转。所以技能执行器必须内置超时机制。我在设计执行器时对技能执行的每一层都设置了超时工具调用层、验证层、指令拼接层。外层超时通常设为 30 秒内部工具调用超时设为 10 秒。超时之后怎么办不是简单返回超时错误而是要让模型有一定恢复能力。我尝试过的最小可行方案是捕获超时异常把错误信息重新注入上下文让模型决定是换一个技能还是换一个工具参数重试。注意这里给模型重试机会的次数要限制最多 2 次否则模型会在同一个坑里反复打转。class SkillExecutor: def __init__(self, timeout30): self.timeout timeout def execute(self, skill, args): try: return asyncio.wait_for(skill.run(args), timeoutself.timeout) except asyncio.TimeoutError: suggestion { status: error, error: f技能 {skill.name} 执行超时{self.timeout}s, suggestion: 尝试换用其他技能或调整参数后重新执行 } return suggestion这套执行器虽然简单但在线上环境扛住了很多异常场景。核心思路就是技能执行结果永远是一条结构化消息成功时有数据失败时有建议模型拿到这条消息后能继续往下走而不是卡死。4. 技能失效的真实案例与完整排查链路技能写完、上线、跑起来一切看起来都很顺。但用不了多久你就会发现技能失效的场景五花八门而且多数失效不是代码 bug而是模型行为偏离预期。这一章我挑三个真实踩过的坑完整还原排查链路你可以直接借鉴这个排查思路。4.1 案例一技能描述信息不够模型绕过了它第一个案例是我做的库存查询技能。上线后通过日志发现用户在问这个商品还有货吗时模型根本没有调用库存技能而是凭空编造了一个库存数字出来。排查链路是这样的先翻对话日志确认模型确实没有发起工具调用然后看技能描述发现描述里写的是查询指定商品在指定仓库的库存数量而用户的问题是这个商品还有货吗——库存和有货之间模型没有建立起对应关系。修复方案是在技能描述里增加常见问法别名当用户询问是否有货、剩余数量、可售数量、库存数量时均使用本技能。同时把技能名称从query_stock_level改成更贴近用户语言的check_product_availability。改完之后调用率从 40% 涨到了 80%。从这次踩坑得到的经验是技能的调用率首先取决于模型的语义理解语义匹配度不够高再好的实现也白搭。4.2 案例二工具参数校验缺失模型传了非法输入第二个案例更隐蔽。一个生成报表的技能内部调用了一个第三方 PDF 渲染接口模型在传参数时给了负数页数接口直接 500。诡异的是技能没有报错因为技能内部只检查了接口返回码 200 才认为成功500 被当作非成功处理但错误信息没有透传模型收到的是一条泛化的工具调用失败。排查链路是先从执行器日志看到技能最终返回了工具调用失败但没有具体原因然后单独复现第三方接口调用发现是负数页数导致参数校验失败最后回到技能定义发现page_size参数缺少最小值校验模型的参数约束全靠 Chat Completions API 的 JSON Schema 声明而声明里只写了 integer 类型没写 minimum 约束。修复就是补上最小值和最大值约束并在技能内部对所有工具调用增加一层显式参数校验。这次教训让我养成了一个习惯任何技能的对外输入都必须在自己的代码里再校验一遍绝不盲目信任模型的输出。4.3 案例三外部依赖变了技能还在按旧逻辑干活第三个案例是不定期的隐性失效。一个定时抓取第三方网站数据的技能连续几周输出都是空的但技能状态一直是成功。排查过程比较曲折先看技能验证逻辑发现它只用HTTP 200判断抓取成功而目标网站改版后200 返回的页面里已经没有数据字段了再看解析逻辑发现解析规则还是旧版选择器匹配不到任何元素返回空列表。这个案例暴露出的核心问题是验证逻辑只验证了请求成功没验证数据有效。后来我修改了验证逻辑新增一条规则——如果解析结果为空且连续出现多次自动把技能状态标记为异常并触发告警。同时把外部依赖的变化纳入监控定期检查目标页面结构与解析规则的匹配度。对于任何技能如果它依赖外部系统一定要思考外部系统变了技能怎么感知到。我的排查思路可以沉淀为一套实用的方法论当你遇到技能失效时按以下顺序检查先看日志里模型有没有调用技能没调用是语义匹配问题调用了但结果不对看技能内部有没有异常被吞掉异常处理正常但数据仍旧不对把验证逻辑打开看验证什么。按照这个链路走完80% 的问题都能定位。5. 技能的评测与持续迭代不回归就等着翻车我在很长一段时间里都是写完技能就上线直到被现实狠狠教训过一次。那次我给一个查询技能升级了新版本手工测了几个 case 感觉没问题结果上线后发现一个老功能挂了——新版本改坏了旧逻辑。从那时起我意识到技能也需要像软件工程一样建立评测集、做回归测试。5.1 怎么构造一份靠谱的技能评测集评测集不能靠拍脑袋写几个问题它需要覆盖技能的典型场景、边界场景和异常场景。以查询营收的技能为例场景类型测试用例示例期望指标正常场景查询本月各门店营收返回非空数据格式正确边界场景查询未来日期数据返回无数据而非报错边界场景查询一年前的历史数据能返回结果或明确提示数据范围异常场景传入非法门店 ID返回错误信息且不崩溃组合场景昨天到今天的数据对比时间筛选条件正确生效评测集里的每个用例都要预先标注期望的输出特征不一定是一个精确值但必须是可以自动判断的断言比如返回数据条数大于 0状态字段为 success包含 store_id 字段。有了断言评测才能自动化才能进 CI/CD 流程。5.2 回归测试的自动化和准入准出标准技能的回归测试最好是全自动的。每次技能迭代跑一遍完整评测集用通过率来判断能不能上线。以我的标准核心技能的通过率要高于 90%非核心技能也要高于 80%。低于这个线说明这次改动引入的回归太大需要重新调整。自动化回归有个现实问题调用大模型有成本、有延迟。所以评测集不一定要全量跑可以分两级。第一级是冒烟集20 个核心用例每次提交代码都跑控制在 1 分钟以内第二级是完整集跑全部用例每天晚上跑一次第二天早上看报告。这样既保证了及时性又控制了成本。我还建议把评测结果和技能版本号关联起来。每次技能更新后能直接看到这个版本在评测集上的通过率曲线是提升了还是恶化了。如果你的技能偶尔会表现不稳定同样的用例有时通过有时不通过那就需要找出那些偶发失败的用例分析是模型扰动导致的还是外部依赖抖动导致的。5.3 迭代节奏什么时候该重构技能什么时候该新建技能最后聊一下技能的演进。技能库不是一成不变的随着业务发展你会不断面对该改旧技能还是该写新技能的抉择。我的判断标准有三条如果旧技能里塞进了太多互不相关的任务拆成多个技能如果多个技能之间有大量重复逻辑抽一个公共技能如果旧技能描述怎么改都很难被模型正确调用重新设计它而不是在旧结构上打补丁。尤其要警惕技能膨胀。我在一个项目里见过 300 多个技能其中一半以上是可以被合并的变体。技能库过于庞杂直接影响模型选技能的准确率因为候选集太大、描述差异化不够模型很容易在相似的技能之间犹豫或选错。定期的技能梳理是件必要的工作我一般是每月做一次用调用频率和描述相似度两个维度来排查调用频率极低的技能退回开发库描述相似度高于 0.75 的技能组重新合并设计。6. 从单体 Agent 到技能网络复用与协作的真正价值技能化走到最后你会获得一个意想不到的收益——技能可以在多个 Agent 之间复用甚至跨项目复用。这件事的想象空间比单个 Agent 的可用性提升大得多。6.1 技能的三个抽象层级我把技能分成三层原子技能、组合技能、业务技能。原子技能是最小执行单元比如发送邮件查询数据库调用外部 API通用性最强任意项目都能用。组合技能是几个原子技能按特定路径编排比如生成周报等于查询数据 分析异常 生成正文 渲染 PDF这种技能在不同项目之间也能复用只要业务逻辑相同。业务技能则和具体业务强绑定比如计算跨境电商平台的税费这类技能复用范围窄但价值最高。设计技能时要有意识地划分层级。不要一上来就写业务技能先沉淀原子技能。原子技能复用得越多后续组合技能的开发成本越低。我现在的习惯是维护一个私人技能模板库所有项目的技能都从这个库里派生。6.2 多 Agent 协作里的技能共享机制在一个大型系统里跑多个 Agent 时技能共享就更关键。我的做法是技能仓库独立部署所有 Agent 都从同一个技能注册中心拉取技能元数据而不是各自在自己本地维护一套。这样做让每个 Agent 可以按需加载自己需要的技能子集。比如客服 Agent 加载订单查询、退换货处理、物流跟踪这些技能运营 Agent 加载报表生成、用户分群、活动效果分析这些技能。两个 Agent 的技能集合有重叠但各自只加载一部分。技能实体的升级只需要发布一次所有引用了该技能的 Agent 下次调用时就自动用上了新版本不用逐个改。但共享也带来了新的问题技能变更影响面扩大。以前一个技能只服务一个 Agent改坏了只影响一个现在技能仓库里的技能被多个 Agent 引用一次不谨慎的发布可能导致全线崩溃。所以技能发布必须带上版本号和向后兼容策略。我把技能的接口变更分成两类兼容性变更只改内部实现、指令模板对外契约不变和平级变更修改了输入输出结构。兼容性变更走标准发布流程平级变更要检查所有引用方同步修改后才能发布。这个检查不建议手工做在技能注册中心建立一个引用关系图发布时自动提示受影响范围。6.3 构建技能的职业发展视角从个人发展角度看投入时间去打磨一套技能库其实是在积累一种可以复用的职业资本。你写过的最好的那几个技能换个项目、换个公司照样能用顶多改改接口参数。这套方法论本身也是通用的——任何用大模型做应用的人都会面临同样的问题模型不听话、任务不稳定、外部依赖多变。技能化不是银弹但它是目前我看到的最靠谱的工程化手段。6.4 最后分享一次实操中的体会回到 agent-skills 这件事本身如果让我最后总结一句我会说别把它想得太玄技能就是把那些你希望模型稳定做好的事情给它一个确定的边界和路径。模型负责聪明你负责让它不犯错。技能库的建设不需要一步到位你可以先从两三个最高频、最痛的任务开始跑通流程再逐步扩充。但有几个习惯建议你从第一个技能就养成描述写仔细、验证不偷懒、评测出了就坚持跑。这几件事做得越早后面还的债越少。我现在每接手一个新项目第一件事就是问业务方哪三件事最需要稳定输出然后先把这三件事做成技能。等这三件立住了再往四面延展。这不是最炫酷的做法但一定是最扎实的路径。