决定一个 AI Agent 好不好用的说实话早就不是模型智商了而是它手上到底有多少靠谱的“技能”。我去年维护了一个名叫 agent-skills 的技能库把同一套任务分别用纯提示词和技能化方式实现了一版效果差距大得离谱。所谓 agent-skills说白了就是把“让模型记住怎么做”变成“让模型知道有哪些技能可用、每个技能怎么被调用、调用结果怎么落回上下文”。这篇文章不聊虚的概念我会直接分享我搭建这套技能体系时踩过的坑、沉淀下来的设计套路以及实测中真正管用的调试方法。如果你正在做 AI 应用落地或者想让现有的助手能稳定干活而不是动不动一本正经地胡说这篇值得看完。1. 为什么 Agent 需要“技能化”而不是一堆提示词1.1 技能和提示词的本质区别很多人问过我一个问题我已经在系统提示词里写清楚了“当你需要查天气时就调用 /weather 接口”为什么 Agent 还是经常不按套路出牌这个问题的答案恰恰是理解 agent-skills 的关键。如果把大模型当成一个刚入职的实习生提示词就是领导的“口头交代”大概说清楚方向但具体步骤、边界条件、异常怎么处理全靠临时发挥。而技能相当于一张标准操作卡上面明确写了输入要什么格式、输出返回什么结构、什么情况不能碰、失败了怎么收场。举个我实际遇到的例子。早期我在系统提示词里塞了一段话“用户想了解股票行情时调用get_stock_price(symbol)返回最新价格。”听起来很清楚对吧实际运行中模型经常犯三种错一是用户说“帮我看看最近板块走势”模型也调用了这个接口二是接口需要“600519.SH”这种带交易所后缀的代码模型却传了“贵州茅台”四个字三是接口超时或者返回空数据时模型直接编了一个价格出来告诉用户。这就是纯提示词方案的天然缺陷它只有“意图”没有“约束”模型每一步都在自由发挥。技能化解决的就是这个问题。一个技能至少包含四样东西能被模型理解的描述、严格的输入参数定义、确定性的执行逻辑、结构化的输出格式。以查股票为例技能描述里会写“仅用于查询A股个股最新行情不适用于指数、板块、基金用户给出股票名称时请先转换为标准代码”输入参数是枚举约束的字符串必须符合交易所代码规则输出统一是{status, data, error_code, retryable}结构。模型不再“背命令”它只是在一个定义好的技能列表里做选择选完了由执行系统保证动作的正确性。这就是技能和提示词最本质的差别提示词靠模型自觉技能靠系统约束。1.2 技能化带来的三个直接收益第一个收益是可复用。一个write_meeting_summary技能写好后可以用在会议助手、周报生成器、项目复盘机器人等多个场景里不需要每次重新写长提示词也不会因为提示词越改越长而出现“改一处坏一片”的连锁反应。我现在的做法是技能独立成文件哪个场景需要就引入哪个业务代码和提示词都清爽很多。第二个收益是可测试。技能是黑盒输入固定输出结构固定我可以单独准备一批测试样本每天跑一遍回归看触发准确率和参数解析正确率有没有下降。这在纯提示词时代是很难想象的因为你没法对一段描述做单元测试。技能化之后“这个技能描述改了会不会误触发”变成了一个可以量化的问题每次发布前跑一次回归就心中有数。第三个收益是可观测。Agent 调用了哪些技能、每个技能花了多少毫秒、传入了什么参数、返回了什么结果全部可以记录成结构化日志。一旦出问题顺着调用链就能定位是模型选错了技能、参数没传对还是外部接口挂了。这种透明度对生产环境太重要了我后面第五章会展开讲具体的排查方法。2. 一份好技能清单长什么样核心字段与设计思路2.1 技能的基本字段与命名规范我维护的 agent-skills 技能库里每个技能都是一个独立的 JSON 文件注册中心启动时自动扫描加载。一个完整的技能定义大致包含下面这些字段字段作用我的建议name技能唯一标识也是模型选择时的依据动词开头、小写加下划线如query_calendardescription告诉模型“什么时候用这个技能”写清触发场景、输入要点、输出内容、不使用范围parameters输入参数的 JSON Schema必填可选项要明确枚举值要完整每个字段都写描述output_schema返回结果的结构定义统一包含status、data、error_code、retryableentrypoint实际执行函数的引用对应代码里的函数名或内部接口路由tags技能标签用于动态注入时的召回过滤cost预估调用成本等级我给每个技能标 low/mid/high方便做路由决策命名规范这件事看起来琐碎实际上对模型影响很大。我一开始用过中文名比如“查询日历”模型倒是能理解但和别的中文技能混在一起时描述稍长就容易语义重叠。后来统一改成英文小写动词短语模型反而更容易区分因为技能名本身就是现成的语义锚点。另外一个细节是技能名不要太长不超过四个词否则模型在生成函数调用时容易截断。2.2 输入输出的 Schema 设计要点输入输出 Schema 是整个技能设计的核心我在这上面翻过最大的跟头是校验太严会拒掉真实请求校验太松会让模型乱传参数。后来总结出一个相对平衡的做法必填字段严格校验可选字段给默认值所有字段必须有description。举个例子一个query_weather技能的参数定义可以长这样{ type: object, properties: { city: { type: string, description: 城市名称如北京、上海, minLength: 2 }, date: { type: string, description: 查询日期格式 YYYY-MM-DD默认今天, pattern: ^\\d{4}-\\d{2}-\\d{2}$ } }, required: [city], additionalProperties: false }这里有几个设计意图值得说一下。date不是必填但我在描述里写清楚了默认值这样用户说“北京明天天气”时模型也会主动把日期补上。additionalProperties: false看起来严格实际能防止模型塞一些奇怪字段进来比如把“体感温度”这种需求直接放进参数里。还有一个小技巧输出结构里不要只返回result这种自由文本统一用{status: ok, data: {...}}或者{status: error, error_code: PARAM_MISSING, message: 缺少城市参数, retryable: true}。这个retryable字段特别有用代表“这次失败是否值得让 Agent 修正后重试”。输出设计上还有一条原则不要让技能返回超长内容。我见过一个技能把数据库里五十行记录全塞回来结果模型上下文瞬间被占满后续对话质量直线下降。正确的做法是在技能内部做截断、聚合只返回最关键的几条数据并附上一句“共查到 N 条记录已展示前 5 条”。这比让模型自己去处理海量原始数据要稳得多。2.3 技能描述里的“触发条件”与“边界条件”技能描述是模型判断“要不要调用这个技能”的核心依据写得好不好直接决定触发准确率。我的标准模板是这个技能干什么 什么时候用 什么时候不要用 输入要注意什么。前三句尤其重要特别是“什么时候不要用”这句很多人会忽略。拿我在 agent-skills 里的一个技能举例{ name: get_stock_price, description: 查询A股个股最新行情。当用户给出具体股票名称或代码并询问股价、涨跌幅、市值时使用。需要先将股票名称转换为标准代码。仅适用于个股行情不适用于指数、板块、基金、期货。若用户只问宏观市场走势不要调用本技能。 }“仅适用于个股”“不适用于指数”这些否定句对防止误触发有奇效。我之前只写正向描述“查询股票行情时使用”结果用户说“看看今天大盘怎么样”模型也去调这个接口拿回来的个股数据自然驴唇不对马嘴。加上边界条件之后误触发率从 17% 降到了 3% 左右。还有一个经验是技能功能要单一不要做“全能型技能”。比如一个技能既查天气又推荐穿衣描述写起来就很容易含糊“当用户询问天气或穿衣建议时使用”。模型在高并发场景下大概率会纠结到底该不该为了一句“今天适合穿什么”去调这个技能。我后来把推荐穿衣单独拆成了suggest_outfit技能它的输入直接吃query_weather的输出数据功能边界一下清晰了。3. 从定义到可执行技能注册与调用的完整链路3.1 技能注册中心一份技能清单如何被“加载”技能定义文件写好了接下来要解决的就是“怎么让系统认识它们”。我采用的是注册中心模式启动时扫描skills/目录下的所有 JSON 文件解析并校验加载进内存构建一个按技能名索引的字典。这样做的好处是技能可以通过文件系统做版本管理上线新技能只加文件下线技能只删文件不需要改业务代码。为了让注册中心足够可靠我加了一道“启动自检”流程扫描完所有技能文件后会做三件事检查技能名唯一性重名直接报错阻断启动。检查每个技能的入口函数是否存在找不到就打印警告并把技能标记为disabled。校验参数 Schema 是否合法非法 JSON Schema 直接阻断启动。这一步看起来不起眼但能在开发期拦截大量低级问题。我早期偷懒跳过自检结果上线后有个技能因为入口函数名写错每次被模型选中都报 500用户体感就是“助手突然不会干活了”。现在自检流程跑一遍只要几百毫秒省心得多。技能文件的entrypoint我推荐用内部函数名而不是 HTTP 接口地址。因为技能执行器多数情况下是同一个进程函数调用比 HTTP 调用少一层网络开销也更容易做超时控制。如果技能需要访问外部 API在对应的函数内部再去请求不要让技能定义直接依赖某个第三方接口地址否则接口一换所有技能文件都要改。3.2 Function Calling 与动态工具注入技能注册好之后怎么让大模型知道这些技能的存在目前主流的做法是通过大模型厂商提供的 Function Calling / Tool Use 能力把技能列表里的名字、描述、参数 Schema 转成模型接口里的tools参数模型在回答时如果觉得需要就会返回一个函数调用请求其中包含技能名和模型推测出的参数。调用完成后业务系统把执行结果拼成一条工具消息返回给模型模型再基于这个结果组织最终回复。这套链路听起来简单实际工程里最需要用心的是“把哪些技能注入给模型”。早期技能少全量注入没问题技能超过二十个之后全量注入有三个隐患一是 token 消耗猛增每个技能的描述加参数 Schema 动辄几百 token三十个技能就是上万 token一次对话十几轮成本直接失控二是技能多了之后模型选择准确率反而下降因为描述之间的语义重叠会互相干扰三是响应变慢工具列表越长模型需要处理的输入越多首字延迟被明显拉高。我的解决方案是“动态技能注入”先对用户消息做一次轻量召回从技能库里捞出一批候选技能再连同系统级技能一起注入模型。def recall_skills(user_message: str, all_skills: dict[str, Skill]) - list[str]: # 先按关键词标签过滤 candidates [s for s in all_skills.values() if any(tag in user_message for tag in s.tags)] # 再做一次 embedding 语义召回取 top_k top_k get_top_k_embeddings(user_message, candidates, k5) return [s.name for s in top_k] DEFAULT_ALWAYS_INJECTED召回策略我用了两层第一层是标签关键词匹配速度快能覆盖大多数明确意图第二层是向量召回用来处理那些“用户没有说出关键词但语义相关”的情况。两层都落空时模型就只带系统级技能回答或者通过一个ask_clarification技能追问用户。实测下来动态注入能把单轮 token 成本砍掉一半以上而且模型选对技能的概率提升了大概 10 个百分点。3.3 技能执行器的设计超时、重试与并发控制技能被模型选中后实际执行工作由执行器完成这也是 agent-skills 体系里真正“干粗活”的地方。执行器做的不是简单调用函数而是要把技能执行的各个环节管起来鉴权、限流、超时、重试、结果归一化。这里我重点讲超时和重试因为这两个地方最容易踩坑。超时设置我分成两档内部函数技能统一 10 秒超时外部 API 类技能分网络情况给 5 到 15 秒。原则是“宁可超时返回错误也不要无限挂起”。早期我没给外部请求设置超时结果某次第三方接口挂了Agent 卡了整整两分钟没响应用户直接关闭了页面。现在执行器默认给所有外部请求打上timeout参数并且超时后返回{error_code: TIMEOUT, retryable: true}模型看到这个结果会主动说“刚才查询超时了要不要再试一次”体验比干等好太多。重试策略有两条硬性规则第一幂等技能才可以自动重试比如查询类技能第二非幂等技能比如发消息、创建订单绝对禁止自动重试只能把错误返回给模型让模型提示用户确认后重试。自动重试采用指数退避第一次 1 秒第二次 2 秒第三次 4 秒最多三次。这样既能缓解网络抖动又不会因为短时间重试风暴把下游接口打崩。并发控制上我的做法是给每个技能配置一个最大并发数超出的请求直接排队。同一用户上下文内的技能调用串行执行不同用户的请求并发执行。这样做是为了保住一个东西上下文一致性——同一个对话里技能结果的顺序不能乱否则模型理解起来会很错乱。4. 技能编排多个技能如何协作完成复杂任务4.1 线性编排与条件编排单个技能只能处理单一指令真实用户的需求往往是复合的。比如“帮我安排明天上午的出差行程如果下雨就提醒我带伞还要提前出发”这句话至少涉及解析行程意图、查日历、查天气、计算路程时间、生成行程简报这几个环节。技能编排就是把这些环节有序地串起来。我最常用的是线性编排加条件分支。还是用出差助手这个例子完整的技能调用流程是这样的parse_trip_request解析用户消息提取日期、目的地、会议时间等结构化信息。query_calendar查询当天日程确认是否有冲突。query_weather查询目的地天气得到是否下雨、温度等数据。calculate_travel_time计算从当前位置到目的地的时间依赖天气数据调整建议出发时间。write_trip_brief把前面所有输出汇总成一段可读的行程简报。send_notification将简报发送到用户指定的渠道。这个流程里每一步输出都是下一步的输入依据顺序不能错。但我不建议写死一个 DAG 执行引擎来强行编排原因很简单真实用户请求千变万化引擎写死了反而僵化。我的做法是给 Agent 一个“蓝图技能”把上述顺序以输入输出说明的方式写清楚由模型自己决定走到哪一步、跳过哪一步。比如用户没提天气模型完全可以从步骤 2 直接跳到步骤 4不需要经过天气技能。条件分支的场景同样交给模型判断。我见过一个典型的例子天气技能返回retryable: true且连续失败两次模型会主动换一条分支不再依赖天气数据提示用户“天气服务暂时不可用我按常规情况帮你安排建议出门前自己看一眼窗外”。这种灵活度是写死的编排引擎给不了的。4.2 技能间数据传递上下文的“临时存取区”技能编排最难处理的一个问题就是中间数据怎么传递。我的 agent-skills 体系里专门设置了一个“上下文暂存区”本质是一个有命名空间的缓存结构每个技能执行完后把需要留给后面用的数据写入这个区域后续技能通过明确的键名取数。{ session_id: session_1024, context: { current: { trip: {date: 2025-06-20, city: 杭州, meeting_time: 10:00}, weather: {city: 杭州, date: 2025-06-20, rain: false, temp_c: 28} }, history: [] } }这里的current只保留当前这轮任务相关的临时数据任务结束后清空history记录已执行的技能调用摘要方便模型回溯。两个注意点一是每个技能在写入数据时要带清晰的键名不要所有技能都往一个result字段里塞否则取数时根本不知道取的是谁的结果二是取数时只取当前任务需要的那部分子集不要把整个current对象都传给下一个技能的 prompt否则上下文膨胀得很快。数据传递还有一个常见坑是格式转换。比如query_weather返回的温度是一个浮点数 28.0而suggest_outfit期望的是类似hot的枚举值就需要在技能内部做一次映射而不是把原始浮点数直接塞进去让模型自己推。技能与技能之间的数据格式应该由接收方技能的参数 Schema 来约束发送方要在执行完就转换好不要指望模型在下游技能调用时自动做类型推断。4.3 技能的自省与降级技能执行失败后的处理我一开始的天真想法是让模型看到错误返回然后自己想办法。后来发现这不够因为模型经常想不出替代方案只会道歉然后重复调用同一个失败技能。后来我引入了“降级技能”的概念——在技能定义里显式写清楚当本技能不可用时可以退而求其次使用哪个技能或者改为通过询问用户收集更多信息再选择方案。拿flight_price技能举例描述里我写了这样一句“本技能用于查询实时机票价格如果实时接口不可用可以降级使用price_estimate技能提供价格范围最终答复中需向用户说明是估算值。”这句话给了模型一个明确的逃生通道它不会卡死在失败循环里。我还给降级设置了成本护栏优先在候选技能里切换到cost更低的技能比如实时查询失败可以用历史统计接口但不允许反着来。自省方面我鼓励给 Agent 配置一个ask_clarification技能当它发现用户请求含糊、缺少必要参数且无法从上下文推断时主动向用户提问而不是强行调用一个参数残缺的技能。实测这个技能对整体体验的提升很直观用户不会觉得机器人在瞎猜反而觉得“这个助手知道什么该问”。这种交互上的“示弱”其实比硬着头皮执行更可靠。5. 测试与调试让技能体系真正“可控”5.1 技能级测试用黄金样例集验证技能描述是给模型看的“说明书”改一个字都可能影响触发行为所以测试绝对不能省。我的做法是给每个技能建一个黄金样例集里面包含三类样本应该触发该技能的正例、不该触发该技能的负例、触发后参数解析应该得到什么结果的参数例。具体到文件结构我会准备一个类似下面的测试集[ {user_message: 帮我看看贵州茅台今天涨了没, expected_skill: get_stock_price, expected_params: {symbol: 600519.SH}}, {user_message: 今天大盘怎么样, expected_skill: none}, {user_message: 帮我订一张明天去上海的车票, expected_skill: create_ticket_order, expected_params: {from: 北京, to: 上海, date: 2025-06-21}} ]每次修改完技能描述或者新增技能我都跑一遍全量回归统计几个关键指标正例触发率、负例误触发率、参数解析正确率。这个步骤说起来简单实际价值非常大。我印象最深的一次是给create_ticket_order的描述里加了一句“当用户需要查询车次时刻表时不要使用”结果负例误触发率直接从 11% 降到 2%如果没有这个测试集这种问题几乎不可能被发现。5.2 链路级测试与问题追踪技能级测试通过只是第一步真实场景里 Agent 会一次调用多个技能链路级的问题更复杂。最常见的是“上下文污染”前一个技能返回了大量原始数据后面模型组织回复时被这些数据带偏把不相干的信息当成了重点。为了排查这类问题我养成了给每次用户请求记录技能调用链的习惯。一条典型的调用链日志长这样{ request_id: req_8f2a, user_message: 帮我看下明天杭州出差穿什么, events: [ {skill: parse_trip_request, elapsed_ms: 95, status: ok}, {skill: query_weather, elapsed_ms: 320, status: ok}, {skill: suggest_outfit, elapsed_ms: 210, status: ok} ], final_reply: 明天杭州28度建议穿短袖... }排查问题时我一般按照这个顺序问模型有没有选对技能选对了参数传对了没有参数对了执行成功了吗执行成功但返回值是不是被正确传递给了下一个环节这四步看完绝大多数问题都能定位到具体位置。如果模型压根没选技能就回复了用户那就是召回层或者描述层的问题如果选对了技能但参数是空的那就是 Schema 设计得太复杂模型没理解每个字段的含义如果执行报错则要看错误码和重试策略。5.3 常见问题速查表我在实战里遇到过的典型问题整理成了一张速查表发布前检查一遍能省很多事问题现象可能原因排查方式解决方案模型该调技能时不调技能描述太模糊或注入时被漏掉检查调用链日志是否有技能注入记录重写描述增加正例触发场景表述检查动态召回规则非目标场景也调技能描述缺少负例边界或技能功能过宽检查负例测试集的误触发率在描述里补“不使用场景”拆分为单一职责技能参数解析不完整参数 Schema 有必填字段但描述没说清楚查看模型返回的原始函数调用参数每个参数字段补充描述与示例必要时放宽校验调用成功但结果没用上输出结构复杂模型抓取信息失败检查上下文暂存区的数据是否被正确写入输出结构尽量扁平增加摘要字段技能全部超时外部依赖异常或超时设置过短查看执行器日志中的耗时分布区分内部函数和外部 API 的超时阈值增加重试手动测试没问题线上不稳定动态注入召回不稳定漏掉关键技能对比手工测试和线上请求的技能候选集增加关键词标签调整 embedding 相似度阈值上下文被长返回撑爆技能返回了大量原始数据没有截断查看 final_reply 前上下文 token 占用技能内部做截断聚合只返回摘要和 top-k 数据这张表我会贴在项目文档首页遇到问题先对着表自查一遍比自己瞎猜要快得多。希望它也能帮你少走一段弯路。6. 避坑经验与我的实操心得6.1 给新手的三个建议如果你正准备在项目里搭建一套 agent-skills 体系我强烈建议你从这三个小习惯开始。第一从最常用的 5 个技能开始不要一上来就做庞大技能库。我见过一个团队雄心勃勃规划了四十个技能结果注册中心是搭起来了技能描述却大量重复模型选起来一脸茫然。技能数量少的时候全量注入和动态注入区别不大先把链路跑通更重要。第二技能描述先写三句话这个技能干什么、什么时候用、什么时候千万别用。写完之后念一遍如果自己都觉得含糊模型肯定更糊涂。第三任何外部依赖都要有 mock 模式。开发阶段不要连真实天气接口、真实支付接口本地用 mock 数据跑通流程这样测试用例可控、调试成本也低。这三个习惯帮我避开了很多不必要的大坑。6.2 从“脚本”到“产品”技能的持续迭代最后说说我最大的一个观念转变。最开始我把 agent-skills 当成一套脚本管理工具技能写了就完事很少回头改。后来发现技能和产品一样需要持续迭代——用户问法在变、外部接口在变、大模型版本在变技能描述和边界条件也必须跟着微调。我现在固定每两周做一次技能体检跑一遍全量回归测试看触发准确率和参数解析正确率有没有变化翻一遍生产环境的调用链日志找出那些“模型选了技能但结果不如人意”的样本再看看有没有新增的用户问法没被现有技能覆盖。这套循环不复杂但它把技能体系从静态文件变成了一个可持续进化的系统。还有一个我正在尝试的方向是技能自动生成给模型提供一份业务文档让它产出技能定义初稿包括描述、参数 Schema 和负例边界再由人工审核后合入注册中心。目前生成质量大概七成能用剩下的三成需要调整描述和补负面样例但已经能省很多写文件的时间了。等这个流程再跑顺一些技能库的扩展速度会比现在快很多。我自己的体会是Agent 的技能体系设计本质上是在“模型的自由发挥”和“系统的可控约束”之间找平衡。技能太少模型容易瞎猜技能太多模型容易选错。真正好用的 agent-skills应该像一套收纳整齐的工具箱每个技能放在它该在的位置标签清晰待命就绪。这个度需要靠测试、日志和持续调优来把握没有什么一劳永逸的捷径但走完这套流程之后你会明显感觉到 Agent 从“偶尔聪明”变成了“稳定靠谱”。
决定一个 AI Agent 好不好用的说实话早就不是模型智商了而是它手上到底有多少靠谱的“技能”。我去年维护了一个名叫 agent-skills 的技能库把同一套任务分别用纯提示词和技能化方式实现了一版效果差距大得离谱。所谓 agent-skills说白了就是把“让模型记住怎么做”变成“让模型知道有哪些技能可用、每个技能怎么被调用、调用结果怎么落回上下文”。这篇文章不聊虚的概念我会直接分享我搭建这套技能体系时踩过的坑、沉淀下来的设计套路以及实测中真正管用的调试方法。如果你正在做 AI 应用落地或者想让现有的助手能稳定干活而不是动不动一本正经地胡说这篇值得看完。1. 为什么 Agent 需要“技能化”而不是一堆提示词1.1 技能和提示词的本质区别很多人问过我一个问题我已经在系统提示词里写清楚了“当你需要查天气时就调用 /weather 接口”为什么 Agent 还是经常不按套路出牌这个问题的答案恰恰是理解 agent-skills 的关键。如果把大模型当成一个刚入职的实习生提示词就是领导的“口头交代”大概说清楚方向但具体步骤、边界条件、异常怎么处理全靠临时发挥。而技能相当于一张标准操作卡上面明确写了输入要什么格式、输出返回什么结构、什么情况不能碰、失败了怎么收场。举个我实际遇到的例子。早期我在系统提示词里塞了一段话“用户想了解股票行情时调用get_stock_price(symbol)返回最新价格。”听起来很清楚对吧实际运行中模型经常犯三种错一是用户说“帮我看看最近板块走势”模型也调用了这个接口二是接口需要“600519.SH”这种带交易所后缀的代码模型却传了“贵州茅台”四个字三是接口超时或者返回空数据时模型直接编了一个价格出来告诉用户。这就是纯提示词方案的天然缺陷它只有“意图”没有“约束”模型每一步都在自由发挥。技能化解决的就是这个问题。一个技能至少包含四样东西能被模型理解的描述、严格的输入参数定义、确定性的执行逻辑、结构化的输出格式。以查股票为例技能描述里会写“仅用于查询A股个股最新行情不适用于指数、板块、基金用户给出股票名称时请先转换为标准代码”输入参数是枚举约束的字符串必须符合交易所代码规则输出统一是{status, data, error_code, retryable}结构。模型不再“背命令”它只是在一个定义好的技能列表里做选择选完了由执行系统保证动作的正确性。这就是技能和提示词最本质的差别提示词靠模型自觉技能靠系统约束。1.2 技能化带来的三个直接收益第一个收益是可复用。一个write_meeting_summary技能写好后可以用在会议助手、周报生成器、项目复盘机器人等多个场景里不需要每次重新写长提示词也不会因为提示词越改越长而出现“改一处坏一片”的连锁反应。我现在的做法是技能独立成文件哪个场景需要就引入哪个业务代码和提示词都清爽很多。第二个收益是可测试。技能是黑盒输入固定输出结构固定我可以单独准备一批测试样本每天跑一遍回归看触发准确率和参数解析正确率有没有下降。这在纯提示词时代是很难想象的因为你没法对一段描述做单元测试。技能化之后“这个技能描述改了会不会误触发”变成了一个可以量化的问题每次发布前跑一次回归就心中有数。第三个收益是可观测。Agent 调用了哪些技能、每个技能花了多少毫秒、传入了什么参数、返回了什么结果全部可以记录成结构化日志。一旦出问题顺着调用链就能定位是模型选错了技能、参数没传对还是外部接口挂了。这种透明度对生产环境太重要了我后面第五章会展开讲具体的排查方法。2. 一份好技能清单长什么样核心字段与设计思路2.1 技能的基本字段与命名规范我维护的 agent-skills 技能库里每个技能都是一个独立的 JSON 文件注册中心启动时自动扫描加载。一个完整的技能定义大致包含下面这些字段字段作用我的建议name技能唯一标识也是模型选择时的依据动词开头、小写加下划线如query_calendardescription告诉模型“什么时候用这个技能”写清触发场景、输入要点、输出内容、不使用范围parameters输入参数的 JSON Schema必填可选项要明确枚举值要完整每个字段都写描述output_schema返回结果的结构定义统一包含status、data、error_code、retryableentrypoint实际执行函数的引用对应代码里的函数名或内部接口路由tags技能标签用于动态注入时的召回过滤cost预估调用成本等级我给每个技能标 low/mid/high方便做路由决策命名规范这件事看起来琐碎实际上对模型影响很大。我一开始用过中文名比如“查询日历”模型倒是能理解但和别的中文技能混在一起时描述稍长就容易语义重叠。后来统一改成英文小写动词短语模型反而更容易区分因为技能名本身就是现成的语义锚点。另外一个细节是技能名不要太长不超过四个词否则模型在生成函数调用时容易截断。2.2 输入输出的 Schema 设计要点输入输出 Schema 是整个技能设计的核心我在这上面翻过最大的跟头是校验太严会拒掉真实请求校验太松会让模型乱传参数。后来总结出一个相对平衡的做法必填字段严格校验可选字段给默认值所有字段必须有description。举个例子一个query_weather技能的参数定义可以长这样{ type: object, properties: { city: { type: string, description: 城市名称如北京、上海, minLength: 2 }, date: { type: string, description: 查询日期格式 YYYY-MM-DD默认今天, pattern: ^\\d{4}-\\d{2}-\\d{2}$ } }, required: [city], additionalProperties: false }这里有几个设计意图值得说一下。date不是必填但我在描述里写清楚了默认值这样用户说“北京明天天气”时模型也会主动把日期补上。additionalProperties: false看起来严格实际能防止模型塞一些奇怪字段进来比如把“体感温度”这种需求直接放进参数里。还有一个小技巧输出结构里不要只返回result这种自由文本统一用{status: ok, data: {...}}或者{status: error, error_code: PARAM_MISSING, message: 缺少城市参数, retryable: true}。这个retryable字段特别有用代表“这次失败是否值得让 Agent 修正后重试”。输出设计上还有一条原则不要让技能返回超长内容。我见过一个技能把数据库里五十行记录全塞回来结果模型上下文瞬间被占满后续对话质量直线下降。正确的做法是在技能内部做截断、聚合只返回最关键的几条数据并附上一句“共查到 N 条记录已展示前 5 条”。这比让模型自己去处理海量原始数据要稳得多。2.3 技能描述里的“触发条件”与“边界条件”技能描述是模型判断“要不要调用这个技能”的核心依据写得好不好直接决定触发准确率。我的标准模板是这个技能干什么 什么时候用 什么时候不要用 输入要注意什么。前三句尤其重要特别是“什么时候不要用”这句很多人会忽略。拿我在 agent-skills 里的一个技能举例{ name: get_stock_price, description: 查询A股个股最新行情。当用户给出具体股票名称或代码并询问股价、涨跌幅、市值时使用。需要先将股票名称转换为标准代码。仅适用于个股行情不适用于指数、板块、基金、期货。若用户只问宏观市场走势不要调用本技能。 }“仅适用于个股”“不适用于指数”这些否定句对防止误触发有奇效。我之前只写正向描述“查询股票行情时使用”结果用户说“看看今天大盘怎么样”模型也去调这个接口拿回来的个股数据自然驴唇不对马嘴。加上边界条件之后误触发率从 17% 降到了 3% 左右。还有一个经验是技能功能要单一不要做“全能型技能”。比如一个技能既查天气又推荐穿衣描述写起来就很容易含糊“当用户询问天气或穿衣建议时使用”。模型在高并发场景下大概率会纠结到底该不该为了一句“今天适合穿什么”去调这个技能。我后来把推荐穿衣单独拆成了suggest_outfit技能它的输入直接吃query_weather的输出数据功能边界一下清晰了。3. 从定义到可执行技能注册与调用的完整链路3.1 技能注册中心一份技能清单如何被“加载”技能定义文件写好了接下来要解决的就是“怎么让系统认识它们”。我采用的是注册中心模式启动时扫描skills/目录下的所有 JSON 文件解析并校验加载进内存构建一个按技能名索引的字典。这样做的好处是技能可以通过文件系统做版本管理上线新技能只加文件下线技能只删文件不需要改业务代码。为了让注册中心足够可靠我加了一道“启动自检”流程扫描完所有技能文件后会做三件事检查技能名唯一性重名直接报错阻断启动。检查每个技能的入口函数是否存在找不到就打印警告并把技能标记为disabled。校验参数 Schema 是否合法非法 JSON Schema 直接阻断启动。这一步看起来不起眼但能在开发期拦截大量低级问题。我早期偷懒跳过自检结果上线后有个技能因为入口函数名写错每次被模型选中都报 500用户体感就是“助手突然不会干活了”。现在自检流程跑一遍只要几百毫秒省心得多。技能文件的entrypoint我推荐用内部函数名而不是 HTTP 接口地址。因为技能执行器多数情况下是同一个进程函数调用比 HTTP 调用少一层网络开销也更容易做超时控制。如果技能需要访问外部 API在对应的函数内部再去请求不要让技能定义直接依赖某个第三方接口地址否则接口一换所有技能文件都要改。3.2 Function Calling 与动态工具注入技能注册好之后怎么让大模型知道这些技能的存在目前主流的做法是通过大模型厂商提供的 Function Calling / Tool Use 能力把技能列表里的名字、描述、参数 Schema 转成模型接口里的tools参数模型在回答时如果觉得需要就会返回一个函数调用请求其中包含技能名和模型推测出的参数。调用完成后业务系统把执行结果拼成一条工具消息返回给模型模型再基于这个结果组织最终回复。这套链路听起来简单实际工程里最需要用心的是“把哪些技能注入给模型”。早期技能少全量注入没问题技能超过二十个之后全量注入有三个隐患一是 token 消耗猛增每个技能的描述加参数 Schema 动辄几百 token三十个技能就是上万 token一次对话十几轮成本直接失控二是技能多了之后模型选择准确率反而下降因为描述之间的语义重叠会互相干扰三是响应变慢工具列表越长模型需要处理的输入越多首字延迟被明显拉高。我的解决方案是“动态技能注入”先对用户消息做一次轻量召回从技能库里捞出一批候选技能再连同系统级技能一起注入模型。def recall_skills(user_message: str, all_skills: dict[str, Skill]) - list[str]: # 先按关键词标签过滤 candidates [s for s in all_skills.values() if any(tag in user_message for tag in s.tags)] # 再做一次 embedding 语义召回取 top_k top_k get_top_k_embeddings(user_message, candidates, k5) return [s.name for s in top_k] DEFAULT_ALWAYS_INJECTED召回策略我用了两层第一层是标签关键词匹配速度快能覆盖大多数明确意图第二层是向量召回用来处理那些“用户没有说出关键词但语义相关”的情况。两层都落空时模型就只带系统级技能回答或者通过一个ask_clarification技能追问用户。实测下来动态注入能把单轮 token 成本砍掉一半以上而且模型选对技能的概率提升了大概 10 个百分点。3.3 技能执行器的设计超时、重试与并发控制技能被模型选中后实际执行工作由执行器完成这也是 agent-skills 体系里真正“干粗活”的地方。执行器做的不是简单调用函数而是要把技能执行的各个环节管起来鉴权、限流、超时、重试、结果归一化。这里我重点讲超时和重试因为这两个地方最容易踩坑。超时设置我分成两档内部函数技能统一 10 秒超时外部 API 类技能分网络情况给 5 到 15 秒。原则是“宁可超时返回错误也不要无限挂起”。早期我没给外部请求设置超时结果某次第三方接口挂了Agent 卡了整整两分钟没响应用户直接关闭了页面。现在执行器默认给所有外部请求打上timeout参数并且超时后返回{error_code: TIMEOUT, retryable: true}模型看到这个结果会主动说“刚才查询超时了要不要再试一次”体验比干等好太多。重试策略有两条硬性规则第一幂等技能才可以自动重试比如查询类技能第二非幂等技能比如发消息、创建订单绝对禁止自动重试只能把错误返回给模型让模型提示用户确认后重试。自动重试采用指数退避第一次 1 秒第二次 2 秒第三次 4 秒最多三次。这样既能缓解网络抖动又不会因为短时间重试风暴把下游接口打崩。并发控制上我的做法是给每个技能配置一个最大并发数超出的请求直接排队。同一用户上下文内的技能调用串行执行不同用户的请求并发执行。这样做是为了保住一个东西上下文一致性——同一个对话里技能结果的顺序不能乱否则模型理解起来会很错乱。4. 技能编排多个技能如何协作完成复杂任务4.1 线性编排与条件编排单个技能只能处理单一指令真实用户的需求往往是复合的。比如“帮我安排明天上午的出差行程如果下雨就提醒我带伞还要提前出发”这句话至少涉及解析行程意图、查日历、查天气、计算路程时间、生成行程简报这几个环节。技能编排就是把这些环节有序地串起来。我最常用的是线性编排加条件分支。还是用出差助手这个例子完整的技能调用流程是这样的parse_trip_request解析用户消息提取日期、目的地、会议时间等结构化信息。query_calendar查询当天日程确认是否有冲突。query_weather查询目的地天气得到是否下雨、温度等数据。calculate_travel_time计算从当前位置到目的地的时间依赖天气数据调整建议出发时间。write_trip_brief把前面所有输出汇总成一段可读的行程简报。send_notification将简报发送到用户指定的渠道。这个流程里每一步输出都是下一步的输入依据顺序不能错。但我不建议写死一个 DAG 执行引擎来强行编排原因很简单真实用户请求千变万化引擎写死了反而僵化。我的做法是给 Agent 一个“蓝图技能”把上述顺序以输入输出说明的方式写清楚由模型自己决定走到哪一步、跳过哪一步。比如用户没提天气模型完全可以从步骤 2 直接跳到步骤 4不需要经过天气技能。条件分支的场景同样交给模型判断。我见过一个典型的例子天气技能返回retryable: true且连续失败两次模型会主动换一条分支不再依赖天气数据提示用户“天气服务暂时不可用我按常规情况帮你安排建议出门前自己看一眼窗外”。这种灵活度是写死的编排引擎给不了的。4.2 技能间数据传递上下文的“临时存取区”技能编排最难处理的一个问题就是中间数据怎么传递。我的 agent-skills 体系里专门设置了一个“上下文暂存区”本质是一个有命名空间的缓存结构每个技能执行完后把需要留给后面用的数据写入这个区域后续技能通过明确的键名取数。{ session_id: session_1024, context: { current: { trip: {date: 2025-06-20, city: 杭州, meeting_time: 10:00}, weather: {city: 杭州, date: 2025-06-20, rain: false, temp_c: 28} }, history: [] } }这里的current只保留当前这轮任务相关的临时数据任务结束后清空history记录已执行的技能调用摘要方便模型回溯。两个注意点一是每个技能在写入数据时要带清晰的键名不要所有技能都往一个result字段里塞否则取数时根本不知道取的是谁的结果二是取数时只取当前任务需要的那部分子集不要把整个current对象都传给下一个技能的 prompt否则上下文膨胀得很快。数据传递还有一个常见坑是格式转换。比如query_weather返回的温度是一个浮点数 28.0而suggest_outfit期望的是类似hot的枚举值就需要在技能内部做一次映射而不是把原始浮点数直接塞进去让模型自己推。技能与技能之间的数据格式应该由接收方技能的参数 Schema 来约束发送方要在执行完就转换好不要指望模型在下游技能调用时自动做类型推断。4.3 技能的自省与降级技能执行失败后的处理我一开始的天真想法是让模型看到错误返回然后自己想办法。后来发现这不够因为模型经常想不出替代方案只会道歉然后重复调用同一个失败技能。后来我引入了“降级技能”的概念——在技能定义里显式写清楚当本技能不可用时可以退而求其次使用哪个技能或者改为通过询问用户收集更多信息再选择方案。拿flight_price技能举例描述里我写了这样一句“本技能用于查询实时机票价格如果实时接口不可用可以降级使用price_estimate技能提供价格范围最终答复中需向用户说明是估算值。”这句话给了模型一个明确的逃生通道它不会卡死在失败循环里。我还给降级设置了成本护栏优先在候选技能里切换到cost更低的技能比如实时查询失败可以用历史统计接口但不允许反着来。自省方面我鼓励给 Agent 配置一个ask_clarification技能当它发现用户请求含糊、缺少必要参数且无法从上下文推断时主动向用户提问而不是强行调用一个参数残缺的技能。实测这个技能对整体体验的提升很直观用户不会觉得机器人在瞎猜反而觉得“这个助手知道什么该问”。这种交互上的“示弱”其实比硬着头皮执行更可靠。5. 测试与调试让技能体系真正“可控”5.1 技能级测试用黄金样例集验证技能描述是给模型看的“说明书”改一个字都可能影响触发行为所以测试绝对不能省。我的做法是给每个技能建一个黄金样例集里面包含三类样本应该触发该技能的正例、不该触发该技能的负例、触发后参数解析应该得到什么结果的参数例。具体到文件结构我会准备一个类似下面的测试集[ {user_message: 帮我看看贵州茅台今天涨了没, expected_skill: get_stock_price, expected_params: {symbol: 600519.SH}}, {user_message: 今天大盘怎么样, expected_skill: none}, {user_message: 帮我订一张明天去上海的车票, expected_skill: create_ticket_order, expected_params: {from: 北京, to: 上海, date: 2025-06-21}} ]每次修改完技能描述或者新增技能我都跑一遍全量回归统计几个关键指标正例触发率、负例误触发率、参数解析正确率。这个步骤说起来简单实际价值非常大。我印象最深的一次是给create_ticket_order的描述里加了一句“当用户需要查询车次时刻表时不要使用”结果负例误触发率直接从 11% 降到 2%如果没有这个测试集这种问题几乎不可能被发现。5.2 链路级测试与问题追踪技能级测试通过只是第一步真实场景里 Agent 会一次调用多个技能链路级的问题更复杂。最常见的是“上下文污染”前一个技能返回了大量原始数据后面模型组织回复时被这些数据带偏把不相干的信息当成了重点。为了排查这类问题我养成了给每次用户请求记录技能调用链的习惯。一条典型的调用链日志长这样{ request_id: req_8f2a, user_message: 帮我看下明天杭州出差穿什么, events: [ {skill: parse_trip_request, elapsed_ms: 95, status: ok}, {skill: query_weather, elapsed_ms: 320, status: ok}, {skill: suggest_outfit, elapsed_ms: 210, status: ok} ], final_reply: 明天杭州28度建议穿短袖... }排查问题时我一般按照这个顺序问模型有没有选对技能选对了参数传对了没有参数对了执行成功了吗执行成功但返回值是不是被正确传递给了下一个环节这四步看完绝大多数问题都能定位到具体位置。如果模型压根没选技能就回复了用户那就是召回层或者描述层的问题如果选对了技能但参数是空的那就是 Schema 设计得太复杂模型没理解每个字段的含义如果执行报错则要看错误码和重试策略。5.3 常见问题速查表我在实战里遇到过的典型问题整理成了一张速查表发布前检查一遍能省很多事问题现象可能原因排查方式解决方案模型该调技能时不调技能描述太模糊或注入时被漏掉检查调用链日志是否有技能注入记录重写描述增加正例触发场景表述检查动态召回规则非目标场景也调技能描述缺少负例边界或技能功能过宽检查负例测试集的误触发率在描述里补“不使用场景”拆分为单一职责技能参数解析不完整参数 Schema 有必填字段但描述没说清楚查看模型返回的原始函数调用参数每个参数字段补充描述与示例必要时放宽校验调用成功但结果没用上输出结构复杂模型抓取信息失败检查上下文暂存区的数据是否被正确写入输出结构尽量扁平增加摘要字段技能全部超时外部依赖异常或超时设置过短查看执行器日志中的耗时分布区分内部函数和外部 API 的超时阈值增加重试手动测试没问题线上不稳定动态注入召回不稳定漏掉关键技能对比手工测试和线上请求的技能候选集增加关键词标签调整 embedding 相似度阈值上下文被长返回撑爆技能返回了大量原始数据没有截断查看 final_reply 前上下文 token 占用技能内部做截断聚合只返回摘要和 top-k 数据这张表我会贴在项目文档首页遇到问题先对着表自查一遍比自己瞎猜要快得多。希望它也能帮你少走一段弯路。6. 避坑经验与我的实操心得6.1 给新手的三个建议如果你正准备在项目里搭建一套 agent-skills 体系我强烈建议你从这三个小习惯开始。第一从最常用的 5 个技能开始不要一上来就做庞大技能库。我见过一个团队雄心勃勃规划了四十个技能结果注册中心是搭起来了技能描述却大量重复模型选起来一脸茫然。技能数量少的时候全量注入和动态注入区别不大先把链路跑通更重要。第二技能描述先写三句话这个技能干什么、什么时候用、什么时候千万别用。写完之后念一遍如果自己都觉得含糊模型肯定更糊涂。第三任何外部依赖都要有 mock 模式。开发阶段不要连真实天气接口、真实支付接口本地用 mock 数据跑通流程这样测试用例可控、调试成本也低。这三个习惯帮我避开了很多不必要的大坑。6.2 从“脚本”到“产品”技能的持续迭代最后说说我最大的一个观念转变。最开始我把 agent-skills 当成一套脚本管理工具技能写了就完事很少回头改。后来发现技能和产品一样需要持续迭代——用户问法在变、外部接口在变、大模型版本在变技能描述和边界条件也必须跟着微调。我现在固定每两周做一次技能体检跑一遍全量回归测试看触发准确率和参数解析正确率有没有变化翻一遍生产环境的调用链日志找出那些“模型选了技能但结果不如人意”的样本再看看有没有新增的用户问法没被现有技能覆盖。这套循环不复杂但它把技能体系从静态文件变成了一个可持续进化的系统。还有一个我正在尝试的方向是技能自动生成给模型提供一份业务文档让它产出技能定义初稿包括描述、参数 Schema 和负例边界再由人工审核后合入注册中心。目前生成质量大概七成能用剩下的三成需要调整描述和补负面样例但已经能省很多写文件的时间了。等这个流程再跑顺一些技能库的扩展速度会比现在快很多。我自己的体会是Agent 的技能体系设计本质上是在“模型的自由发挥”和“系统的可控约束”之间找平衡。技能太少模型容易瞎猜技能太多模型容易选错。真正好用的 agent-skills应该像一套收纳整齐的工具箱每个技能放在它该在的位置标签清晰待命就绪。这个度需要靠测试、日志和持续调优来把握没有什么一劳永逸的捷径但走完这套流程之后你会明显感觉到 Agent 从“偶尔聪明”变成了“稳定靠谱”。
