在写这篇复盘之前先交代一下背景我从去年开始一直在折腾 AI Agent 方向的个人项目最近把精力集中在一个叫agent-skills的技能库设计上也就是给大语言模型LLM驱动的智能体装配一组可插拔、可复用、可独立测试的“外挂能力”。聊到 Agent很多人的第一反应是“多轮对话 工具调用”但真正让 Agent 从“能聊”变成“能干”的往往是它背后挂载的那批 skills。这篇文章就用我自己踩过的坑和整理出的方法论把这个技能库从设计到落地的过程拆开讲透。我默认读者已经对 LLM API 有基本认知知道 function calling / tool use 大概是怎么一回事。如果你目前还停留在“Prompt 里写规则让模型自己瞎猜”的阶段那这篇内容正好能帮你建立一套更工程化的技能组织方式。下文所有代码片段我都尽量用最简单的方式呈现方便你直接抄走改造。1. 先想清楚再动手Agent 的“技能”和模型原生能力的分界线在哪里很多人会把 Agent 的技能等同于“给模型多加几段 Prompt 描述”或者等同于“接入外部 API 的客户端”。我在项目初期也走过这个弯路把天气查询、汇率计算、文件读写全部写死在一套对话逻辑里结果模型调用的准确率还行但每次新增一个能力都要动主流程代码最后整份代码变成一团乱麻。后来我梳理清楚了一个核心分界模型的原生能力是“理解与生成”技能是“改变状态或获取外部事实”。这句话听起来简单实践上却能直接指导你决定该把什么放进 skill什么留在对话层。原生能力处理的任务逻辑推理、文本改写、代码生成、知识问答中基于已学参数的推断。技能处理的任务实时数据获取天气、股价、业务动作执行发邮件、创建工单、与自有系统的交互查库存、更新数据库记录。基于这个划分agent-skills的核心思路就变成设计一层标准化的“技能模型”让每一个技能都是一个独立、自描述、可被 Agent 自动发现和调用的模块。所谓“自描述”指的是技能本身携带足够多的元信息名称、用途、参数定义、返回结果约定模型看到这些信息就能决策要不要用、怎么用。我当时给自己定了一个验收标准当我新增一个技能时不应该修改 Agent 主循环的任何一行代码。只要满足这一点技能的复用性和扩展性就算初步过关。后续你会发现这个标准会反过来逼你把技能定义做得足够规范。2. 技能的标准形态一句话描述、一套参数约束、一个返回协议一个技能模块要能被模型稳定调用必须存在一致的结构。我最终把每个技能收敛为三种层次的组合Manifest清单、Schema参数约束、Executor执行函数。下面用一个非常通用的内部案例来说明技能是“查询天气”。2.1 Manifest 的写法模型挑选工具的第一眼Manifest 是技能的说明书通常包括name和description两项。很多人在写 description 的时候习惯写成“查询天气并返回温度”但在真实应用中你需要写清楚这个技能的适用边界、什么情况下该用、什么情况下不该用、以及某个参数的含义。我在维护agent-skills时就见过一个反例技能 description 写了“获取任意城市天气信息”结果模型在遇到“上海和北京哪个现在更冷”这种需要比较的场景时只调了一次工具就返回因为工具描述里没说“需要比较两个城市时必须调用两次”。这种细节藏在 Manifest 里比藏在 Prompt 的规则里有效得多。以工程化的方式写 description通常这样组织一句话说清该技能做什么明确触发条件“仅当用户询天气时使用”明确不适用条件“不用于预测未来 7 天后的天气”参数中特殊值的含义。这种写法让模型在候选技能较多时更容易做出正确选择。我在实际测试中发现Manifest 写得越像一份“人看的操作手册”模型调用的成功率越高。你可以理解为模型本质上是“在文字空间里做模式匹配”你描述得越接近用户问题的语境它越容易命中。2.2 Schema 的约束参数是模型的“填空游戏”参数约束决定了模型生成调用请求时是否容易出错。我的原则是能用枚举就枚举能设默认值就设默认值能限定格式就限定格式绝不把一个需要结构化解析的字段丢给模型自由发挥。看下面这个参数定义示例{ name: get_weather, description: 查询城市当前及未来24小时天气情况。当用户询问多个城市的天气时请对每个城市分别调用本技能一次。本技能不提供历史天气数据。, parameters: { type: object, properties: { city: { type: string, description: 城市中文名或行政区划名如上海、北京市。用户说我这时可先向用户询问具体城市。 }, unit: { type: string, enum: [celsius, fahrenheit], default: celsius, description: 温度单位默认摄氏度。 } }, required: [city] } }注意这里我把unit设成了枚举并给了默认值而不是让模型自由输入“温度单位”字符串。原因很简单模型在生成 JSON 时最容易犯的错误不是参数名写错而是参数值格式不规范。你想想看如果允许自由输入模型可能给你填写unit: °C、unit: Celsius温度你的执行层还得做一层模糊匹配这就是给自己挖坑。另一个容易忽略的地方是required字段。很多技能出错不是模型不会填参数而是它把可选参数也当成必填反复追问用户。我在技能实现里坚持一个原则如果这个参数 95% 的场景都是同一个值那就给 default别放进 required。参数的“必填”越少模型在边缘场景下的鲁棒性越强。2.3 Executor 的返回协议给模型生成“标准答案”而不是“数据全家桶”Executor 是真正执行动作的函数它的返回值需要按固定协议组织。我的标准返回结构是{ status: success, data: { city: 上海, temperature: 28.5, unit: celsius }, message: 上海当前气温 28.5 摄氏度多云。 }message字段是给模型看的“自然语言摘要”data是给下游逻辑用的结构化数据。为什么要多此一举因为让模型再读一份原始 JSON 数据去总结纯属浪费 token而且容易出错。你在 Executor 里直接把模型订阅的关键信息提炼成一句话模型接下来的回答就稳了。执行失败时返回协议同样重要。返回内容应包含模型能理解的“原因”和“可纠正信息”让模型有机会自行修正参数后重试而不是机械地把错误堆给用户{ status: error, code: CITY_NOT_FOUND, message: 未找到城市[上海]请确认城市名称拼写或改用拼音再试一次。 }3. 注册与路由让 Agent 在“技能集市”里按需采购单看一个技能没什么了不起真正考验架构的是几十个技能并存时模型如何快速找到正确的那个。我在agent-skills中把这块设计成两部分技能注册中心与选择路由。3.1 注册中心全部技能集中管理按领域分组所有技能首次启动时完成注册统一收口。注册不只是在内存里维护字典而是要建立一个“技能清单”里面记录每个技能的名称、描述、分组、版本、调用频率等运行数据。注册中心的数据结构大概长这样# skills/registry.py SKILL_GROUPS { information: [get_weather, get_exchange_rate, search_local_business], automation: [send_email, create_calendar_event], data_analysis: [run_sql_query, generate_report_snapshot] } registry {} def register(skill): registry[skill.name] { definition: skill, group: skill.group, version: skill.version, call_count: 0 }注册中心带来的一个直接好处是模型在选择技能前可以先按“问题类型”缩小候选范围而不是一次性面对几十个技能描述。我实测过一个会话里塞入超过 30 个技能描述时模型的选型准确率会明显下降而且 token 占用极高。按分组维度把候选集压缩到 5-8 个状况会好很多。这里有一个实现上的优化点在输入给模型的消息里按相关性动态注入技能描述而不是把所有技能都怼进 tools 参数。你可以先拿用户问题做一次轻量意图分类筛掉绝对不相关的组再把剩下组的技能描述注入。这个方法对身边做 Agent 的朋友我推荐过很多次都反馈效果立竿见影。3.2 路由层技能选择失败时不要让模型“硬编”路由层的作用是监督模型的技能选择。具体来说当模型在对话中决定调用某个技能时路由层需要做三件事校验技能名是否存在于注册中心校验参数是否符合 JSON Schema检查该技能是否允许在当下上下文使用比如“只读技能”和“写操作技能”的进入门槛应该不同。我经历过的典型事故是模型在用户问“明天天气”时因为我在注册中心里还有“城市攻略生成”技能它的描述里刚好包含“天气”两个字结果模型选错了技能生成了一篇攻略而不是提供天气。后来我加入了“本轮关键词匹配度”和“技能历史使用率”两个维度的评分模型再次动摇时路由层会把它拉回正轨def route_skill(user_input, candidate_skills): scores [] for skill in candidate_skills: desc skill.manifest[description] overlap len(set(user_input.split()) set(desc.split())) score overlap skill.usage_bias scores.append((score, skill.name)) return max(scores)[1]说实话这个逻辑非常朴素但在多数场景下够用。真要上复杂任务你可以后续换成 embedding 相似度计算我这里就不展开讲了。4. 技能的实现细节从“能跑”到“稳定”的四个关键取舍技能库要经得起线上流量的考验光把定义写好还不够。以下四个实现层面的决策是我在开发过程中反复权衡后固定的方案。4.1 参数化校验别让 Executor 去兜底我在很多实现里看到一种做法依赖模型的输出直接进入 Executor出了错再由 Executor 抛异常。这是一种本末倒置——模型输出的 JSON 本质上是“预测结果”它天然可能不符合规范。正确做法是在路由层就完成 JSON Schema 校验不合格就不进入 Executor。校验可以用现成库也可以手写简版。核心是对enum、type、required三个维度做检查。举个例子如果 schema 规定limit必须小于等于 100那么校验层就不该放过 101 这个值——哪怕模型真的生成出来了。4.2 错误处理错误信息要面向“模型”写而不是面向“程序员”写很多人在 Executor 的异常处理里写except Exception as e: return {status: error, error: str(e)}然后模型拿到KeyError: k这种报错信息直接傻掉因为它不知道该怎么修正。你应该在技能实现里把原始异常翻译成模型能理解的“修正指引”。所以我反复强调返回协议里那句message的写法它不只是给人看的更是给模型看的。按照“能自行修正则给指引、不能则说明原委”的原则来写错误消息Agent 在连续多轮调用中的稳定性会好很多。4.3 超时与重试技能调用必须设置天花板外部 API 不可控技能必须设置超时。我统一给所有技能加了 5 秒超时上限并做了两层机制偶发超时允许模型换一种表述重试一次连续失败直接返回“服务暂不可用”状态终止本轮调用循环。这样做是防止 Agent 在遇到外部接口抖动时陷入无限重试的循环。理论上模型是有“执拗病”的——你给它的错误信息越详细它越倾向于反复尝试直到把上下文耗尽。所以重试次数必须由路由层硬性控制而不是交给模型自行判断。4.4 权限隔离读操作和写操作要分家技能库走到一定阶段一定会包含“只读查询”和“变更系统状态”两类技能。我强烈建议在一个技能库内区分等级技能类型示例调用限制纯查询类get_weather,run_sql_query普通会话可随意调用轻操作类send_email,create_calendar_event需用户二次确认后调用高风险类delete_record,transfer_money禁止在无人值守场景调用这条经验来自我在联调阶段的教训Agent 在一次任务中自主把一条演示数据删了理由是“用户表达过想清理数据”的意图。从那以后所有含“删除”“修改”“转账”语义的技能我在实现时都会在 Executor 里再套一层“确认令牌”机制没有用户明确授权就直接返回 “BLOCKED_BY_POLICY”。5. 从 0 到几十个技能的成长路径先做分类再补数量如果你准备在自己的项目里落地agent-skills我的建议不是追求“什么技能都有”而是按阶段推进。第一个阶段先做三个刚需技能信息查询类、计算类、输入输出绕行类。这一步帮助你验证整个标准流程是否顺畅模型能不能发现技能、参数解析是否可靠、错误值是否能被模型消化。第二个阶段开始按业务场景扩展技能组。比如做客服场景就围绕“查订单”“查物流”“生成退款单”三类来建做内容生成场景就围绕“查资料”“生成大纲”“格式化输出”三类来建。不要跨场景乱建技能否则注册中心会很臃肿。第三个阶段引入版本化。技能的参数结构一旦被模型依赖就不能随意破坏。我给每个技能都加了version字段并在注册中心保留了旧版本定义确保线上会话不会因为技能更新而突然出现 JSON 解析失败。这就像 API 的兼容性保证只不过这里的调用方是“模型”而非“浏览器”。技术上完全可以把技能库做成一个对外可安装的插件式目录skills/文件夹下每个 Python 文件对应一个技能启动时自动扫描注册。这种组织方式让新增技能变成“向文件夹丢一个文件”那么简单完全符合我之前给自己定的验收标准不加主流程代码。6. 沉淀下来的调试经验当模型调用了错误的技能先别急着改 Prompt最后聊聊我在调试agent-skills时反复用到的一套方法论。当你发现模型选择技能不够准确时第一反应可能是“加一段 Prompt 强调规则”。我以前也是这么干的但后来发现效果往往有上限——因为你说得越多模型反而越混乱。正确路径是倒序排查先核对 Manifest 描述是否精准。是不是描述里混入了太多无关信息导致相近技能互相干扰如果两个技能的关键词 overlap 太高模型必然摇摆。再检查路由层打分逻辑。是不是根本没有路由层所有技能描述都一次性塞给模型最后才考虑 Prompt 调整。如果前两个层面都正常还是选错那再考虑在 Prompt 中增加一两条任务约束。我在本地维护技能库时还养成了一个习惯每个技能写一个“伪对话测试”即用三至五条典型用户语句直接跑一次离线 mock 调用检查技能是否被触发、参数是否解析正确、返回消息是否能让模型顺利接话。这些测试每次改动技能定义后会重跑一遍成本极低但能挡住大部分回归问题。技能库这件事的本质就是用工程手段把“模型发挥不稳定”这一特性约束在可控范围内。你没法改变模型生成 JSON 的概率分布但你可以通过标准定义、注册路由、错误心智设计把不稳定性挡在关键业务之外。对我而言agent-skills最终沉淀下来的不只是一堆技能代码而是一套“如何与模型协作”的接口哲学——给模型尽量少的自由度它才能给你尽量高的可靠性。