说起来有点不好意思我的 agent-skills 这个项目最早是从一次“翻车现场”开始的。当时我正在做一个客服智能体对话能力已经调得挺顺用户问什么都能答上两句可一旦涉及“查订单状态—生成退款单—通知仓库”这种多步骤的真实业务流程模型就开始自由发挥有时候漏掉退款字段有时候调错内部接口有时候干脆把流程次序搞反。与其说是智能体在干活不如说是它在“即兴表演”。我后来复盘时想明白一件事对话可以靠模型临场发挥但能力不能。能力必须被显式地定义、注册、路由、可观测。于是就有了 agent-skills——一套把智能体的“技能”当作标准化资产来管理的轻量框架。这篇文章不聊大而全的平台只聊我在设计 agent-skills 时踩过的坑、想清楚的道理以及一套可以直接抄走的落地路径。如果你也在做 Agent 类应用遇到过“工具调用乱、技能复用难、上下文一多就崩”的问题那这篇应该能帮上忙。1. 项目定位agent-skills 到底在解决什么问题1.1 没有技能目录的 Agent能力全靠“现场发挥”很多人一开始做 Agent最自然的做法是把所有能力和工具说明一股脑塞进 system prompt。比如告诉模型“你可以调用 get_order、refund_order、send_notification 这三个函数”再给它一堆 JSON schema。这种方案在小 demo 里跑得通因为任务单一、工具少。可一旦业务复杂起来问题就慢慢冒出来了。首先是 prompt 长度失控。工具说明、参数约束、调用示例、异常码说明全堆在上下文里每轮对话都带着这堆东西走token 开销大不说模型还容易抓不住重点。其次是能力边界模糊。模型经常在不需要调用工具的时候自作主张调了工具或者该调工具的时候反而一本正经地胡编数据。第三是技能无法沉淀。你让人工把某个流程调通了下一周换一个 Agent 实例这些经验全丢还得重新来一遍。agent-skills 的核心主张就是别把技能当成 system prompt 里的几行描述把它当成可以注册、复用、测试、审计的一等公民。1.2 把技能当成标准化资产而不是提示词里的几行话我参考了很多平台里“技能市场”的灵感也借鉴了早期语义内核里插件注册表的设计最终确定了一个极简模型每一项技能包含三样东西——声明文件、执行逻辑、访问控制。声明文件负责描述技能“是什么、能干什么、需要什么参数、有什么前置条件”。执行逻辑负责真正做事可以是一段 Python 函数、一个 HTTP 调用封装甚至是一个 shell 脚本。访问控制则决定了哪些角色、哪些上下文可以触发这个技能。这三样解耦之后技能就成了标准的“插件”你甚至可以给甲方交付一个只包含声明文件加核心代码的技能包他接入自己的 Agent 时只需要跑一条注册命令。这套设计最大的好处是能力边界从模型手里收回到开发者手里。模型要做的事情退化为“理解用户意图选择一个技能填好参数”剩下的多步操作完全由技能内部保证。这大大降低了不可控感。1.3 这套东西到底适合谁我并不是要建议所有场景都上 agent-skills。如果你是做一个十分钟的问答 demo自然语言直接回答就够了没必要绕一层技能框架。但如果你遇到下面几种情况这套思路就很值得参照同一个能力要被多个 Agent 或场景复用不想重复维护提示词。流程里包含外部系统调用、权限检查、回调、状态持久化不能只靠模型自然语言描述。团队里有多个人同时在加能力需要统一管理入口和发布规范。线上出了事故你想追溯到“哪个技能、哪次调用、哪个参数”导致了错误。换句话说agent-skills 解决的问题不是“能不能让模型调用工具”而是“如何让工具调用变成一套可控、可维护、可复制的体系”。2. 整体设计与目录结构2.1 一个技能的最小信息单元在设计技能结构时我最关心一个原则让模型和开发者都能快速看懂“这个技能是干嘛的”。我见过很多技能定义写得像 API 文档的复制粘贴参数说明含糊不清示例给了等于没给。模型看到这种东西照样不会用。我把每个技能的最小信息单元收敛成七项skill_id全局唯一标识比如 report.generator.weekly。name面向模型和日志展示的名称。description不超过 200 字的自然语言描述必须说清楚“什么时候该用、什么时候不该用”。parametersJSON Schema 方式的参数定义每个参数都要有类型、必填性、默认值和示例。tasks可选字段列出技能内部会执行的主要步骤方便模型判断任务匹配度。policies权限、速率限制、超时策略等。entry指向执行逻辑的入口通常是一个函数名或可调用路径。metadata版本号、作者、标签、更新时间等治理信息。这七项不是拍脑袋定的。我最初少写了 tasks模型经常把“查天气”和“查航班”搞混因为两者的 description 里都出现了“查询信息”。后来在描述里增加了“典型任务场景”才把误命中率压下来。所以 tasks 看似冗余对于模型路由却有实际帮助。2.2 目录与文件约定agent-skills 的仓库结构目前长这样agent-skills/ ├── skills/ │ ├── report/ │ │ ├── weekly_report/ │ │ │ ├── skill.yaml │ │ │ ├── __init__.py │ │ │ └── implement.py │ │ └── daily_report/ │ │ ├── skill.yaml │ │ └── implement.py │ └── order/ │ └── refund/ │ ├── skill.yaml │ └── implement.py ├── core/ │ ├── registry.py │ ├── router.py │ ├── schema.py │ └── executor.py ├── tests/ └── examples/每个技能一个目录目录里 skill.yaml 管声明implement.py 管执行。core 里是引擎本身包括注册表、路由、参数校验和调用器。使用方不需要关心 core 的细节只需要往 skills 目录里丢技能包。我一开始也想把声明和执行写在同一个文件里后来发现当技能逻辑超过一百行时声明文件会被代码淹没非工程师侧的同学也看不懂。拆开之后产品同学可以 review skill.yaml工程同学专心改 implement.py边界舒服多了。2.3 为什么选 YAML 声明式 Python 实现当时也纠结过要不要用 JSON 或者 TOML 来写声明文件。JSON 的问题是注释缺失TOML 的类型表达能力又不够丰富。YAML 虽然缩进容易坑但它天然支持注释而且写复杂嵌套结构时的可读性最好。对于工程师来说YAML 确实是声明技能的及格线选择。执行逻辑用 Python 是顺手的事。生态里有 pydantic 做参数校验、有各类 HTTP 客户端、有 asyncio 做并发。技能内部还可以用 Python 写更细的流程编排比如重试、熔断、数据转换。声明与实现的分离核心目的不是语言洁癖而是让“路由决策”和“业务执行”各司其职。3. 核心实现从定义到调用的完整链路3.1 技能注册表启动时扫描 vs 运行时注册技能要能被调用第一步是进入注册表。我在 agent-skills 里同时支持两种注册方式。启动时扫描的做法是服务启动时遍历 skills 目录逐个读取 skill.yaml通过 pydantic 校验结构把技能对象塞进一个字典。这个方法的好处是简单、可预测适合技能列表相对稳定的生产环境。运行时注册的做法是暴露一个 register_skill 接口调用方在代码里动态传入技能定义适合做“插件热加载”或“用户自定义技能”等场景。两种方式我最后都保留因为真实业务中总会有“今天下午临时给大客户开一个特殊技能不想重新发版”的需求。运行时注册虽然灵活但一定要配合权限校验否则等于给攻击者开了一个代码执行入口。哪怕只在内部环境使用我也建议给注册接口加上鉴权和操作审计。核心注册表代码其实不长核心是避免重复注册和兼容热更新class SkillRegistry: def __init__(self): self._skills {} self._lock asyncio.Lock() async def register(self, skill: SkillDefinition): async with self._lock: if skill.skill_id in self._skills: raise SkillConflictError(skill.skill_id) self._skills[skill.skill_id] skill async def unregister(self, skill_id: str): async with self._lock: self._skills.pop(skill_id, None) def get(self, skill_id: str): return self._skills.get(skill_id)很多人会忽略重复注册的校验。我们线上曾经因为配置中心重复推送同一个技能被注册了两遍导致路由表里出现两个同名条目模型调用时随机命中其中一个行为时好时坏。所以这里用锁加重复校验不是小题大做。3.2 路由匹配从模糊意图到技能入口注册表解决的是“有哪些技能”路由解决的是“该用哪个技能”。agent-skills 没有走太复杂的 NLI 模型而是采用了一种多级匹配策略效果和成本比较均衡。第一级是向量召回。把用户当前消息或整段会话摘要编码成向量与每个技能的 description 和 tasks 编码后的向量做相似度检索找出 Top-K 候选技能。第二级是 LLM 精排。把候选技能的名称、描述、参数列表交给模型让模型输出一个 JSON 结构指定选中的技能和参数。这样既避免了纯向量匹配的“语义漂移”又省去了让 LLM 从几百个技能里大海捞针的开销。这里有一个我在实践中反复踩过的坑不要把整个技能描述原样丢给模型做精排模型会迷失在细节里。我最后把性价比最高的方式定为只把技能的 name、description 以及参数名列表传给模型。完整参数说明只在模型选择完技能后进入参数填写的第二阶段才给。这相当于把“选技能”和“填参数”拆成了两次模型调用虽然多了一次延迟但准确率明显提升。async def route(self, query: str, top_k: int 5): candidates await self.vector_store.search(query, top_k) simplified [ { skill_id: c.skill_id, name: c.name, description: c.description, parameter_names: list(c.parameters.keys()), } for c in candidates ] decision await self.llm.decide(query, simplified) return self._build_invocation(decision)3.3 参数校验与自动补全技能被选中后下一步是让模型填参数。这一步最烦的问题不是模型不会填而是填了错误的类型、填了没定义的字段、或者把东八区时间填成了 UTC 没有转换。我在 agent-skills 里引入两段式处理先做严格 Schema 校验再做启发式补全。严格校验用 pydantic 完成。model 根据参数的 JSON Schema 生成一个大致的参数对象校验器检查类型、枚举、必填项。校验失败时不是直接中断而是把错误信息返回给模型让它重新生成一次参数补全。这个“一次纠错机会”在生产环境非常有用。我统计过给模型一次纠错机会后参数填充成功率能从 84% 提升到 97% 左右。启发式补全解决的是模型留空的字段。比如“当前时间”“用户ID”“默认仓库编号”这些可以从上下文或配置中心自动获取的字段技能定义里可以标记为 auto_fill。补全逻辑必须在技能执行前做最好把补全后的参数快照写入日志方便事后稽核。3.4 上下文管理临时技能状态与持久记忆分离技能调用过程中最隐蔽的坑是上下文串扰。早期版本我图省事把技能的中间状态直接挂在会话上下文对象上。结果用户在一个会话里连续触发了“查询订单”“查询物流”“投诉登记”三个技能状态的 key 互相覆盖订单号被物流单号冲掉投诉登记里带上了前一个技能的残留参数。后来我把上下文拆成了两层。第一层是短期执行上下文每个技能调用都有独立的 context 对象技能结束后就丢弃内部的状态不会泄漏到其他技能。第二层是持久会话状态里面只放 Agent 需要在多轮对话中记住的业务事实比如“用户当前选中的订单编号”由 Agent 主流程显式写入。这两层的隔离规则很简单技能内部变量不许跨技能传递但如果技能想“让 Agent 记住某件事”必须写成明确的记忆写入操作。这种显式设计虽然多写几行代码但排查问题时能少掉一半脑细胞。4. 实操过程把第一个技能跑起来4.1 以“生成周报”技能为例空谈不如实操我用一个最常见的“生成周报”技能把完整流程走一遍。这个技能要干的事情是拉取过去七天的工单记录、按类型聚合、调用大模型生成总结、渲染成 Markdown、最后发给指定邮箱。第一步新建 skills/report/weekly_report 目录写 skill.yaml。关键点是 description 要写清楚使用边界否则模型会在不合适的时候乱调用。我是这么写的skill_id: report.generator.weekly name: 周报生成 description: 当用户要求生成周报、周总结、本周工作情况汇报时使用。 仅用于汇总过去七天的工单和任务数据不适用于日报或月报。 tasks: - 查询工单记录 - 聚合工单类型 - 生成总结文本 parameters: recipient_email: type: string description: 周报接收邮箱 nullable: false include_metrics: type: boolean default: true description: 是否包含统计数据表格 entry: module: implement function: generate_weekly_report metadata: version: 1.2.0 author: team tags: [report, weekly]这里想特别提醒一点description 里最好同时写“什么时候该用”和“什么时候不该用”。很多技能没写反面约束模型就很容易在用户说“帮我写个周计划”时误调“周报生成”。4.2 实现执行逻辑接着写 implement.py。这个文件里就是普通 Python 代码但有两个约定函数签名必须接收 context 和 params 两个参数返回值统一为 SkillResult 对象。加一个 context 参数是为了让技能能访问外部服务依赖又不用直接和全局变量耦合。import datetime from agent_skills.core.types import SkillContext, SkillResult async def generate_weekly_report(ctx: SkillContext, params: dict) - SkillResult: query_api ctx.services.get(ticket_client) start datetime.datetime.now() - datetime.timedelta(days7) tickets await query_api.list_tickets(start_timestart, end_timedatetime.datetime.now()) grouped aggregate_by_type(tickets) summary await ctx.llm.summarize(grouped) content render_markdown(grouped, summary, include_metricsparams[include_metrics]) await ctx.services.get(mailer).send(toparams[recipient_email], contentcontent) return SkillResult.ok({email: params[recipient_email], ticket_count: len(tickets)})写执行逻辑时最容易忽略的是超时。如果调用外部 API 三秒钟没响应技能卡在那里Agent 整轮对话就僵住了。我在所有技能里强制要求最长执行时间超时后返回一个明确的错误让 Agent 跟用户说“抱歉周报生成暂时不可用”而不是无限等待。4.3 注册与测试脚本技能写好后本地启动一个测试脚本把它注册进引擎然后模拟用户请求。我习惯用一个最小的 REPL 环境验证整个链路from agent_skills import AgentSkillsEngine from agent_skills.integrations.llm import make_llm async def main(): engine AgentSkillsEngine() await engine.register_from_directory(skills) llm make_llm(...) response await engine.handle(帮我生成这周的周报发到 opsexample.com) print(response) asyncio.run(main())第一次跑通后重点看两件事一是路由日志里是否选中了 report.generator.weekly二是最终发出的邮件里数据是否准确。我强烈建议每个技能都配一个“黄金用例集”里面包含 3 到 5 种不同说法比如“把本周工单总结发给我”和“汇总一下这七天的情况做成报告”用来验证路由稳定性。4.4 多轮交互里的技能切换单技能跑通之后难点在于多轮交互中技能之间的切换。Agent 用户很可能先问“今天多少工单”接着又说“顺便把周报发了吧”。这时 Agent 需要从“查询工单数据”的技能状态平滑切到“生成周报”技能。我的做法是每轮对话都重新做一次路由决策但会结合一个轻量级对话摘要把它拼到 query 里。这个摘要不要长能表达用户当前意图即可。比如“用户问过工单数量现在要求生成周报”这样路由模型就能准确判断新技能。摘要由主循环每两轮更新一次不用把所有聊天记录都塞给路由。这样可以显著降低 token 消耗也避免模型被历史信息带偏。5. 常见问题与排查实录5.1 技能引擎常见的五类故障把 agent-skills 跑了快半年我把最常遇到的故障整理成了表。这张表基本能覆盖新接入团队 80% 的尖叫时刻故障现象可能原因解决办法模型总选错技能description 写得太宽泛缺反面约束重写 description加入“不适用场景”技能调用后参数全是空值Schema 定义不规范没给默认值用 pydantic 严格校验加 auto_fill同一技能第一次调用成功第二次失败上下文残留了脏参数每次调用前创建独立 context结束后销毁技能执行超时外部系统响应慢没有超时控制全局强制超时配合重试和熔断热更新后技能行为仍是旧的注册表缓存未失效注册时带上版本号路由按版本选择其实这些问题的根源大多是“把技能当函数调用”的思维惯性。技能本身也是一个系统凡是系统就可能遇到并发、缓存、超时、状态管理问题。用工程化的眼光去治理它而不是靠堆提示词才是正道。5.2 排查思路与观测手段我先前的排查方式是看日志但 Chat 型 Agent 的日志里交织着模型推测、工具调用、上下文 token 统计非常难看。后来我给 agent-skills 专门加了一个结构化调用链记录一次完整技能调用会生成一条 trace里面包括 query 摘要、命中的 skill_id、模型填的参数、校验结果、执行耗时、返回值和错误信息。排查时我第一个看的就是 trace。如果路由选错技能那看“描述与意图是否匹配”如果参数错误看“模型填参前的候选列表”如果执行超时看“到底卡在哪个外部调用”。这套观测手段让我从“猜问题”变成了“看问题”团队新人也更容易上手。5.3 性能与成本优化建议最后聊聊成本和性能。agent-skills 的主要开销集中在模型调用上尤其是“路由精排”和“参数补全”这两次额外调用。为了省钱我做了三件事。第一精排候选数量设置上限。Top-K 从 10 减到 5准确率几乎不变但每个请求能省掉不少 token。第二把路由模型和对话模型分离。路由用一个更小的模型对话和总结用大模型。小模型做判断足够大模型负责生成内容。第三给相似技能的向量检索加缓存。如果用户连续几条消息意图相近不需要每次重新计算向量直接用上一次的候选集。性能层面技能的加载可以并行。注册多个目录时用 asyncio.gather 并发扫描起量后 CPU 消耗并不大。真正的瓶颈往往在技能内部的外部调用上所以实现技能时一定要用好连接池别每个请求都新建一次数据库连接。6. 写在最后给后来者的一些建议6.1 先别急着造框架把一两个技能跑通再说我见过太多团队一上来就搭技能管理平台画架构图、定规范、开会评审结果三个月还没跑通一个真实场景。agent-skills 能成型最重要的是我先快速做了四个技能查订单、查物流、生成周报、更新客户备注。跑通了这四个才知道共性在哪、痛点在哪。你想复刻这套也建议先选三到五个高频业务技能用最朴素的方式把它实现了再谈平台化。6.2 技能定义要拥抱变化但接口要保持稳定技能内容一定会频繁变尤其是 description 和参数示例。我每个迭代都会根据线上失败案例去微调 skill.yaml但注册表和调用器这两个核心接口几乎没有动过。稳定接口是内外部协作的关键。如果引擎接口动不动就 breaking change团队很快会失去信任技能数量也会停滞不前。6.3 试错时的个人心得我实际做下来的最大体会是Agent 技能不是一个技术问题而是一个管理问题。技术方案两个小时就能写出来难的是让每个人都愿意遵守“先声明、后实现、再注册、可观测”的规范。建议你在团队里先立一个简单的例子让产品、算法、后端都能读懂再慢慢推行。另外把每一次线上路由失败都当成 bug 处理不要归因于“模型笨”。模型只是反射了技能定义的模糊度和流程的设计漏洞改定义、改校验、改观测比换一个更大的模型更有用。如果后面你打算把 agent-skills 的边界再往外推可以试试加一个技能评审流程类似 code review任何人提交新技能都要过一遍声明文件、执行逻辑和测试用例。我当时偷懒省掉了这步后来线上出过几次可预期的低级事故补上评审之后整套系统的稳定性直接上了一个台阶。技能库做大的关键不是有多少技能而是每个技能都值得被信任。
说起来有点不好意思我的 agent-skills 这个项目最早是从一次“翻车现场”开始的。当时我正在做一个客服智能体对话能力已经调得挺顺用户问什么都能答上两句可一旦涉及“查订单状态—生成退款单—通知仓库”这种多步骤的真实业务流程模型就开始自由发挥有时候漏掉退款字段有时候调错内部接口有时候干脆把流程次序搞反。与其说是智能体在干活不如说是它在“即兴表演”。我后来复盘时想明白一件事对话可以靠模型临场发挥但能力不能。能力必须被显式地定义、注册、路由、可观测。于是就有了 agent-skills——一套把智能体的“技能”当作标准化资产来管理的轻量框架。这篇文章不聊大而全的平台只聊我在设计 agent-skills 时踩过的坑、想清楚的道理以及一套可以直接抄走的落地路径。如果你也在做 Agent 类应用遇到过“工具调用乱、技能复用难、上下文一多就崩”的问题那这篇应该能帮上忙。1. 项目定位agent-skills 到底在解决什么问题1.1 没有技能目录的 Agent能力全靠“现场发挥”很多人一开始做 Agent最自然的做法是把所有能力和工具说明一股脑塞进 system prompt。比如告诉模型“你可以调用 get_order、refund_order、send_notification 这三个函数”再给它一堆 JSON schema。这种方案在小 demo 里跑得通因为任务单一、工具少。可一旦业务复杂起来问题就慢慢冒出来了。首先是 prompt 长度失控。工具说明、参数约束、调用示例、异常码说明全堆在上下文里每轮对话都带着这堆东西走token 开销大不说模型还容易抓不住重点。其次是能力边界模糊。模型经常在不需要调用工具的时候自作主张调了工具或者该调工具的时候反而一本正经地胡编数据。第三是技能无法沉淀。你让人工把某个流程调通了下一周换一个 Agent 实例这些经验全丢还得重新来一遍。agent-skills 的核心主张就是别把技能当成 system prompt 里的几行描述把它当成可以注册、复用、测试、审计的一等公民。1.2 把技能当成标准化资产而不是提示词里的几行话我参考了很多平台里“技能市场”的灵感也借鉴了早期语义内核里插件注册表的设计最终确定了一个极简模型每一项技能包含三样东西——声明文件、执行逻辑、访问控制。声明文件负责描述技能“是什么、能干什么、需要什么参数、有什么前置条件”。执行逻辑负责真正做事可以是一段 Python 函数、一个 HTTP 调用封装甚至是一个 shell 脚本。访问控制则决定了哪些角色、哪些上下文可以触发这个技能。这三样解耦之后技能就成了标准的“插件”你甚至可以给甲方交付一个只包含声明文件加核心代码的技能包他接入自己的 Agent 时只需要跑一条注册命令。这套设计最大的好处是能力边界从模型手里收回到开发者手里。模型要做的事情退化为“理解用户意图选择一个技能填好参数”剩下的多步操作完全由技能内部保证。这大大降低了不可控感。1.3 这套东西到底适合谁我并不是要建议所有场景都上 agent-skills。如果你是做一个十分钟的问答 demo自然语言直接回答就够了没必要绕一层技能框架。但如果你遇到下面几种情况这套思路就很值得参照同一个能力要被多个 Agent 或场景复用不想重复维护提示词。流程里包含外部系统调用、权限检查、回调、状态持久化不能只靠模型自然语言描述。团队里有多个人同时在加能力需要统一管理入口和发布规范。线上出了事故你想追溯到“哪个技能、哪次调用、哪个参数”导致了错误。换句话说agent-skills 解决的问题不是“能不能让模型调用工具”而是“如何让工具调用变成一套可控、可维护、可复制的体系”。2. 整体设计与目录结构2.1 一个技能的最小信息单元在设计技能结构时我最关心一个原则让模型和开发者都能快速看懂“这个技能是干嘛的”。我见过很多技能定义写得像 API 文档的复制粘贴参数说明含糊不清示例给了等于没给。模型看到这种东西照样不会用。我把每个技能的最小信息单元收敛成七项skill_id全局唯一标识比如 report.generator.weekly。name面向模型和日志展示的名称。description不超过 200 字的自然语言描述必须说清楚“什么时候该用、什么时候不该用”。parametersJSON Schema 方式的参数定义每个参数都要有类型、必填性、默认值和示例。tasks可选字段列出技能内部会执行的主要步骤方便模型判断任务匹配度。policies权限、速率限制、超时策略等。entry指向执行逻辑的入口通常是一个函数名或可调用路径。metadata版本号、作者、标签、更新时间等治理信息。这七项不是拍脑袋定的。我最初少写了 tasks模型经常把“查天气”和“查航班”搞混因为两者的 description 里都出现了“查询信息”。后来在描述里增加了“典型任务场景”才把误命中率压下来。所以 tasks 看似冗余对于模型路由却有实际帮助。2.2 目录与文件约定agent-skills 的仓库结构目前长这样agent-skills/ ├── skills/ │ ├── report/ │ │ ├── weekly_report/ │ │ │ ├── skill.yaml │ │ │ ├── __init__.py │ │ │ └── implement.py │ │ └── daily_report/ │ │ ├── skill.yaml │ │ └── implement.py │ └── order/ │ └── refund/ │ ├── skill.yaml │ └── implement.py ├── core/ │ ├── registry.py │ ├── router.py │ ├── schema.py │ └── executor.py ├── tests/ └── examples/每个技能一个目录目录里 skill.yaml 管声明implement.py 管执行。core 里是引擎本身包括注册表、路由、参数校验和调用器。使用方不需要关心 core 的细节只需要往 skills 目录里丢技能包。我一开始也想把声明和执行写在同一个文件里后来发现当技能逻辑超过一百行时声明文件会被代码淹没非工程师侧的同学也看不懂。拆开之后产品同学可以 review skill.yaml工程同学专心改 implement.py边界舒服多了。2.3 为什么选 YAML 声明式 Python 实现当时也纠结过要不要用 JSON 或者 TOML 来写声明文件。JSON 的问题是注释缺失TOML 的类型表达能力又不够丰富。YAML 虽然缩进容易坑但它天然支持注释而且写复杂嵌套结构时的可读性最好。对于工程师来说YAML 确实是声明技能的及格线选择。执行逻辑用 Python 是顺手的事。生态里有 pydantic 做参数校验、有各类 HTTP 客户端、有 asyncio 做并发。技能内部还可以用 Python 写更细的流程编排比如重试、熔断、数据转换。声明与实现的分离核心目的不是语言洁癖而是让“路由决策”和“业务执行”各司其职。3. 核心实现从定义到调用的完整链路3.1 技能注册表启动时扫描 vs 运行时注册技能要能被调用第一步是进入注册表。我在 agent-skills 里同时支持两种注册方式。启动时扫描的做法是服务启动时遍历 skills 目录逐个读取 skill.yaml通过 pydantic 校验结构把技能对象塞进一个字典。这个方法的好处是简单、可预测适合技能列表相对稳定的生产环境。运行时注册的做法是暴露一个 register_skill 接口调用方在代码里动态传入技能定义适合做“插件热加载”或“用户自定义技能”等场景。两种方式我最后都保留因为真实业务中总会有“今天下午临时给大客户开一个特殊技能不想重新发版”的需求。运行时注册虽然灵活但一定要配合权限校验否则等于给攻击者开了一个代码执行入口。哪怕只在内部环境使用我也建议给注册接口加上鉴权和操作审计。核心注册表代码其实不长核心是避免重复注册和兼容热更新class SkillRegistry: def __init__(self): self._skills {} self._lock asyncio.Lock() async def register(self, skill: SkillDefinition): async with self._lock: if skill.skill_id in self._skills: raise SkillConflictError(skill.skill_id) self._skills[skill.skill_id] skill async def unregister(self, skill_id: str): async with self._lock: self._skills.pop(skill_id, None) def get(self, skill_id: str): return self._skills.get(skill_id)很多人会忽略重复注册的校验。我们线上曾经因为配置中心重复推送同一个技能被注册了两遍导致路由表里出现两个同名条目模型调用时随机命中其中一个行为时好时坏。所以这里用锁加重复校验不是小题大做。3.2 路由匹配从模糊意图到技能入口注册表解决的是“有哪些技能”路由解决的是“该用哪个技能”。agent-skills 没有走太复杂的 NLI 模型而是采用了一种多级匹配策略效果和成本比较均衡。第一级是向量召回。把用户当前消息或整段会话摘要编码成向量与每个技能的 description 和 tasks 编码后的向量做相似度检索找出 Top-K 候选技能。第二级是 LLM 精排。把候选技能的名称、描述、参数列表交给模型让模型输出一个 JSON 结构指定选中的技能和参数。这样既避免了纯向量匹配的“语义漂移”又省去了让 LLM 从几百个技能里大海捞针的开销。这里有一个我在实践中反复踩过的坑不要把整个技能描述原样丢给模型做精排模型会迷失在细节里。我最后把性价比最高的方式定为只把技能的 name、description 以及参数名列表传给模型。完整参数说明只在模型选择完技能后进入参数填写的第二阶段才给。这相当于把“选技能”和“填参数”拆成了两次模型调用虽然多了一次延迟但准确率明显提升。async def route(self, query: str, top_k: int 5): candidates await self.vector_store.search(query, top_k) simplified [ { skill_id: c.skill_id, name: c.name, description: c.description, parameter_names: list(c.parameters.keys()), } for c in candidates ] decision await self.llm.decide(query, simplified) return self._build_invocation(decision)3.3 参数校验与自动补全技能被选中后下一步是让模型填参数。这一步最烦的问题不是模型不会填而是填了错误的类型、填了没定义的字段、或者把东八区时间填成了 UTC 没有转换。我在 agent-skills 里引入两段式处理先做严格 Schema 校验再做启发式补全。严格校验用 pydantic 完成。model 根据参数的 JSON Schema 生成一个大致的参数对象校验器检查类型、枚举、必填项。校验失败时不是直接中断而是把错误信息返回给模型让它重新生成一次参数补全。这个“一次纠错机会”在生产环境非常有用。我统计过给模型一次纠错机会后参数填充成功率能从 84% 提升到 97% 左右。启发式补全解决的是模型留空的字段。比如“当前时间”“用户ID”“默认仓库编号”这些可以从上下文或配置中心自动获取的字段技能定义里可以标记为 auto_fill。补全逻辑必须在技能执行前做最好把补全后的参数快照写入日志方便事后稽核。3.4 上下文管理临时技能状态与持久记忆分离技能调用过程中最隐蔽的坑是上下文串扰。早期版本我图省事把技能的中间状态直接挂在会话上下文对象上。结果用户在一个会话里连续触发了“查询订单”“查询物流”“投诉登记”三个技能状态的 key 互相覆盖订单号被物流单号冲掉投诉登记里带上了前一个技能的残留参数。后来我把上下文拆成了两层。第一层是短期执行上下文每个技能调用都有独立的 context 对象技能结束后就丢弃内部的状态不会泄漏到其他技能。第二层是持久会话状态里面只放 Agent 需要在多轮对话中记住的业务事实比如“用户当前选中的订单编号”由 Agent 主流程显式写入。这两层的隔离规则很简单技能内部变量不许跨技能传递但如果技能想“让 Agent 记住某件事”必须写成明确的记忆写入操作。这种显式设计虽然多写几行代码但排查问题时能少掉一半脑细胞。4. 实操过程把第一个技能跑起来4.1 以“生成周报”技能为例空谈不如实操我用一个最常见的“生成周报”技能把完整流程走一遍。这个技能要干的事情是拉取过去七天的工单记录、按类型聚合、调用大模型生成总结、渲染成 Markdown、最后发给指定邮箱。第一步新建 skills/report/weekly_report 目录写 skill.yaml。关键点是 description 要写清楚使用边界否则模型会在不合适的时候乱调用。我是这么写的skill_id: report.generator.weekly name: 周报生成 description: 当用户要求生成周报、周总结、本周工作情况汇报时使用。 仅用于汇总过去七天的工单和任务数据不适用于日报或月报。 tasks: - 查询工单记录 - 聚合工单类型 - 生成总结文本 parameters: recipient_email: type: string description: 周报接收邮箱 nullable: false include_metrics: type: boolean default: true description: 是否包含统计数据表格 entry: module: implement function: generate_weekly_report metadata: version: 1.2.0 author: team tags: [report, weekly]这里想特别提醒一点description 里最好同时写“什么时候该用”和“什么时候不该用”。很多技能没写反面约束模型就很容易在用户说“帮我写个周计划”时误调“周报生成”。4.2 实现执行逻辑接着写 implement.py。这个文件里就是普通 Python 代码但有两个约定函数签名必须接收 context 和 params 两个参数返回值统一为 SkillResult 对象。加一个 context 参数是为了让技能能访问外部服务依赖又不用直接和全局变量耦合。import datetime from agent_skills.core.types import SkillContext, SkillResult async def generate_weekly_report(ctx: SkillContext, params: dict) - SkillResult: query_api ctx.services.get(ticket_client) start datetime.datetime.now() - datetime.timedelta(days7) tickets await query_api.list_tickets(start_timestart, end_timedatetime.datetime.now()) grouped aggregate_by_type(tickets) summary await ctx.llm.summarize(grouped) content render_markdown(grouped, summary, include_metricsparams[include_metrics]) await ctx.services.get(mailer).send(toparams[recipient_email], contentcontent) return SkillResult.ok({email: params[recipient_email], ticket_count: len(tickets)})写执行逻辑时最容易忽略的是超时。如果调用外部 API 三秒钟没响应技能卡在那里Agent 整轮对话就僵住了。我在所有技能里强制要求最长执行时间超时后返回一个明确的错误让 Agent 跟用户说“抱歉周报生成暂时不可用”而不是无限等待。4.3 注册与测试脚本技能写好后本地启动一个测试脚本把它注册进引擎然后模拟用户请求。我习惯用一个最小的 REPL 环境验证整个链路from agent_skills import AgentSkillsEngine from agent_skills.integrations.llm import make_llm async def main(): engine AgentSkillsEngine() await engine.register_from_directory(skills) llm make_llm(...) response await engine.handle(帮我生成这周的周报发到 opsexample.com) print(response) asyncio.run(main())第一次跑通后重点看两件事一是路由日志里是否选中了 report.generator.weekly二是最终发出的邮件里数据是否准确。我强烈建议每个技能都配一个“黄金用例集”里面包含 3 到 5 种不同说法比如“把本周工单总结发给我”和“汇总一下这七天的情况做成报告”用来验证路由稳定性。4.4 多轮交互里的技能切换单技能跑通之后难点在于多轮交互中技能之间的切换。Agent 用户很可能先问“今天多少工单”接着又说“顺便把周报发了吧”。这时 Agent 需要从“查询工单数据”的技能状态平滑切到“生成周报”技能。我的做法是每轮对话都重新做一次路由决策但会结合一个轻量级对话摘要把它拼到 query 里。这个摘要不要长能表达用户当前意图即可。比如“用户问过工单数量现在要求生成周报”这样路由模型就能准确判断新技能。摘要由主循环每两轮更新一次不用把所有聊天记录都塞给路由。这样可以显著降低 token 消耗也避免模型被历史信息带偏。5. 常见问题与排查实录5.1 技能引擎常见的五类故障把 agent-skills 跑了快半年我把最常遇到的故障整理成了表。这张表基本能覆盖新接入团队 80% 的尖叫时刻故障现象可能原因解决办法模型总选错技能description 写得太宽泛缺反面约束重写 description加入“不适用场景”技能调用后参数全是空值Schema 定义不规范没给默认值用 pydantic 严格校验加 auto_fill同一技能第一次调用成功第二次失败上下文残留了脏参数每次调用前创建独立 context结束后销毁技能执行超时外部系统响应慢没有超时控制全局强制超时配合重试和熔断热更新后技能行为仍是旧的注册表缓存未失效注册时带上版本号路由按版本选择其实这些问题的根源大多是“把技能当函数调用”的思维惯性。技能本身也是一个系统凡是系统就可能遇到并发、缓存、超时、状态管理问题。用工程化的眼光去治理它而不是靠堆提示词才是正道。5.2 排查思路与观测手段我先前的排查方式是看日志但 Chat 型 Agent 的日志里交织着模型推测、工具调用、上下文 token 统计非常难看。后来我给 agent-skills 专门加了一个结构化调用链记录一次完整技能调用会生成一条 trace里面包括 query 摘要、命中的 skill_id、模型填的参数、校验结果、执行耗时、返回值和错误信息。排查时我第一个看的就是 trace。如果路由选错技能那看“描述与意图是否匹配”如果参数错误看“模型填参前的候选列表”如果执行超时看“到底卡在哪个外部调用”。这套观测手段让我从“猜问题”变成了“看问题”团队新人也更容易上手。5.3 性能与成本优化建议最后聊聊成本和性能。agent-skills 的主要开销集中在模型调用上尤其是“路由精排”和“参数补全”这两次额外调用。为了省钱我做了三件事。第一精排候选数量设置上限。Top-K 从 10 减到 5准确率几乎不变但每个请求能省掉不少 token。第二把路由模型和对话模型分离。路由用一个更小的模型对话和总结用大模型。小模型做判断足够大模型负责生成内容。第三给相似技能的向量检索加缓存。如果用户连续几条消息意图相近不需要每次重新计算向量直接用上一次的候选集。性能层面技能的加载可以并行。注册多个目录时用 asyncio.gather 并发扫描起量后 CPU 消耗并不大。真正的瓶颈往往在技能内部的外部调用上所以实现技能时一定要用好连接池别每个请求都新建一次数据库连接。6. 写在最后给后来者的一些建议6.1 先别急着造框架把一两个技能跑通再说我见过太多团队一上来就搭技能管理平台画架构图、定规范、开会评审结果三个月还没跑通一个真实场景。agent-skills 能成型最重要的是我先快速做了四个技能查订单、查物流、生成周报、更新客户备注。跑通了这四个才知道共性在哪、痛点在哪。你想复刻这套也建议先选三到五个高频业务技能用最朴素的方式把它实现了再谈平台化。6.2 技能定义要拥抱变化但接口要保持稳定技能内容一定会频繁变尤其是 description 和参数示例。我每个迭代都会根据线上失败案例去微调 skill.yaml但注册表和调用器这两个核心接口几乎没有动过。稳定接口是内外部协作的关键。如果引擎接口动不动就 breaking change团队很快会失去信任技能数量也会停滞不前。6.3 试错时的个人心得我实际做下来的最大体会是Agent 技能不是一个技术问题而是一个管理问题。技术方案两个小时就能写出来难的是让每个人都愿意遵守“先声明、后实现、再注册、可观测”的规范。建议你在团队里先立一个简单的例子让产品、算法、后端都能读懂再慢慢推行。另外把每一次线上路由失败都当成 bug 处理不要归因于“模型笨”。模型只是反射了技能定义的模糊度和流程的设计漏洞改定义、改校验、改观测比换一个更大的模型更有用。如果后面你打算把 agent-skills 的边界再往外推可以试试加一个技能评审流程类似 code review任何人提交新技能都要过一遍声明文件、执行逻辑和测试用例。我当时偷懒省掉了这步后来线上出过几次可预期的低级事故补上评审之后整套系统的稳定性直接上了一个台阶。技能库做大的关键不是有多少技能而是每个技能都值得被信任。
