1. 项目定位与整体思路Agent 的“可插拔技能库”到底该怎么做最近在做一个内部代号为agent-skills的实验项目目标很朴素给智能体Agent搭一套可插拔、可复用、可评估的技能库把零散的工具调用收拢成结构化的能力单元。断断续续折腾了三个版本从最开始的一堆 if-else 写死在 Prompt 里到后来抽成独立的 Skill 模块再到现在的动态加载、组合编排整个过程踩了不少坑也积累了一些还算成熟的做法。这篇文章就把项目从头到尾的设计思路、核心机制和实操细节展开聊一聊希望对正在做 Agent 应用的开发者有参考价值。先说清楚我理解的“技能”和普通“工具”的区别。工具是一个可被直接调用的函数比如查询天气、计算两个数相加、发一条消息。技能则是一个更完整的自包含单元它除了执行逻辑本身还包含能力描述、参数契约、依赖关系、资源消耗声明以及权限要求。为什么要把一个简单的函数调用弄得这么重因为在 Agent 场景里模型需要先“看懂”这个能力才知道什么时候该调它、该怎么把参数填对。一段只写了一行函数签名的主程模型经常要么误用、要么干脆不用。技能库解决的问题实质上就是“让 Agent 能够自己发现和正确使用工具”。这个项目适合谁来参考两类人最合适。第一类是正在搭 Agent 应用、发现代码里工具函数逻辑越来越乱的开发者技能库能帮你把散落的功能点收敛成统一结构。第二类是团队内要做 Agent 能力共享的人一个维护良好的技能库能让团队里每个人都在同一个能力底盘上做上层应用而不是各自写各自的脚本。如果你只是在本地跑个一次性小 Demo、总共就两三个函数那确实没必要上这套东西——我前几版就是这么过度设计然后推倒重来的。2. 技能的核心结构设计一份让模型能看懂的“说明书”2.1 技能描述规范Description 是给模型看的第一张脸agent-skills的第一版协议其实很简单一个 Skill 就是一个文件夹里面有一个skill.yaml和一段处理逻辑。但真正开始用以后发现整个协议里最重要、也最容易被低估的是description字段。一开始我们只写“根据关键词搜索公开网页返回标题和摘要”模型用起来经常不理解参数边界。后来改成带约束条件的完整描述“根据关键词搜索公开网页内容返回标题、链接和摘要列表。keyword 建议为 2 到 10 个字过长的查询请先做关键信息抽取。limit 取值为 1 到 10默认 5。”改完之后调用成功率明显上升。所以技能描述的第一原则写清楚能力范围、参数偏好和典型使用场景并且用短句排列避免一段长文本直接把模型的注意力稀释掉。我们甚至在内部规范里要求每条 description 不得超过 80 个中文字符写不下的信息放进 Parameter 字段。这里有个很生活化的类比技能描述就像家电说明书上的“功能速览”用户模型先看它再决定要不要用这个功能。要是说明书写得模棱两可性能再强也会被闲置。2.2 参数协议与校验把“类型对齐”这件事提前到加载阶段参数协议是技能库和普通工具调用最大的差异点。普通函数调用靠开发者的常识保证参数类型正确但 Agent 场景里参数是由模型生成的类型和取值范围都可能偏离预期。我们在每个skill.yaml里声明parameters每个参数必须包含type、required、description可选包含default和enum。框架在技能加载阶段就生成一个 JSON Schema 校验器在运行前先做一次参数检查避免脏参数直接打到下游服务。分享一个实际经验数值型参数一定要显式声明上下限enum能限定的就限定不要指望模型自动理解“这个数字别传太大”。曾经有个归档类技能limit 参数本来应该取值 1 到 50结果模型在一次长文任务里传了个 500直接把下游接口拖垮。加校验之后如果模型传的数值超范围框架会自动 clamp 到合法区间同时记录一条 warning既保证任务不中断也方便后续看模型对协议的理解是否到位。2.3 执行器接口与上下文传递一切围绕 SkillContext执行器用一个统一接口来管理def handler(ctx: SkillContext, params: dict) - SkillResult: ...SkillContext是运行时的核心对象它在一次任务里贯穿所有技能调用。里面包含了任务级别的 trace_id、调用者身份、当前技能名、资源限制阀门以及一个只读的共享状态区。所谓只读是指技能之间不允许直接互相写对方的输出只能通过上下文里的结果引用或显式传递的数据流来交互。这样设计是为了防止技能之间耦合A 技能偷偷改了 B 技能的中间状态排查时根本找不到是谁动的。SkillResult也做成了统一结构必含ok、output、duration_ms、logs四个字段。所有技能无论内部多复杂对外只暴露这四个维度。有没有这个统一结构在后面的编排、追踪和评估里差别非常大。早期版本每个技能自己定义返回格式有的用 dict 带 items有的直接返字符串写编排逻辑的时候到处做类型判断苦不堪言。3. 运行时管理与资源控制技能库不能成为失控的入口3.1 超时、重试与熔断技能跑起来以后最直接的问题是超时。一个技能可能调用外部接口也可能做本地计算无论如何都要有明确的超时上限。我们在运行时给每次调用设置三层保护单次调用超时、执行器的总时长预算、以及整个任务的最大时长预算。单次超时默认 5 秒如果技能内部逻辑特殊需要更长时间必须在skill.yaml里显式声明max_timeout_ms否则框架直接拒绝加载。超时后的处理也分层。幂等类技能比如读操作允许自动重试一次非幂等类技能比如创建订单绝不重试而是把控制权交还给上层的决策器让模型自己判断是换一种做法还是宣告失败。熔断则是基于连续失败率做统计某个技能在 60 秒内失败率超过 40%自动打开熔断开关后续调用直接快速失败不再消耗时间预算。这个机制救过我们很多次有一次下游服务半挂不挂每个请求都等满 10 秒超时如果没有熔断整条任务链路会被拖到全线超时。3.2 沙箱与权限声明技能不是越强越好权限问题是我个人认为最容易被初学者忽略、但项目做到中后期一定会回来补的一环。agent-skills在协议里加入permissions段技能声明自己需要什么资源是否需要出网、是否能写本地文件、允许访问哪几个具体域名、是否可以执行子进程。运行时根据声明做沙箱化执行没声明的一律拒绝。这样做的直接收益是即使某个技能的代码有 bug或者模型在极端情况下把技能的参数构造得恶意嵌套破坏面也被限制在一层薄薄的权限边界内。有一次我在调试一个 PDF 处理技能因为代码里写了个shutil.rmtree用来清理临时目录路径变量被模型注入成了根路径差点把所有临时文件全删了。事后反思如果当时技能声明里没开“写临时目录”这个权限运行时早在调用点就拦住了。权限声明还能帮模型做粗粒度的选择一个技能要访问外网另一个纯本地计算模型在规划阶段就会倾向用轻量的那个。3.3 动态加载与热更新技能库从“写死”走向“扩展”技能库的加载机制我们也做了几次迭代最终实现的方案是技能以目录为单位放在skills/下框架启动时扫描所有子目录读取skill.yaml注册进内存索引。新技能放进去通过一个管理接口触发热加载不用重启主服务。这个能力在开发调试期尤其好用改完一个技能直接重载测试不用反复启停容器。但动态加载也要求更严格的规范。我们在加载流程里做三个检查YAML 结构合法且协议版本兼容、handler 引用的依赖模块存在、声明的权限没有超过运行时策略允许的最大边界。任何一个检查不过该技能会被置为“加载失败”状态并在健康检查接口里暴露原因而不是静默跳过。这样做的原因是静默失败比显式失败可怕得多——某次线上排查半天找不到某个技能为什么不可用最后发现是 YAML 缩进写错框架把它跳过了但日志里完全没有痕迹只有健康检查里多了一个加载失败计数。4. 技能编排与组合从单技能调用到工作流4.1 依赖关系声明顺序不能被模型“猜”技能库真正释放生产力的是组合编排。单个技能解决单点问题组合才能解决真实任务。agent-skills的编排支持两种形式声明式 YAML pipeline 和命令式 Python 编排。声明式适合固定流水线适合已经验证过的稳定路径命令式适合需要分支判断的动态逻辑。先说声明式。每个编排文件定义成一个pipeline里面列出技能调用序列并声明每个技能的输出如何映射到后一个技能的输入。关键点在于依赖关系必须显式声明不能靠技能名字猜顺序。我们早期吃过亏两个技能之间存在隐式依赖结果在并发执行时数据集还没准备好就去消费报错还特别隐蔽只有在高负载时才偶现。显式声明之后运行时可以做两件事构建有向无环图做依赖检查发现环直接报错把没有依赖关系的技能做并行执行整体耗时大幅下降。pipeline: content_summarizer steps: - id: fetch skill: content_fetcher params: url: {input.url} - id: clean skill: text_cleaner input: {fetch.output} - id: summarize skill: llm_summarizer params: text: {clean.output} max_tokens: 3004.2 数据流与变量引用设计一个让技能之间不打架的传递规则数据流设计是编排里最微妙的部分。我见过一些 Agent 框架技能的输入可以由上一个技能直接往下传或者靠全局变量互相改结果到了后期根本不知道中间状态是谁改的。agent-skills采用一种约定每个技能的输出放在一个独立的命名槽里下游技能用槽名.字段名的表达式引用但整个引用是只读的。技能只能消费上游槽位里已经存在的数据不能回头修改上游槽位。为什么只读很重要因为一旦允许技能的输出被其他技能原地修改编排的可观测性就没了。你想复现一个问题时同一份上游数据跑两次结果可能不同因为某个副作用把共享数据改了。只读数据流把技能实例当作一个纯函数来看待输入引用加参数输出固定到新槽位排查和录播都会轻松非常多。命令式 Python 编排也给同样的数据流规则只是变了一种语法pipeline(content_summarizer) def run(ctx): raw await ctx.call(content_fetcher, urlctx.vars[url]) clean await ctx.call(text_cleaner, htmlraw.output) summary await ctx.call(llm_summarizer, textclean.output, max_tokens300) return summary.output4.3 条件分支与循环上限执行图越清晰越不容易失控真实任务里很少有从头到尾一条路走完的情况。模型经常需要根据中间结果决定下一步走哪个分支比如“先搜索如果搜索结果不足 3 条就扩大关键词重搜”。为了让这种分支可控我们在编排层引入条件节点的概念一个步骤执行完后可以在配置里声明多个后续分支优先级从上到下匹配第一个命中就走那条路。循环同样需要显式约束。agent-skills里的循环节点必须声明max_iterations默认是 3。不做上限的后果很直接模型有概率陷入自我重复的闭环一个失败的结果反复触发重试在第一个版本里我们只设置了超时保护结果虽然不至于无限跑但也把时间预算浪费得很严重。设置循环上限之后配合上下文里的尝试计数能让模型在几次尝试失败后转向其他策略整体任务完成率反而提升。链路追踪也要配合编排一起做。每个 pipeline 有一个 trace_id每个技能调用都记录父子关系和耗时最后汇总成一份执行轨迹。看轨迹的时候你会很容易发现整个任务耗时的大头在哪一步哪个步骤失败率高哪个分支是死路。我们甚至做了一版把执行轨迹可视化的小工具这一步对排障的效率提升非常大。5. 调试、评估与质量保障让技能库从“能用”到“可靠”5.1 干跑模式与 Mock 依赖技能库上线前最怕的就是真调用外部服务。调试一个搜索技能不想每次都真的去请求外部接口费时又费钱。我们实现了一个 dry-run 模式技能执行时如果检测到开启该模式所有网络类调用都会被一个本地 Mock 拦截器接管返回从录制好的数据里按规则匹配的假响应。这样在本地就能把编排逻辑完整跑通。Mock 的最佳实践是“以录播为主”。把之前在真实环境跑过的技能请求和响应录下来按接口和请求参数摘要索引调试时按固定比例回放。录播的好处是数据真实比手写假响应可信得多。不过需要注意录播数据会过期外部服务改字段了录播还在会导致测试通过但线上失败。所以我们在录制文件里加了过期时间戳超过 7 天的回放会打警告提醒你用新的真实调用刷新数据。5.2 录制与回放排查问题时的时光机另一个让我觉得非常值回票价的功能是录制回放。线上任务执行时框架会把每个技能的真实输入参数、输出结果、耗时和异常信息按 trace_id 落盘。出现问题后直接提取该 trace_id 的录制文件在本地按照相同数据流重放一遍可以在不接触线上服务的情况下复现问题。录制回放对排查模型参数构造问题尤其有用。有一次任务总在第三步失败现场看日志发现模型给技能传了个格式诡异的参数但不知道模型是怎么推理出这个参数的。重放后我们拿到了完整的执行轨迹把上下文里之前的模型输出也打出来才看到是前面某个归纳步骤把数字格式改了导致后续技能解析报错。没有回放这类问题只能靠猜。5.3 技能级评估与回归基线技能库做了一段时间后最大的隐患不是单个技能性能下降而是变更一个基础技能后多个上层任务同时受影响。我们建了一套技能级回归测试每个技能至少有一个最小测试用例集覆盖正常路径、边界参数、异常参数各至少一例组合场景也有端到端的任务样例集每次框架版本或技能逻辑更新后自动跑一遍对比完成率和耗时。评估指标里我个人最关注的不是“任务成功率”一个数字而是两个观察项技能调用是否正确该调用的技能是否真的被调用不该调用的有没有误用以及参数符合率模型生成的参数里有多少比例通过 schema 校验。参数符合率是一个很敏感的指标它能提前暴露 Prompt 里描述是否出问题——如果模型开始频繁传错参数类型多半是技能 description 写得不清楚或者和别的技能描述产生了混淆。这套指标配合埋点统计让我们在迭代版本时心里有底而不是每次发布全凭感觉。6. 常见问题与避坑实录现场排障手册我把项目过程中真实遇到的典型问题整理成了一张速查表每个问题都是踩过的坑现象可能原因解决办法技能加载后模型从不调用description 过于口语化或没有说适用范围改写 description给出典型使用场景和限制条件对比参数符合率模型频繁给枚举参数传新值enum 里没有包含常见值或 description 没强调枚举约束扩充 enum 到业务常见值在参数描述里加一句“仅限枚举值”技能偶发超时下游接口不稳定或技能没做超时声明检查 max_timeout_ms加熔断策略给该技能设置独立超时编排执行顺序不稳定依赖没有显式声明并行执行出现数据竞争在 pipeline 配置里把所有数据引用显式声明用依赖图解析代替名字匹配模型陷入重复循环循环节点没设 max_iterations配置 max_iterations默认 3并在上下文里暴露尝试次数本地录播数据测试通过、线上同样请求失败录播数据过期外部服务字段已变定期刷新录制文件对回放数据加过期告警技能 A 修改了技能 B 的中间数据共享状态被设计成可写切换为只读数据流所有输出写入独立槽位技能之间禁止原地改数据排查问题找不到发生链路日志缺少 trace_id 关联在 SkillContext 中强制贯穿 trace_id落盘所有调用记录并生成轨迹报告还需要强调一个心态问题技能库不是写完就能稳定运行的它需要持续观察。我们项目里有一个每周例行动作拉取本周所有失败的技能调用样本逐条看失败原因区分是模型规划问题、技能实现 bug 还是外部服务波动。大部分问题通过改 description 和补参数校验就能解决真正动核心执行逻辑的情况反而很少。这也印证了前面那句话在 Agent 场景里技能面向模型的那份描述往往比实现本身还需要认真对待。7. 关于 agent-skills 的个人体会与后续打算做这个项目最大的体会是Agent 应用的复杂度并不在模型本身而在如何把离散能力组织得足够规范让模型能正确、稳定地使用它们。agent-skills本质上建立了一套边界技能描述说清楚什么能做参数协议规定怎么做权限声明限制能碰什么编排层控制组合方式录制与评估保证变更可回归。把每个环节都约束住复杂任务才不至于变成一团乱麻。下一步我打算重点做两件事。一是技能仓库的语义搜索当技能数量超过 30 个以后模型在规划阶段选错技能的频率会上升一个好的检索逻辑能先按任务文本召回候选技能二是技能效果的精细化度量不只是成功率和耗时还想把每一步的 Token 消耗、任务完成质量和用户反馈都汇总到一个仪表盘里。这两块做完以后技能库就从一个工程支撑组件变成一个能持续反馈迭代的能力中台。最后送各位两个小建议。一个是在设计技能时时刻问自己“模型看到这份描述能不能在 1 秒内判断该不该用、怎么用”拿这个标准去否定那些过于晦涩的描述。另一个是不要急着把权限放宽按最小必要原则走权限永远比能力更难在出事后再收紧。技能越丰富边界越清晰Agent 这个系统才越可信。