我最早接触 agent-skills 这个概念其实是在调试一个多智能体协作系统的时候。当时我发现自己写的 Agent 越来越臃肿每一个新任务都要在 prompt 里塞进大段大段的工具说明任务一多上下文窗口被吃掉大半模型的理解能力直线下降而且不同 Agent 之间完全没有共用的能力模块改一处逻辑要同时改好几个地方。后来我开始把各种单点能力抽出来做成一个可插拔、可复用、可独立维护的技能库这套方法就是 agent-skills 的核心思路。这篇文章我想把自己在构建和使用 agent-skills 过程中的完整思考、设计方案、落地细节以及踩过的坑整理出来给正在做 Agent 工程化、或者被多智能体能力复用问题折腾的朋友一份可以直接上手的参考。1. agent-skills 项目概述与核心痛点1.1 为什么 Agent 需要一套独立的技能库很多人在刚开始做 Agent 的时候习惯把工具函数直接写死在主流程里或者一股脑把所有 API、代码逻辑、提示词都塞进系统 prompt。早期 demo 阶段这么干确实省事但项目稍微一复杂问题立刻暴露出来。拿我自己之前的一个场景举例当时我需要让 Agent 同时完成联网检索、本地文件搜索、PDF 内容提取、表格数据汇总、定时提醒这几个任务。如果按照传统做法每个 Agent 都要重复配置这些工具而且每个 Agent 的回答风格、参数格式还不一定一致。更要命的是一旦底层工具的接口变了比如某个检索 API 从 v1 升级到 v2我得把所有 Agent 的配置全部翻出来改一遍改完之后还要逐个测试工作量直接翻倍。agent-skills 要解决的正是这个问题把每一个可复用的能力单元抽出来做成标准化的“技能”技能与技能之间松散耦合Agent 可以按需加载、按叙调用。这样整个系统就像一个工具箱Agent 需要哪个工具就拿哪个而不是把整个工具箱背在身上。另外一个隐藏的痛点是提示词长度。现在主流大模型的上下文窗口看起来很大但实际上真正有效的注意力区域依然是有限的。你把几十个工具说明一次性塞进 prompt模型在长上下文中做工具选择时准确率会显著下降尤其是语义相近的工具之间特别容易出现误选。技能库按需加载之后每次只给 Agent 注入当前任务真正需要的几个技能描述工具选择准确率提升非常明显。1.2 这份项目总结适合谁来参考如果你正在做以下几类事情agent-skills 这套思路会比较对路搭建多智能体协作系统希望不同 Agent 之间的能力可以统一调度、避免重复建设做单 Agent 应用但感觉 prompt 越来越长、工具选择经常出错、维护成本越来越高刚入行大模型应用开发想知道正规一点的 Agent 工程是怎么把工具和模型解耦的做企业级 AI 平台需要考虑技能的安全隔离、权限控制、审计日志、版本回滚等生产级问题。我会尽量把原理和实操都讲清楚有基础的读者可以直接跳到第 3 部分看代码实现和参数设计新手建议从头往后顺序读每一步都会有配合解释。2. 技能体系的整体设计与拆解思路2.1 任务拆解与技能原子化构建 agent-skills 的第一步不是写代码而是把业务需求拆成最小的技能粒度。技能粒度怎么定直接决定了整个系统的灵活性和维护成本。粒度太粗比如把“处理文档”做成一个技能那这个技能的输入输出会非常不可控粒度太细比如把“把字符串转成大写”也当技能又会让技能数量爆炸Agent 在技能选择时反而会犯选择困难症。我自己总结了一个判断标准如果一个技能的内部逻辑超过 50 行或者它内部明显包含了两个以上可以独立变化的子步骤那就应该继续拆分。反过来如果一个技能被三个以上不同的场景调用而调用时参数基本一致那说明这个技能本身是独立的原子能力。举个例子。我当时需要 Agent 具备“分析周报并生成摘要”的能力。按粗粒度拆这是一个技能但真正分析它的内部逻辑应该拆成读取文件内容支持 PDF、Word、Markdown、TXT根据文件类型做文本提取和清洗调用大模型生成摘要将摘要保存到指定目录这四个子步骤里面第一、第二、第四都是通用能力被其他任务复用的可能性极高所以应该独立成技能。第三个是核心业务能力但也可以把“模型调用”抽成一个底座技能上层技能只指定模型参数和 prompt 模板不关心底层走的是什么模型。2.2 技能编排与执行管线技能拆完之后下一步要考虑的是技能之间如何编排。agent-skills 的编排逻辑参照了微服务架构里非常成熟的做法技能之间不直接调用而是通过一个统一的调度层来进行。调度层负责三件事接收 Agent 传来的目标描述和上下文根据技能列表和当前上下文决定调用哪些技能以及调用顺序把技能的返回值做标准化处理再回传给 Agent我用的编排方式是“无向技能注册 有向任务管线”。每个技能独立注册到技能中心技能中心维护一份技能元数据清单技能名称、描述、输入 Schema、输出 Schema、版本、依赖关系。当 Agent 收到一个复杂任务时先由调度层做一个简单的意图预判断把任务初步归类再动态检索出候选技能集合最后由大模型基于候选技能描述选择最匹配的技能序列。这种方式比纯靠模型自由选择所有技能要稳定得多。模型的选择空间从几十个技能缩小到三到五个候选技能选择错误率可以控制到很低的水平。2.3 工具选型与技术栈考量agent-skills 的技术栈选择核心考量是三个生态成熟度、运行效率、团队上手成本。我选择了 Python 3.10 作为主语言因为目前大模型应用的开源生态基本集中在 Python无论是 LangChain 还是 LlamaIndex都能很好地配合技能库做集成。Web 框架用的是 FastAPI它的异步性能好pydantic 的数据校验能力也能直接用于技能的输入校验。技能注册中心用的是 Redis 加内存缓存的双层结构Redis 负责持久化和跨进程共享内存负责加速同进程内的频繁调用。向量检索用的是轻量的 SQLite sqlite-vec没有引入重型的向量数据库因为技能数量只要不是上万级别轻量方案完全够用并且部署起来省事很多。如果要跑在异构环境里比如一部分技能依赖 Java 服务一部分技能依赖 Node 服务那我的建议是在技能中心之上再包一层网关用统一 HTTP 协议封装不同语言实现的技能。这一点我下面会详细说。3. 核心实现从零构建可复用的技能库3.1 技能定义与 Schema 设计一个技能在 agent-skills 里的核心定义不只是函数本身还包括一份机器和模型都能读懂的元数据。我设计了这样的等价数据结构你可以直接参考dataclass class SkillSchema: name: str description: str version: str author: str input_schema: dict output_schema: dict tags: list[str] dependencies: list[str] timeout_seconds: int 30 requires_auth: bool False is_async: bool False这里的 input_schema 和 output_schema 是关键。它们不仅仅是装饰实际的作用有三个第一用于大模型理解技能。description 和 input_schema 会拼装成工具说明注入到模型请求里模型看到“技能名 功能描述 参数格式”后就能知道什么时候该调用、怎么调用。第二用于运行时校验。技能在执行前系统会强校验传入参数是否符合 Schema。这一层校验现在看起来很基础但在实际运行中能挡住大量脏数据。我遇到过不止一次模型生成了缺参数或者类型错误的调用请求如果没有这层校验错误会直接炸到业务逻辑里。第三用于技能检索。tags 和 description 会做向量化存入本地向量库检索时按语义相似度召回。为了模型在工具选择阶段不迷路description 必须写清楚技能“做什么、不做什么、在什么场景下用”。比如一个技能叫“上传文件”描述只写“上传文件”就不够好写“将用户提供的文件上传到对象存储并返回访问 URL仅支持不超过 50MB 的文件”才是合格的描述。3.2 技能的注册、发现与热加载技能注册中心在我的实现里承担两件事维护技能元数据响应技能调用请求。注册的流程比较简单每个技能包在启动时调用注册接口把自己的 Schema 注册进中心。为了支持热加载所有技能实现都放在一个插件目录下用 importlib 做动态导入这样可以做到不修改主进程代码直接新增技能文件即可生效。# skills_dispatcher.py import importlib import pkgutil from typing import Dict class SkillDispatcher: def __init__(self): self.registry: Dict[str, SkillSchema] {} self.handlers: Dict[str, callable] {} def discover_and_register(self, package_name: str): package importlib.import_module(package_name) for mod_info in pkgutil.iter_modules(package.__path__): mod importlib.import_module(f{package_name}.{mod_info.name}) if hasattr(mod, skill_schema) and hasattr(mod, handler): self.registry[mod.skill_schema.name] mod.skill_schema self.handlers[mod.skill_schema.name] mod.handler print(f[Skill] loaded {mod.skill_schema.name} v{mod.skill_schema.version}) def execute(self, skill_name: str, **kwargs): if skill_name not in self.handlers: raise SkillNotFoundException(skill_name) schema self.registry[skill_name] # 执行前 schema 校验 validated_input validate_against_schema(schema.input_schema, kwargs) result self.handlers[skill_name](**validated_input) # 执行后输出校验 return validate_against_schema(schema.output_schema, result)这套代码本身不难但有几个细节值得注意。技能的 handler 函数是普通同步函数还是异步函数必须在 is_async 字段里标明否则在 asyncio 事件循环里直接调用同步函数会导致整体性能下降。另外一个细节是技能执行必须有超时控制。我在调度器里给每个技能单独设置了 timeout_seconds超时的技能直接返回错误不让坏技能拖垮整个 Agent 会话。3.3 沙箱执行、鉴权与安全技能一旦多起来安全就是一个绕不开的问题。你从网上拉一个现成技能包回来里面如果有恶意代码一执行可能就把整个系统搞坏了。即使团队内部开发的技能像执行 shell 命令、访问数据库、调用外部 API 这类高危能力也必须有精细到技能级别的权限管控。我的安全方案分了三层第一层技能分级。我把技能按风险等级分成 L1、L2、L3 三级。L1 是纯计算、无副作用的能力比如文本格式化、时间换算、数学计算L2 是访问内部系统只读接口的能力比如查询数据库、读取文件L3 是产生写操作或外部调用的能力比如发邮件、写库、调用第三方付费 API。L1 技能不设权限限制L2 技能要求用户身份在可访问名单内L3 技能必须经过显式授权且执行前弹出确认。第二层隔离执行。L3 技能默认跑在一个受限的子进程里这个子进程没有网络访问权限也没有本地文件写入权限只有明确开放的沙箱目录可写。用到了 Python 的 resource 模块限制 CPU 时间和内存防止技能死循环或者内存泄漏把宿主机拖垮。第三层审计追踪。所有技能调用都记录完整日志包括调用者、时间戳、参数摘要、返回状态、耗时。这些日志在出问题时是排查事故的关键线索。值得提一句参数摘要不应该记录完整明文尤其是包含敏感信息时我习惯直接用 SHA-256 对参数做哈希摘要只记录指纹用于追踪不记录具体内容。3.4 缓存、错误处理与可观测性很多技能处理的是重复度很高的请求。比如“从文件路径读取全文”这种技能如果同一个文件被反复请求解析每次都重新读取一遍浪费是显而易见的。我给技能调度层加了一级内容缓存缓存 key 由技能名 参数哈希组成默认缓存 5 分钟L1 纯计算技能可以缓存更长时间。这里要注意的是有外部副作用的技能比如查询天气不能随便用缓存否则用户会拿到过期的数据。错误处理方面我给技能调用统一设计了异常结构这是功能实现之外很重要的一个环节class SkillExecutionError(Exception): def __init__(self, skill_name, error_type, message, recoverableTrue, retry_count0): self.skill_name skill_name self.error_type error_type self.message message self.recoverable recoverable self.retry_count retry_count super().__init__(message)错误类型我分成了这么几类SchemaValidationError参数校验失败直接返回 Agent让模型重新构造参数不需要重试TimeoutError执行超时按策略做一次重试如果还超时就返回错误提示ExternalAPIError调用外部接口失败根据外部接口的返回状态决定是重试还是降级ResourceLimitError资源受限直接返回错误要求用户减少数据量或提升配额。为了观察技能的运行状态我还在调度器里内置了一个简单的监控面板展示技能调用次数、失败率、平均耗时P50/P95、缓存命中率。这些指标对我做技能迭代的价值非常大比如我看到某个技能 P95 耗时是 P50 的五六倍就说明它在线程竞争或 IO 等待上出了问题值得深入优化。4. 技能质量评估与持续迭代4.1 多维评估体系技能做出来了怎么判断它好不好用我一开始只看功能跑不跑得通后来发现这是一种错觉。有些技能功能上完全正常但放到真实 Agent 场景里模型根本不知道该什么时候调用它或者调用了之后输出格式让 Agent 解读困难这时技能的效果就是零。后来我建立了一个多维评估体系从五个维度给技能打分第一个维度是任务成功率。给定一组标准测试输入技能能否返回符合预期的输出。这个是最基本的。第二个维度是调用准确率。在一个模拟 Agent 环境里准备好多个相似技能和干扰技能让模型自主选择技能看模型在遇到目标任务时能不能准确命中对应技能。这个维度衡量的是技能的语义清晰度如果模型频繁选错那多半是技能描述或参数说明不够有区分度。第三个维度是响应延迟。技能从被调用到返回结果的总耗时重点关注 P95 和 P99高百分位耗时比平均耗时更能发现问题。第四个维度是 token 消耗。调用该技能消耗的大模型输入 token 数因为技能描述是注入到上下文里的这个成本经常被忽略但技能一多它对成本和上下文质量的影响不容小觑。第五个维度是失败恢复率。技能在出错后经过自动重试或参数纠正后能成功恢复的比例。每次迭代技能我都跑一遍这五个维度的评估对比前后差异而不是只看功能有没有实现。4.2 回归测试与版本管理技能库的版本管理是 agent-skills 里最容易做砸的部分。一开始我偷懒技能文件直接覆盖式更新结果有一次改了一个底层共享技能的内部逻辑没注意到它被其他五个技能依赖上完线之后五个技能全部异常。那天排查到半夜最痛苦的还不是修 bug而是根本说不清是从哪个版本开始坏的。后来我彻底改了策略把技能版本管理纳入了整个开发流程。现在每个技能包里固定带一个版本号升级技能时只新增不覆盖旧版本保留在技能中心里。调用方如果指定了技能版本就固定调用该版本不指定的话默认调用最新稳定版。另外技能的依赖关系和影响面要做成可查询的改任何一个技能之前先查它的反向依赖列表确定不会影响其他技能才动手。回归测试这件事我从标准的软件工程里搬了过来每个技能有三个固定流程单元测试验证单个技能自身逻辑输入边界条件、异常参数全覆盖集成测试在一个完整 Agent 场景里验证技能和模型、调度器之间的配合回归测试旧版本技能跑通过的测试用例新版本必须全部再跑一遍不通过不允许发布。这套机制做起来会多花一些时间但长期看绝对值。技能库里的技能一旦积累到两位数没有这套机制做任何改动都像在雷区走路。5. 实战过程与关键细节复盘5.1 从零落地的完整流程记录我把这次从零构建 agent-skills 的完整流程用一条时间线串一下这样你可以照着复现。第一阶段是技能盘点与设计大概花了两天。我把所有需要 Agent 支持的业务场景列出来逐一拆解成最小子步骤然后合并同类项、剔除不必要的技能最终整理出二十三个技能涉及文档处理、数据查询、外部接口调用、消息通知这几大类。每个技能写好 Schema 初稿并给所有描述设置了统一的写作规范。第二阶段是底盘建设也用了两天。写好了注册中心、调度器、Schema 校验、缓存、权限控制、监控面板这些基础设施。这个阶段我在本地用一个小测试场景验证了完整链路注册一个技能、调用一个技能、校验输入输出、记录日志全部通了一遍。第三阶段是技能实现花的时间最多五天。二十三个技能分成三批每批次实现完之后立刻跑单元测试和集成测试。这段时间我发现技术本身不难难的是把技能边界和依赖关系梳理清楚。第四阶段是 Agent 集成与评估两天。把技能库接入到我正在做的多 Agent 系统里跑完整流程。评估之后淘汰了两个描述不清的技能合并了三个功能重叠的技能优化了四个技能的超时设置。整个过程中我用的是自己搭建的轻量环境一台 8C16G 的开发机代码仓库用 Git技能中心用 Redis SQLite调度服务用 FastAPI 跑在 Docker 里。这个组合对个人项目和中小团队来说足够了。5.2 踩坑记录与关键细节技巧这条路走过来有几个坑印象很深分享出来供你参考。第一个坑技能描述写得太抽象。早期我有几个技能的 functions 描述写得非常简洁比如“获取用户信息”“获取订单信息”。结果模型在任务里需要查询用户时经常调用“获取订单信息”。后来我把所有技能描述重写统一加入触发场景、输入限制、输出样例三要素调用准确率从 81% 提到 97%提升非常明显。坚持一个原则描述要让模型在不确定时敢选你。第二个坑技能超时设置太粗放。我最初所有技能统一设成 60 秒超时。结果一个 L1 纯计算技能因为线程池被占满排队等了快一分钟才执行Agent 会话直接超时。后来我按技能的实际耗时分布重新设定超时纯计算技能 5 秒IO 类技能 20 秒外部调用技能 60 秒网络文件下载类技能 120 秒。给技能定超时之前先跑一轮性能基准测试。第三个坑缓存导致的数据过期。我给“查询用户余额”这种技能加了 5 分钟缓存结果用户反映余额变了但页面显示旧数据。后来我把所有涉及金额、库存、状态类的技能全部设置为禁止缓存只在纯查询类且可容忍延迟的技能上保留缓存。原则是只要数据可能因外部操作而改变就不要轻易缓存。第四个坑技能目录混乱。技能数量一多技能文件组织不规范查找和维护效率就会骤降。后来我强制规定了项目目录结构每个技能占一个子目录包含 skill.py实现、schema.jsonSchema、test_cases.json测试用例、README.md使用说明。这个结构现在成为了团队所有技能仓库的标准模板。5.3 性能调优参考技能系统的性能瓶颈往往不在模型本身而在调度层和 IO 层。我在压测过程中有一套可复用的调优策略按影响程度排序最优先的是技能加载的并发化。技能注册时如果串行加载几十个模块启动时间会被拉长。改成按依赖关系并行加载后40 个技能的加载时间从 4.8 秒降到 1.2 秒。其次是 Schema 校验开销。pydantic 校验在小字段量时没感觉但技能参数一旦包含嵌套列表和自定义类型校验开销就会变大。对大体积参数我做了简单的短路处理先做字段级非空和类型检查再跳过深度校验只有精确到具体业务逻辑时才启用完整校验。再次是缓存命中率的优化。我给缓存 key 设计引入了“规范化参数”步骤把参数里的无关字段时间戳、随机 ID、请求源剔除后再算哈希。这样同一个业务请求即使带了不同的随机 trace_id也能命中同一份缓存。最后是技能注册中心的存储优化。当技能元数据从几十条涨到几千条时全量加载到内存会导致启动变慢。我改成了按技能标签做懒加载实际被 Agent 检索到才从 Redis 拉取完整 Schema。6. 常见问题与排查技巧实录6.1 高频问题速查表我把这段时间被问到最多的六个问题和排查方案整理成了表格方便你快速定位问题现象可能原因快速排查方案Agent 总是选错技能技能描述区分度不够语义重叠对比相似技能的 description找出容易混淆的点重写描述并加入典型的正反示例用户报告技能返回数据很旧缓存策略过宽检查该技能的缓存规则涉及金额、库存、状态等动态数据的技能必须关闭缓存技能调用偶发性超时超时设置不合理或资源竞争查监控面板中该技能的 P95 耗时如果是阶段性高峰导致的扩展线程池或调大超时新增技能后系统变慢技能自动发现了但未做缓存或懒加载检查整个技能描述是否在每次请求时都全量注入考虑改为按意图预筛选 懒加载高权限技能被低权限角色调用权限控制没有下沉到技能级别走审计日志看调用链核对技能级别的 ACL 配置L3 技能必须加二次授权技能回归后其他技能异常共享技能改动影响到了下游查技能反向依赖列表改动前先做影响评估发布后立即跑下游技能集成测试6.2 排查思路与心得排查 Agent 技能问题我总结出的最核心思路是先分清是模型的问题还是系统的问题。用真实请求复现一次然后看调度日志确认模型选择了什么技能、技能参数是什么、执行结果是什么。如果模型选错了是提示词和技能描述的问题如果模型选对了但执行报错是技能实现的问题如果技能执行成功但 Agent 解读错了结果是输出 Schema 不够清晰或返回数据格式不符合预期的问题。一个常见的盲区是把模型的“幻觉性调用”当成系统 bug。曾经有一次Agent 在处理一个时间计算问题时居然调用了一个“天气查询”技能怎么也想不明白为什么。后来查日志发现该技能描述里写着“适合日常场景查询”模型在语义空间里把“天气”和“日常”做了关联。这说明技能描述里的每一个词都会影响模型的工具选择写描述时要刻意避免模糊修饰词。另一个心得是要善用监控面板。我在技能调度层记录的每次调用的调试信息都包含技能名、参数哈希、耗时、错误类型、重试次数。这些数据在定位问题时价值很高。某次用户反馈 Agent 反应卡顿我查了监控面板发现一个技能在特定参数下发生死循环导致线程池被耗尽。没有这些指标这种问题基本只能靠瞎猜。还有一个容易被忽视的点技能返回给模型的结果本身要“适合阅读”。如果技能返回的是一个巨大的 JSON里面 90% 的字段对当前任务没意义模型理解起来就困难还容易误解读。在设计输出 Schema 时要站在模型的角度做减法只返回对后续推理有实际意义的字段能做成摘要的先做成摘要能结构化的先结构化。7. 我给 agent-skills 后续迭代留的扩展方向技能库这套东西做到现在其实还有不少可以继续深入的方向。现阶段我用的是“技能中心 调度器 Agent”的三层模型基本能满足中小规模场景但再往下推进有几个点值得持续投入。第一是技能的自我进化。目前技能迭代基本靠人工分析日志、发现问题、修改实现。理想状态应该是系统能基于失败日志自动生成技能改进建议甚至在人工审核后自动更新技能代码。现在大模型辅助编程的能力已经足够支撑这样一个闭环缺的主要是流程设计。我在内部设计了一个原型失败样本自动聚类 - 总结失败原因 - 生成改进后的技能代码 - 跑自动回归测试 - 推送给人工审核。这个流程跑通后技能迭代效率能再上一个台阶。第二是跨 Agent 的技能复用市场。在企业内部不同团队会各自沉淀出有价值的技能如果把这些技能统一上传到内部技能市场其他团队可以按需订阅使用整个组织的研发效能提升会非常可观。当然这需要解决技能安全审查和跨团队资质认证的问题但方向是明确的。第三是技能链路的可视化编排。目前任务的编排逻辑隐藏在代码和模型之间开发和业务同学很难直观看到一次任务请求具体走过了哪些技能。如果能在技能调度之上叠加一个可视化链路追踪把每一次 Agent 会话的完整技能调用路径展示出来对调优和维护会非常友好。这些方向我会陆续去验证和实现到时候有新结论了再来更新这篇总结。但我个人的体会是agent-skills 这类形态的能力组织方式大概率会是未来 Agent 应用的一个基础设施模块早一点把底子搭好后面做复杂应用时会省心很多。 
长河君 · 2026/9/16 20:05:38 · 阅读 1.2k Agent技能库从设计到落地：多智能体工具复用与性能优化实践
我最早接触 agent-skills 这个概念其实是在调试一个多智能体协作系统的时候。当时我发现自己写的 Agent 越来越臃肿每一个新任务都要在 prompt 里塞进大段大段的工具说明任务一多上下文窗口被吃掉大半模型的理解能力直线下降而且不同 Agent 之间完全没有共用的能力模块改一处逻辑要同时改好几个地方。后来我开始把各种单点能力抽出来做成一个可插拔、可复用、可独立维护的技能库这套方法就是 agent-skills 的核心思路。这篇文章我想把自己在构建和使用 agent-skills 过程中的完整思考、设计方案、落地细节以及踩过的坑整理出来给正在做 Agent 工程化、或者被多智能体能力复用问题折腾的朋友一份可以直接上手的参考。1. agent-skills 项目概述与核心痛点1.1 为什么 Agent 需要一套独立的技能库很多人在刚开始做 Agent 的时候习惯把工具函数直接写死在主流程里或者一股脑把所有 API、代码逻辑、提示词都塞进系统 prompt。早期 demo 阶段这么干确实省事但项目稍微一复杂问题立刻暴露出来。拿我自己之前的一个场景举例当时我需要让 Agent 同时完成联网检索、本地文件搜索、PDF 内容提取、表格数据汇总、定时提醒这几个任务。如果按照传统做法每个 Agent 都要重复配置这些工具而且每个 Agent 的回答风格、参数格式还不一定一致。更要命的是一旦底层工具的接口变了比如某个检索 API 从 v1 升级到 v2我得把所有 Agent 的配置全部翻出来改一遍改完之后还要逐个测试工作量直接翻倍。agent-skills 要解决的正是这个问题把每一个可复用的能力单元抽出来做成标准化的“技能”技能与技能之间松散耦合Agent 可以按需加载、按叙调用。这样整个系统就像一个工具箱Agent 需要哪个工具就拿哪个而不是把整个工具箱背在身上。另外一个隐藏的痛点是提示词长度。现在主流大模型的上下文窗口看起来很大但实际上真正有效的注意力区域依然是有限的。你把几十个工具说明一次性塞进 prompt模型在长上下文中做工具选择时准确率会显著下降尤其是语义相近的工具之间特别容易出现误选。技能库按需加载之后每次只给 Agent 注入当前任务真正需要的几个技能描述工具选择准确率提升非常明显。1.2 这份项目总结适合谁来参考如果你正在做以下几类事情agent-skills 这套思路会比较对路搭建多智能体协作系统希望不同 Agent 之间的能力可以统一调度、避免重复建设做单 Agent 应用但感觉 prompt 越来越长、工具选择经常出错、维护成本越来越高刚入行大模型应用开发想知道正规一点的 Agent 工程是怎么把工具和模型解耦的做企业级 AI 平台需要考虑技能的安全隔离、权限控制、审计日志、版本回滚等生产级问题。我会尽量把原理和实操都讲清楚有基础的读者可以直接跳到第 3 部分看代码实现和参数设计新手建议从头往后顺序读每一步都会有配合解释。2. 技能体系的整体设计与拆解思路2.1 任务拆解与技能原子化构建 agent-skills 的第一步不是写代码而是把业务需求拆成最小的技能粒度。技能粒度怎么定直接决定了整个系统的灵活性和维护成本。粒度太粗比如把“处理文档”做成一个技能那这个技能的输入输出会非常不可控粒度太细比如把“把字符串转成大写”也当技能又会让技能数量爆炸Agent 在技能选择时反而会犯选择困难症。我自己总结了一个判断标准如果一个技能的内部逻辑超过 50 行或者它内部明显包含了两个以上可以独立变化的子步骤那就应该继续拆分。反过来如果一个技能被三个以上不同的场景调用而调用时参数基本一致那说明这个技能本身是独立的原子能力。举个例子。我当时需要 Agent 具备“分析周报并生成摘要”的能力。按粗粒度拆这是一个技能但真正分析它的内部逻辑应该拆成读取文件内容支持 PDF、Word、Markdown、TXT根据文件类型做文本提取和清洗调用大模型生成摘要将摘要保存到指定目录这四个子步骤里面第一、第二、第四都是通用能力被其他任务复用的可能性极高所以应该独立成技能。第三个是核心业务能力但也可以把“模型调用”抽成一个底座技能上层技能只指定模型参数和 prompt 模板不关心底层走的是什么模型。2.2 技能编排与执行管线技能拆完之后下一步要考虑的是技能之间如何编排。agent-skills 的编排逻辑参照了微服务架构里非常成熟的做法技能之间不直接调用而是通过一个统一的调度层来进行。调度层负责三件事接收 Agent 传来的目标描述和上下文根据技能列表和当前上下文决定调用哪些技能以及调用顺序把技能的返回值做标准化处理再回传给 Agent我用的编排方式是“无向技能注册 有向任务管线”。每个技能独立注册到技能中心技能中心维护一份技能元数据清单技能名称、描述、输入 Schema、输出 Schema、版本、依赖关系。当 Agent 收到一个复杂任务时先由调度层做一个简单的意图预判断把任务初步归类再动态检索出候选技能集合最后由大模型基于候选技能描述选择最匹配的技能序列。这种方式比纯靠模型自由选择所有技能要稳定得多。模型的选择空间从几十个技能缩小到三到五个候选技能选择错误率可以控制到很低的水平。2.3 工具选型与技术栈考量agent-skills 的技术栈选择核心考量是三个生态成熟度、运行效率、团队上手成本。我选择了 Python 3.10 作为主语言因为目前大模型应用的开源生态基本集中在 Python无论是 LangChain 还是 LlamaIndex都能很好地配合技能库做集成。Web 框架用的是 FastAPI它的异步性能好pydantic 的数据校验能力也能直接用于技能的输入校验。技能注册中心用的是 Redis 加内存缓存的双层结构Redis 负责持久化和跨进程共享内存负责加速同进程内的频繁调用。向量检索用的是轻量的 SQLite sqlite-vec没有引入重型的向量数据库因为技能数量只要不是上万级别轻量方案完全够用并且部署起来省事很多。如果要跑在异构环境里比如一部分技能依赖 Java 服务一部分技能依赖 Node 服务那我的建议是在技能中心之上再包一层网关用统一 HTTP 协议封装不同语言实现的技能。这一点我下面会详细说。3. 核心实现从零构建可复用的技能库3.1 技能定义与 Schema 设计一个技能在 agent-skills 里的核心定义不只是函数本身还包括一份机器和模型都能读懂的元数据。我设计了这样的等价数据结构你可以直接参考dataclass class SkillSchema: name: str description: str version: str author: str input_schema: dict output_schema: dict tags: list[str] dependencies: list[str] timeout_seconds: int 30 requires_auth: bool False is_async: bool False这里的 input_schema 和 output_schema 是关键。它们不仅仅是装饰实际的作用有三个第一用于大模型理解技能。description 和 input_schema 会拼装成工具说明注入到模型请求里模型看到“技能名 功能描述 参数格式”后就能知道什么时候该调用、怎么调用。第二用于运行时校验。技能在执行前系统会强校验传入参数是否符合 Schema。这一层校验现在看起来很基础但在实际运行中能挡住大量脏数据。我遇到过不止一次模型生成了缺参数或者类型错误的调用请求如果没有这层校验错误会直接炸到业务逻辑里。第三用于技能检索。tags 和 description 会做向量化存入本地向量库检索时按语义相似度召回。为了模型在工具选择阶段不迷路description 必须写清楚技能“做什么、不做什么、在什么场景下用”。比如一个技能叫“上传文件”描述只写“上传文件”就不够好写“将用户提供的文件上传到对象存储并返回访问 URL仅支持不超过 50MB 的文件”才是合格的描述。3.2 技能的注册、发现与热加载技能注册中心在我的实现里承担两件事维护技能元数据响应技能调用请求。注册的流程比较简单每个技能包在启动时调用注册接口把自己的 Schema 注册进中心。为了支持热加载所有技能实现都放在一个插件目录下用 importlib 做动态导入这样可以做到不修改主进程代码直接新增技能文件即可生效。# skills_dispatcher.py import importlib import pkgutil from typing import Dict class SkillDispatcher: def __init__(self): self.registry: Dict[str, SkillSchema] {} self.handlers: Dict[str, callable] {} def discover_and_register(self, package_name: str): package importlib.import_module(package_name) for mod_info in pkgutil.iter_modules(package.__path__): mod importlib.import_module(f{package_name}.{mod_info.name}) if hasattr(mod, skill_schema) and hasattr(mod, handler): self.registry[mod.skill_schema.name] mod.skill_schema self.handlers[mod.skill_schema.name] mod.handler print(f[Skill] loaded {mod.skill_schema.name} v{mod.skill_schema.version}) def execute(self, skill_name: str, **kwargs): if skill_name not in self.handlers: raise SkillNotFoundException(skill_name) schema self.registry[skill_name] # 执行前 schema 校验 validated_input validate_against_schema(schema.input_schema, kwargs) result self.handlers[skill_name](**validated_input) # 执行后输出校验 return validate_against_schema(schema.output_schema, result)这套代码本身不难但有几个细节值得注意。技能的 handler 函数是普通同步函数还是异步函数必须在 is_async 字段里标明否则在 asyncio 事件循环里直接调用同步函数会导致整体性能下降。另外一个细节是技能执行必须有超时控制。我在调度器里给每个技能单独设置了 timeout_seconds超时的技能直接返回错误不让坏技能拖垮整个 Agent 会话。3.3 沙箱执行、鉴权与安全技能一旦多起来安全就是一个绕不开的问题。你从网上拉一个现成技能包回来里面如果有恶意代码一执行可能就把整个系统搞坏了。即使团队内部开发的技能像执行 shell 命令、访问数据库、调用外部 API 这类高危能力也必须有精细到技能级别的权限管控。我的安全方案分了三层第一层技能分级。我把技能按风险等级分成 L1、L2、L3 三级。L1 是纯计算、无副作用的能力比如文本格式化、时间换算、数学计算L2 是访问内部系统只读接口的能力比如查询数据库、读取文件L3 是产生写操作或外部调用的能力比如发邮件、写库、调用第三方付费 API。L1 技能不设权限限制L2 技能要求用户身份在可访问名单内L3 技能必须经过显式授权且执行前弹出确认。第二层隔离执行。L3 技能默认跑在一个受限的子进程里这个子进程没有网络访问权限也没有本地文件写入权限只有明确开放的沙箱目录可写。用到了 Python 的 resource 模块限制 CPU 时间和内存防止技能死循环或者内存泄漏把宿主机拖垮。第三层审计追踪。所有技能调用都记录完整日志包括调用者、时间戳、参数摘要、返回状态、耗时。这些日志在出问题时是排查事故的关键线索。值得提一句参数摘要不应该记录完整明文尤其是包含敏感信息时我习惯直接用 SHA-256 对参数做哈希摘要只记录指纹用于追踪不记录具体内容。3.4 缓存、错误处理与可观测性很多技能处理的是重复度很高的请求。比如“从文件路径读取全文”这种技能如果同一个文件被反复请求解析每次都重新读取一遍浪费是显而易见的。我给技能调度层加了一级内容缓存缓存 key 由技能名 参数哈希组成默认缓存 5 分钟L1 纯计算技能可以缓存更长时间。这里要注意的是有外部副作用的技能比如查询天气不能随便用缓存否则用户会拿到过期的数据。错误处理方面我给技能调用统一设计了异常结构这是功能实现之外很重要的一个环节class SkillExecutionError(Exception): def __init__(self, skill_name, error_type, message, recoverableTrue, retry_count0): self.skill_name skill_name self.error_type error_type self.message message self.recoverable recoverable self.retry_count retry_count super().__init__(message)错误类型我分成了这么几类SchemaValidationError参数校验失败直接返回 Agent让模型重新构造参数不需要重试TimeoutError执行超时按策略做一次重试如果还超时就返回错误提示ExternalAPIError调用外部接口失败根据外部接口的返回状态决定是重试还是降级ResourceLimitError资源受限直接返回错误要求用户减少数据量或提升配额。为了观察技能的运行状态我还在调度器里内置了一个简单的监控面板展示技能调用次数、失败率、平均耗时P50/P95、缓存命中率。这些指标对我做技能迭代的价值非常大比如我看到某个技能 P95 耗时是 P50 的五六倍就说明它在线程竞争或 IO 等待上出了问题值得深入优化。4. 技能质量评估与持续迭代4.1 多维评估体系技能做出来了怎么判断它好不好用我一开始只看功能跑不跑得通后来发现这是一种错觉。有些技能功能上完全正常但放到真实 Agent 场景里模型根本不知道该什么时候调用它或者调用了之后输出格式让 Agent 解读困难这时技能的效果就是零。后来我建立了一个多维评估体系从五个维度给技能打分第一个维度是任务成功率。给定一组标准测试输入技能能否返回符合预期的输出。这个是最基本的。第二个维度是调用准确率。在一个模拟 Agent 环境里准备好多个相似技能和干扰技能让模型自主选择技能看模型在遇到目标任务时能不能准确命中对应技能。这个维度衡量的是技能的语义清晰度如果模型频繁选错那多半是技能描述或参数说明不够有区分度。第三个维度是响应延迟。技能从被调用到返回结果的总耗时重点关注 P95 和 P99高百分位耗时比平均耗时更能发现问题。第四个维度是 token 消耗。调用该技能消耗的大模型输入 token 数因为技能描述是注入到上下文里的这个成本经常被忽略但技能一多它对成本和上下文质量的影响不容小觑。第五个维度是失败恢复率。技能在出错后经过自动重试或参数纠正后能成功恢复的比例。每次迭代技能我都跑一遍这五个维度的评估对比前后差异而不是只看功能有没有实现。4.2 回归测试与版本管理技能库的版本管理是 agent-skills 里最容易做砸的部分。一开始我偷懒技能文件直接覆盖式更新结果有一次改了一个底层共享技能的内部逻辑没注意到它被其他五个技能依赖上完线之后五个技能全部异常。那天排查到半夜最痛苦的还不是修 bug而是根本说不清是从哪个版本开始坏的。后来我彻底改了策略把技能版本管理纳入了整个开发流程。现在每个技能包里固定带一个版本号升级技能时只新增不覆盖旧版本保留在技能中心里。调用方如果指定了技能版本就固定调用该版本不指定的话默认调用最新稳定版。另外技能的依赖关系和影响面要做成可查询的改任何一个技能之前先查它的反向依赖列表确定不会影响其他技能才动手。回归测试这件事我从标准的软件工程里搬了过来每个技能有三个固定流程单元测试验证单个技能自身逻辑输入边界条件、异常参数全覆盖集成测试在一个完整 Agent 场景里验证技能和模型、调度器之间的配合回归测试旧版本技能跑通过的测试用例新版本必须全部再跑一遍不通过不允许发布。这套机制做起来会多花一些时间但长期看绝对值。技能库里的技能一旦积累到两位数没有这套机制做任何改动都像在雷区走路。5. 实战过程与关键细节复盘5.1 从零落地的完整流程记录我把这次从零构建 agent-skills 的完整流程用一条时间线串一下这样你可以照着复现。第一阶段是技能盘点与设计大概花了两天。我把所有需要 Agent 支持的业务场景列出来逐一拆解成最小子步骤然后合并同类项、剔除不必要的技能最终整理出二十三个技能涉及文档处理、数据查询、外部接口调用、消息通知这几大类。每个技能写好 Schema 初稿并给所有描述设置了统一的写作规范。第二阶段是底盘建设也用了两天。写好了注册中心、调度器、Schema 校验、缓存、权限控制、监控面板这些基础设施。这个阶段我在本地用一个小测试场景验证了完整链路注册一个技能、调用一个技能、校验输入输出、记录日志全部通了一遍。第三阶段是技能实现花的时间最多五天。二十三个技能分成三批每批次实现完之后立刻跑单元测试和集成测试。这段时间我发现技术本身不难难的是把技能边界和依赖关系梳理清楚。第四阶段是 Agent 集成与评估两天。把技能库接入到我正在做的多 Agent 系统里跑完整流程。评估之后淘汰了两个描述不清的技能合并了三个功能重叠的技能优化了四个技能的超时设置。整个过程中我用的是自己搭建的轻量环境一台 8C16G 的开发机代码仓库用 Git技能中心用 Redis SQLite调度服务用 FastAPI 跑在 Docker 里。这个组合对个人项目和中小团队来说足够了。5.2 踩坑记录与关键细节技巧这条路走过来有几个坑印象很深分享出来供你参考。第一个坑技能描述写得太抽象。早期我有几个技能的 functions 描述写得非常简洁比如“获取用户信息”“获取订单信息”。结果模型在任务里需要查询用户时经常调用“获取订单信息”。后来我把所有技能描述重写统一加入触发场景、输入限制、输出样例三要素调用准确率从 81% 提到 97%提升非常明显。坚持一个原则描述要让模型在不确定时敢选你。第二个坑技能超时设置太粗放。我最初所有技能统一设成 60 秒超时。结果一个 L1 纯计算技能因为线程池被占满排队等了快一分钟才执行Agent 会话直接超时。后来我按技能的实际耗时分布重新设定超时纯计算技能 5 秒IO 类技能 20 秒外部调用技能 60 秒网络文件下载类技能 120 秒。给技能定超时之前先跑一轮性能基准测试。第三个坑缓存导致的数据过期。我给“查询用户余额”这种技能加了 5 分钟缓存结果用户反映余额变了但页面显示旧数据。后来我把所有涉及金额、库存、状态类的技能全部设置为禁止缓存只在纯查询类且可容忍延迟的技能上保留缓存。原则是只要数据可能因外部操作而改变就不要轻易缓存。第四个坑技能目录混乱。技能数量一多技能文件组织不规范查找和维护效率就会骤降。后来我强制规定了项目目录结构每个技能占一个子目录包含 skill.py实现、schema.jsonSchema、test_cases.json测试用例、README.md使用说明。这个结构现在成为了团队所有技能仓库的标准模板。5.3 性能调优参考技能系统的性能瓶颈往往不在模型本身而在调度层和 IO 层。我在压测过程中有一套可复用的调优策略按影响程度排序最优先的是技能加载的并发化。技能注册时如果串行加载几十个模块启动时间会被拉长。改成按依赖关系并行加载后40 个技能的加载时间从 4.8 秒降到 1.2 秒。其次是 Schema 校验开销。pydantic 校验在小字段量时没感觉但技能参数一旦包含嵌套列表和自定义类型校验开销就会变大。对大体积参数我做了简单的短路处理先做字段级非空和类型检查再跳过深度校验只有精确到具体业务逻辑时才启用完整校验。再次是缓存命中率的优化。我给缓存 key 设计引入了“规范化参数”步骤把参数里的无关字段时间戳、随机 ID、请求源剔除后再算哈希。这样同一个业务请求即使带了不同的随机 trace_id也能命中同一份缓存。最后是技能注册中心的存储优化。当技能元数据从几十条涨到几千条时全量加载到内存会导致启动变慢。我改成了按技能标签做懒加载实际被 Agent 检索到才从 Redis 拉取完整 Schema。6. 常见问题与排查技巧实录6.1 高频问题速查表我把这段时间被问到最多的六个问题和排查方案整理成了表格方便你快速定位问题现象可能原因快速排查方案Agent 总是选错技能技能描述区分度不够语义重叠对比相似技能的 description找出容易混淆的点重写描述并加入典型的正反示例用户报告技能返回数据很旧缓存策略过宽检查该技能的缓存规则涉及金额、库存、状态等动态数据的技能必须关闭缓存技能调用偶发性超时超时设置不合理或资源竞争查监控面板中该技能的 P95 耗时如果是阶段性高峰导致的扩展线程池或调大超时新增技能后系统变慢技能自动发现了但未做缓存或懒加载检查整个技能描述是否在每次请求时都全量注入考虑改为按意图预筛选 懒加载高权限技能被低权限角色调用权限控制没有下沉到技能级别走审计日志看调用链核对技能级别的 ACL 配置L3 技能必须加二次授权技能回归后其他技能异常共享技能改动影响到了下游查技能反向依赖列表改动前先做影响评估发布后立即跑下游技能集成测试6.2 排查思路与心得排查 Agent 技能问题我总结出的最核心思路是先分清是模型的问题还是系统的问题。用真实请求复现一次然后看调度日志确认模型选择了什么技能、技能参数是什么、执行结果是什么。如果模型选错了是提示词和技能描述的问题如果模型选对了但执行报错是技能实现的问题如果技能执行成功但 Agent 解读错了结果是输出 Schema 不够清晰或返回数据格式不符合预期的问题。一个常见的盲区是把模型的“幻觉性调用”当成系统 bug。曾经有一次Agent 在处理一个时间计算问题时居然调用了一个“天气查询”技能怎么也想不明白为什么。后来查日志发现该技能描述里写着“适合日常场景查询”模型在语义空间里把“天气”和“日常”做了关联。这说明技能描述里的每一个词都会影响模型的工具选择写描述时要刻意避免模糊修饰词。另一个心得是要善用监控面板。我在技能调度层记录的每次调用的调试信息都包含技能名、参数哈希、耗时、错误类型、重试次数。这些数据在定位问题时价值很高。某次用户反馈 Agent 反应卡顿我查了监控面板发现一个技能在特定参数下发生死循环导致线程池被耗尽。没有这些指标这种问题基本只能靠瞎猜。还有一个容易被忽视的点技能返回给模型的结果本身要“适合阅读”。如果技能返回的是一个巨大的 JSON里面 90% 的字段对当前任务没意义模型理解起来就困难还容易误解读。在设计输出 Schema 时要站在模型的角度做减法只返回对后续推理有实际意义的字段能做成摘要的先做成摘要能结构化的先结构化。7. 我给 agent-skills 后续迭代留的扩展方向技能库这套东西做到现在其实还有不少可以继续深入的方向。现阶段我用的是“技能中心 调度器 Agent”的三层模型基本能满足中小规模场景但再往下推进有几个点值得持续投入。第一是技能的自我进化。目前技能迭代基本靠人工分析日志、发现问题、修改实现。理想状态应该是系统能基于失败日志自动生成技能改进建议甚至在人工审核后自动更新技能代码。现在大模型辅助编程的能力已经足够支撑这样一个闭环缺的主要是流程设计。我在内部设计了一个原型失败样本自动聚类 - 总结失败原因 - 生成改进后的技能代码 - 跑自动回归测试 - 推送给人工审核。这个流程跑通后技能迭代效率能再上一个台阶。第二是跨 Agent 的技能复用市场。在企业内部不同团队会各自沉淀出有价值的技能如果把这些技能统一上传到内部技能市场其他团队可以按需订阅使用整个组织的研发效能提升会非常可观。当然这需要解决技能安全审查和跨团队资质认证的问题但方向是明确的。第三是技能链路的可视化编排。目前任务的编排逻辑隐藏在代码和模型之间开发和业务同学很难直观看到一次任务请求具体走过了哪些技能。如果能在技能调度之上叠加一个可视化链路追踪把每一次 Agent 会话的完整技能调用路径展示出来对调优和维护会非常友好。这些方向我会陆续去验证和实现到时候有新结论了再来更新这篇总结。但我个人的体会是agent-skills 这类形态的能力组织方式大概率会是未来 Agent 应用的一个基础设施模块早一点把底子搭好后面做复杂应用时会省心很多。