1. 项目概述为什么需要一套“Agent 技能体系”先聊个现象。最近一两年做 Agent智能体的人越来越多但真正能把 Agent 落到业务里的人反而不多。大部分 demo 都卡在同一个地方模型知道该“调用工具”但不知道具体该调哪个、参数怎么填、调完之后结果怎么处理。你把十几个 API 塞给它它反而开始乱选、乱编参数甚至两个技能来回调用死循环。我见过最多的失败现场就是所谓的“Agent 连环调用”——模型把一个接口的返回值当成另一个接口的入参一路错下去最后输出一段完全不相干的内容。agent-skills 这个项目本质上就是在解决这个痛点把 AI Agent 需要执行的任务抽象成一套可注册、可发现、可调度、可评估的技能库。它不是一个具体的聊天机器人也不是某个单一工具而是一套关于“怎么让模型稳定地干活”的方法论和工程落地。我还记得第一次给 Agent 接工具调用时的场景。当时我天真地以为只要把函数列表和 JSON Schema 丢给模型它就能精准调用。结果模型确实调用了——但调用的方式完全出乎意料它把两个相似技能的参数合并在一起捏造了一个并不存在的字段然后坚信自己完成了任务。那一次之后我意识到工具调用这件事需要专门设计。这个项目适合谁如果你正在做 AI 应用开发、正在给语言模型接外部能力、或者你团队里的 Agent 已经出现“工具多了就乱”的迹象那这里的思路可以直接拿去参考。如果你刚接触 Agent这篇文章也能帮你建立一个体感技能库不是简单列一堆函数而是要做分类、做描述、做校验、做故障降级背后是一套完整的工程体系。我自己在实践中的体会是Agent 的能力边界很大程度上不是由模型决定的而是由技能库的设计质量决定的。同样的模型技能描述写得好调用准确率能从 60% 提到 90% 以上技能设计混乱再强的模型也发挥不出来。下面我把整个项目的设计思路、实操过程和踩过的坑完整拆开讲。2. 技能库设计先想清楚“模型是怎么理解技能的”2.1 不要急着写代码先理解大模型的工具选择机制大模型选择技能的本质是一个“阅读理解 语义匹配”的过程。模型看到用户的请求再看到你提供的所有技能描述然后通过语义相似度决定调用哪一个。这意味着技能描述的质量直接决定选择的准确率。有一个常见的误区就是很多人在写技能描述时只写功能不写“使用边界”。比如你给模型注册一个“发送邮件”的技能描述写了“发送邮件给收件人”模型就会在用户说“帮我把这段话发给小李”时调用它但问题是小李的邮箱是什么如果上下文里没有模型就会编造一个。这种问题的根源不在于模型不够聪明而在于技能的触发条件和参数约束写得不够清晰。我在项目里采用的写法是“四段式描述”技能做什么、在什么场景下使用、什么场景下禁止使用、调用前需要哪些前置条件。举个例子这是基于常见实践的补充写法技能名称send_email功能描述向指定收件人发送一封邮件。仅当用户明确提供收件人邮箱地址或已在系统中绑定该联系人时使用。当收件人邮箱缺失、不确定收件人身份时禁止调用应主动追问。前置条件sender_email、recipient_email 均已通过校验。这样写的好处是模型在模糊场景下会优先选择“追问”而不是“瞎猜”。实测对比过加了边界描述之后误调用率下降了大概三成。2.2 技能粒度的取舍粗了没法复用细了调度混乱这个可能是整个项目里最让我纠结的部分。技能粒度直接决定了 Agent 的调度效率和维护成本。我第一版设计时走了两个极端。第一版走的是“全原子化”路线。我把每个底层操作都拆成一个技能比如“获取用户信息”“获取订单列表”“获取商品详情”……结果技能总数到了八十多个。模型每处理一个请求都要从八十多个技能里做一次全量匹配不仅响应变慢而且频繁出现相似技能的混淆——比如“获取订单列表”和“获取订单详情”描述稍微接近一点模型就选错。第二版我吸取教训走了“全业务化”路线。我把每个完整的业务流程封装成一个技能比如“完成一次下单”“处理一次退款”。这样技能数量倒是少了但复用性几乎为零。用户只是问了一句“退款多久到账”模型却无从下手——因为这个问题既不是完整退款流程也没有单独设计“查询退款进度”的技能。最后的折中方案是把技能分成三层原子技能层直接对应单一外部操作粒度最小比如“调用数据库查询”“调用外部 API 获取天气”。这一层只做一件事不做业务判断。组合技能层把多个原子技能按业务逻辑串联起来比如“用户下单”包含“校验库存”“创建订单”“扣减库存”“发送通知”四个原子操作。这一层负责编排不接触具体实现细节。领域技能层面向特定业务场景的入口比如“客户服务”“商品运营”内部封装该领域的高频组合逻辑并暴露少量可配置参数。这种分层的好处是模型在绝大多数情况下只需要从领域层或组合层里做选择选择空间小了、准确率自然高了。只有当组合技能内部的某个步骤需要动态决策时才向下层取用原子技能交给独立的子 Agent 处理。经过分层之后单次调用的模型决策范围从八十多个技能缩减到十几个响应速度和准确率都有明显提升。2.3 技能描述和参数声明写给模型看的“用户手册”技能描述是写给大模型读的所以要用模型“听得懂”的语言。什么叫模型听得懂就是用明确的动词、明确的名词不要用模糊的形容词。这里有一个反面教材和正面教材的对比。反面教材description: 处理用户的信息需求。正面教材description: 当用户询问指定城市的实时天气时调用。城市名必须是中国境内行政区划名称如‘北京’。若用户未给出明确城市名应先追问用户所在地。。从反面教材到正面教材的区别在于三点触发条件明确、参数范围明确、异常处理路径明确。大模型在选择技能时实际上是拿用户输入和技能描述做语义匹配描述里包含的关键实体越多匹配就越精准。参数声明这块我也踩过好几个坑。最开始我照搬 REST API 的字段命名比如cust_id、ord_amt结果模型经常填错。后来改成语义化命名比如customer_id、order_amount准确率立刻上来了。另外JSON Schema 里的 description 字段不要留空每一个参数都要写清楚含义、格式、取值来源比如“订单编号用户在订单列表中看到的 16 位数字编号”。3. 实操落地如何从零实现一个可用的技能库3.1 整体架构注册表、调度器、执行器、审计器真正的 agent-skills 项目在工程上可以拆成四个核心模块注册表Registry、调度器Dispatcher、执行器Executor、审计器Auditor。这四个模块各自职责单一合起来就构成了完整的技能生命周期。注册表负责维护技能元数据包括技能名称、描述、参数 Schema、版本号、依赖关系、启用状态。它只做存储和索引不执行任何业务逻辑。调度器负责接收用户的请求把请求、历史对话上下文、技能描述列表组合成提示词交给大模型做一轮意图识别和技能选择然后返回选中的技能名和参数。执行器负责按照调度器的输出调用真实的服务把 JSON 参数转换为实际函数调用拿到结果后再统一包装成固定格式回传给调度器。审计器负责记录每一次技能调用的情况包括调用了哪个技能、参数是什么、返回结果是什么、耗时多久、是否成功。审计日志是后续排查问题和优化技能的基石。用 Python 实现的框架大致长这样这是项目里的核心思路代码基于常见实践整理from typing import Any, Callable, Optional from pydantic import BaseModel, Field class Skill(BaseModel): name: str description: str parameters: dict enabled: bool True version: str 1.0.0 handler: Optional[Callable] None class SkillRegistry: def __init__(self): self._skills: dict[str, Skill] {} def register(self, skill: Skill) - None: if skill.name in self._skills: raise ValueError(f技能 {skill.name} 已存在请先注销再注册) self._skills[skill.name] skill def get_skill(self, name: str) - Skill: skill self._skills.get(name) if not skill: raise KeyError(f技能 {name} 未注册) return skill def list_skill_descriptions(self) - list[dict]: return [ {name: s.name, description: s.description, parameters: s.parameters} for s in self._skills.values() if s.enabled ]注册表的核心要点是冲突拒绝同一个技能名重复注册时直接报错防止线上配置被意外覆盖。这个看起来简单的逻辑在多人协作时能避免非常多的问题。3.2 调度器的实现控制好提示词的结构调度是整个技能库的引擎难点在于构造一个让模型“不跑偏”的提示词结构。我经过多轮调整最终固定下来的提示词包含五个部分角色设定明确 Agent 的类型比如“你是一个订单助手负责处理用户的订单查询和退款请求”。技能列表把注册表里的技能描述按统一模板渲染出来每条技能占一个区块。用户请求原文展示用户输入不对用户输入做任何预处理。历史上下文摘要将之前的对话内容压缩成摘要避免超出上下文窗口这里基于常见实践补充如果对话太长优先截取最后 N 轮保持摘要与当前请求语义相关。输出约束要求模型只返回一个 JSON 对象格式固定为{skill: 技能名, arguments: {...}}。当模型认为没有合适的技能时返回{skill: fallback, arguments: {message: 需要向用户澄清的内容}}。这里有个关键细节输出格式约束要用 JSON 而不是自然语言。模糊的输出格式是调试时最痛苦的来源。我曾经让模型“用自然语言说明你的决定”结果它返回了“我觉得应该调用查询接口因为用户想知道天气情况……”后面我不得不写一堆字符串解析逻辑既脆弱又容易出错。3.3 执行器的错误处理与降级策略执行器层面最容易出问题的地方是对技能返回结果的处理。很多大模型应用有个通病拿到结果直接拼进下一轮对话完全不管结果的类型和结构。这在 B 站或知乎上你可能见过无数次翻车案例——模型给用户返回了一个 JSON 原始字符串然后还加一句“以上是您要的信息”。我的处理方式是在执行器里统一包一层标准响应结构然后再决定是否把结果送回给模型class ExecutionResult(BaseModel): skill_name: str status: str # success | failed | retryable data: Any None error: Optional[str] None def execute_skill(skill: Skill, arguments: dict) - ExecutionResult: 通用的技能执行包装器基于常见最佳实践补充的关键逻辑。 try: # 参数校验强制校验不通过的参数不上送 validate_arguments(skill.parameters, arguments) # 执行业务逻辑 result skill.handler(**arguments) return ExecutionResult(skill_nameskill.name, statussuccess, dataresult) except ValidationError as e: return ExecutionResult(skill_nameskill.name, statusfailed, errorf参数校验失败: {e}) except RetryableError as e: return ExecutionResult(skill_nameskill.name, statusretryable, errorstr(e)) except Exception as e: return ExecutionResult(skill_nameskill.name, statusfailed, errorf未知异常: {e})这里需要特别解释一下retryable这个状态。它是用来处理“这次失败不代表下次也会失败”的情况比如外部 API 短暂超时、数据库临时连接不上。这类错误不应该让模型去“反思”而应该直接走重试逻辑指数退避重试比如 1 秒、2 秒、4 秒最多三次。不要让大模型决定是否重试——模型介入会引入不确定性重试逻辑交给代码更稳定、更快。3.4 审计日志排查问题的唯一抓手最后是审计器。很多人觉得审计日志就是简单打个日志实际上它在技能库里的价值被严重低估了。我之所以把审计从普通日志里单独拎出来是因为 Agent 的问题往往不是线性发生的。审计日志需要记录的信息包括请求 ID、技能名、选中的大模型版本、提示词版本、参数快照、执行耗时、返回状态。有了这些当某个技能调用准确率突然下降时你可以回查是哪次提示词改动导致的是哪次模型更新导致的是哪批参数格式变化导致的。横向对比是所有排查手段里最有效的一条。我强烈建议在技能库上线后自动统计这几个指标技能调用准确率调用结果成功数 / 调用总数、参数首轮校验通过率、误调用率模型选择了技能但用户反馈完全无关、平均响应耗时。这些指标直接反映了技能库的健康度。4. 踩坑实录Agent 技能实践中遇到的六大典型问题4.1 误调用模型“以为”自己理解了技能这是我在项目中遇到最频繁的问题。典型场景是用户问“帮我看看明天上海天气怎么样”模型却调用了“酒店预订”技能并且自信地输出了一个空房间列表。原因是什么是技能描述中的“城市”和“日期”关键词和用户问题里的“上海”“明天”在词面上有重叠导致模型被误导了。排查方法看审计日志中模型的“选择理由”如果有记录的话。如果没有记录建议在调度器提示词里临时加一个reason字段强制模型写出选择依据。这不是为了给用户看而是为了让你定位问题。我曾经通过这一招发现模型“看到”了技能描述里根本没有的语义关联选错的原因完全不可理喻——找到根因后解决方案就是把描述改得更窄、更具体不给语义联想留空间。4.2 参数幻觉模型编造不存在的参数值参数幻觉是和误调用并驾齐驱的大坑。模型在技能参数缺失时不是选择追问而是用看似合理的数据去“补全”。比如技能要求order_id模型找不到时会捏造一个20250501格式的数字并且振振有词地当作真实数据传下去。解决办法有三个层级调度层在提示词里强调“如果任何必填参数找不到不要猜测使用 fallback 技能进行澄清”。校验层执行器的参数校验强制打开并在 Schema 里给参数加pattern约束比如订单编号必须是 16 位数字格式不对就直接拦截代码里我已经展示了validate_arguments这一步。兜底层系统设计上让 e 级服务即使收到参数也大概率报错形成一个“错误闭环”。三层都做了之后参数幻觉的比例会大幅下降但我不敢说能完全消除——大模型的预测本质决定了它总有概率产出错误内容工程只能降低概率、拦截错误、快速恢复。4.3 来回调用死循环Agent “纠结”在两个技能之间比单个误调用更严重的是死循环。模型在技能 A 的输出里发现了“需要再查一个数据”于是调用技能 B然后在技能 B 的输出里又发现了“还需要查另一个数据”于是再次调用 A……如此反复直到超过最大迭代次数被强制终止。这个过程既浪费成本又给用户极差的体验。我在这个项目里加的硬性限制是单次用户请求最多执行 5 次技能调用超过后强制结束回复用户“这个问题太复杂我已经做了部分处理需要您进一步确认”。同时调度器在每一轮都会把之前已调用过的技能名追加到上下文里并在输出约束中明确提示“不要重复调用以下技能A、B、C。”实践证明追加“已调用列表”比只设上限有效得多因为它直接干预了模型的决策依据。4.4 上下文污染历史对话干扰技能选择有些用户会在同一个会话里先聊 A 事再聊 B 事导致上下文里同时存在多个主题。模型在做技能选择时可能被较早的主题干扰。比如用户先问了“退款流程”然后隔了几轮又问“现在几点了”模型却仍然试图调用退款相关的技能。处理这个问题的常用思路是在做技能选择前单独构造一个“当前意图”判断步骤——先用一个轻量模型判断“用户当前最想做什么”再用当前意图去匹配技能。相当于把“从所有历史对话中提取意图”和“根据意图选技能”两个步骤解耦了。实测这个方法能显著减少跨主题干扰代价是多一次模型调用——但换来的是稳定性的大幅提升。4.5 长尾技能被遗忘数量一多模型就“视而不见”当技能数量超过一定阈值后我实测大概在 30 个以上开始出现模型开始表现出“长尾遗忘”倾向它总是倾向于选择描述更详细、更靠前的技能频率低的技能逐渐被无视。这不是模型存心偷懒而是提示词里塞的技能列表太长注意力机制在分配权重时自然偏向高频信号。几种可行的方案聚类预选在把技能列表送给模型前先做一次粗筛。用嵌入向量把用户请求和技能描述做相似度计算选出最相关的 Top 5 技能再让大模型在这 5 个里做精细选择。这种做法类似于搜索引擎的召回、精排思路也是我最终采用的方案。折叠输入长尾技能默认折叠除非用户关键词命中否则不展开。周级热门技能排序把近期调用频次最高的技能置顶但要注意避免“马太效应”导致低频技能更被遗忘。4.6 提示词版本管理模型升级后技能突然“失灵”最后这个坑我提一下很多人容易忽略。Agent 技能库的配置不仅包括代码还包括提示词模板、技能描述、模型版本这三者耦合非常紧密。我有一次把一套运行稳定的技能库从旧版模型换到新版模型结果技能调用准确率从 90% 掉到 70%整个过程毫无征兆。排查方式很简单审计日志里把模型版本和提示词版本作为字段存起来如果线上配置出现“某个版本启动后指标下降”可以快速回滚到上一个模型版本再逐步验证提示词哪里不适配新模型。模型版本的变更一定要当作一次正式发布来管理而不是后台偷偷切换。5. 后续扩展的几个方向5.1 从静态技能库走向动态技能注入静态技能库的维护成本会随着技能数量增长而增加。我目前实验中的一个方向是几天没被调用的技能自动降级为“低活跃”状态不再进入默认的技能列表。相反用户经常请求、但在技能库里没有匹配的能力会被记录为“技能缺口”汇聚成待开发的 backlog 清单。5.2 把技能评估做成一等公民一个技能好不好不能只看上线当天的效果。我建议对每个技能建立独立的评估基线准备一批测试用例比如 50 个典型提问每次技能描述或提示词有改动时跑一遍回归测试对比技能调用准确率的变化。这一步相当于软件工程里的 CI/CD——没有测试支撑你永远不知道哪次改动破坏了什么。5.3 AI 生成技能草稿的尝试另外一个我还在摸索的方向是让模型根据“技能缺口”直接生成技能草稿。模型可以给出功能说明、参数 Schema 和建议的产品提示词人工审核后放入沙箱环境测试测试通过再上线。整个过程相当于把“写技能”这件事也从手写变成了半自动——不过生成出来的东西一致性还需要人工把关纯自动上线目前还不太现实。5.4 技能编排的可视化与观察性最后再补充一个小建议拿到这些经验之后先挑一个体量最小的业务场景试比如只维护 5 个技能跑通整个注册、调度、执行、审计链路再逐步加技能。不要一上来就做 50 个技能的大库——调度混乱时排查的难度会随着技能数量指数级上升先从 5 个里出成绩比在 50 个里摸爬滚打要快得多。根据我个人经验agent-skills 这套设计真正核心的部分并不是代码而是“为模型写使用说明”的思维方式。每一次技能描述、每一条参数约束、每一条边界条件本质上都是在帮模型建立一个更准确的决策空间。技术这块没有太多玄学认真对待每一个细节就能收到回报。