agent-skills我是怎么把AI智能体从“聊天玩具”调教成“能干活同事”的先说清楚这文章写的是什么过去几个月我一直在搞一个叫 agent-skills 的技能库项目。它不是某个大厂发布的框架也不是什么开箱即用的产品而是一套让我手里的AI智能体真正开始干活的方法论加落地代码。如果你也被“AI很聪明但啥都干不成”这个悖论折磨过或者你刚接手一个Agent项目正在为怎么设计技能目录、怎么写技能描述、怎么控制token成本发愁这篇文章应该能让你少走至少两个月的弯路。整件事的起点挺朴素我手上有十几个GPT类模型接口、一个能跑函数调用的后端服务、一堆内部工具的API文档但这堆东西放在一起什么都做不了。和我对话的AI能写诗、能解数学题、能一本正经地胡说八道但你要它“帮我把这几个Excel合并了顺便提取出销售额最高的三条记录发到群里”它就懵了。不是模型不够聪明是模型没有“手脚”。后来我把“技能”这个概念从ChatGPT的Plugin和OpenAI的Function Calling里拆了出来做成了独立于模型之外的技能层。真正运行起来之后我的Agent才从“只会聊天的实习生”变成了“能独立推进任务的同事”。这篇文章捋一遍我在 agent-skills 项目里做的核心设计决策、踩过的坑、还有抄作业级别的实践步骤。1. 技能机制是怎么火起来的从对话玩具到能干活工具的进化拐点在动手写任何一行代码之前得先搞清楚Agent为什么需要技能层以及这一层和传统的API调用到底差在哪。这个认知不到位后面所有设计都会走偏。1.1 一次失败的项目给我上的课模型再聪明没有手脚也白搭去年下半年我做了一个内部知识库问答机器人技术栈没毛病向量数据库、Rerank、大模型流式输出全部到位演示的时候领导连连点头。但一到真实业务场景就翻车——运营同事问“帮我统计一下这周各渠道的退款率超过5%的渠道重点标注”机器人只能回复一大段“您可以通过XX报表查看”的官话。气得我要死。因为统计逻辑非常简单报表接口我早就封装好了。问题出在哪出在模型不知道自己有工具可以用也不知道用户这句话切换到业务场景里其实是一次包含“取数、计算、格式化、输出预警名单”的连续操作。这就是Agent和ChatBot的分水岭ChatBot负责把话说好Agent负责把事办成。而“办成”的载体就是技能。1.2 技能的准确定义一次把大模型、参数、工具函数串起来的完整行为单元我想给 agent-skills 里“技能”下一个精确的、可用于工程实现的定义技能是一段结构化的说明加上一组可执行的代码/配置它告诉模型“在什么情境下、按照什么步骤、调用哪个工具、拿到结果后怎么处理”而不是简单地暴露一个函数签名让模型自己猜。用最直白的生活类比来说API是螺丝刀技能是“用螺丝刀把机箱侧板拆下来并妥善放置”这一整套动作。你给一个新人一把螺丝刀他大概率不知道怎么下手你给他一份图文并茂的拆机SOP他就能干。这个观念转变是 agent-skills 整个项目的架构基石后续的目录设计、描述模板、评估体系全是从它生长出来的。2. 第一次搭技能库我踩中的三个隐形坑这部分不按教科书路子来直接从我的失败经验切入。你要是正在设计自己的技能体系下面这三条能帮你躲掉绝大多数低级问题。2.1 坑一把技能写成了API文档模型根本读不进去第一版技能描述我写得像后端接口文档每条技能长这样- 功能汇率换算 - 参数amount: float, from_currency: string, to_currency: string - 返回result: float结果模型调用率低得惊人。回头分析日志才发现原因模型不是不知道有“汇率换算”这个工具而是不知道用户哪句话应该触发它。“3000元折合多少美元”这句话里没有“汇率”两个字模型匹配不上。后来我把技能描述从“工具接口”重构成了“业务语义”加了触发场景、口语示例、边界条件- 触发场景用户意图涉及“换钱”“折合”“相当于多少外币”等表述无论是否提到汇率二字 - 口语示例“3000块是多少美金”“帮我看看今天日元价格” - 参数说明金额、原始币种、目标币种币种需归一化为ISO三字母代码 - 边界处理当金额超过10万或币种不支持时必须向用户二次确认改动之后同一个技能调用率提升了三倍多。这件事让我意识到技能描述是给模型这个“特殊员工”看的岗位说明书不是给工程师看的API文档。你写的东西必须贴合模型的语义理解方式。2.2 坑二把技能做成了单体耦合到不敢动最初为了快速上线我把七八个相关功能塞进了一个大的data_analysis_skill函数里表面上模块化实际上内部一个函数几十个参数每个参数还要根据来源加前缀区分。后来需求一变更问题就炸了运营想调整报表维度产品想换图表类型每一项改动都动到“技能”这个整体测试一次要连带跑完所有子功能发布窗口从半小时拖到半天。我用了两周做重构把单体技能拆成原子技能。举个例子“生成周报”不再是一个技能而是“查询数据、生成表格、生成总结、推送消息”四个独立技能的组合。调用时由模型自行规划调用顺序而不是我在代码里写死。每一块都能独立测试、独立迭代、独立回滚这才是技能库该有的样子。2.3 坑三依赖模型超能力没有兜底机制我在早期特别迷信大模型的Instruction Following能力觉得只要提示词写到位模型就能正确调用技能。事实证明幻觉和“自作主张”在任务型场景里比对话场景更致命。印象最深的翻车现场一个查询天气的技能模型没调用天气API而是基于训练数据知识在回答里自己编了一个20度晴天的天气情况。为什么因为大模型的很多训练数据里本身包含一些真实的、但过期的天气信息模型在响应技能描述时被“先入为主”带偏了。从那以后我定了条死规矩凡是技能声明了要调用工具的必须对工具返回结果做结构化校验模型输出的最终答案里必须携带工具返回的数据指纹否则判为无效调用。宁可多一次确认、多一次报错也不能让AI把编的内容端给业务方。3. 自省设计让技能库自己知道自己有什么用如果把技能库看成一支团队每个技能是一个成员那还缺一个统筹全局的角色它知道团队里有什么人、每个人擅长什么、什么活儿该找谁。3.1 技能注册表给所有技能做“身份登记”agent-skills 项目里有一个 SKILLS.md 文件我私下管它叫“技能花名册”。花名册写清楚每个技能的元数据包括技能名称、版本号、功能摘要、依赖关系、负责人维护人联系方式、最后验证时间。别小看这些信息。在项目中期技能数量超过二十个的时候我靠这个花名册才把混乱理清楚——哪个技能过时了、哪个技能和哪个技能功能重叠一目了然。它也直接决定了启动时加载哪些技能进系统提示词而不是每次对话把所有技能描述一股脑塞给模型。用工程术语说这是技能的动态路由依据。模型每拿到一次任务系统会先在花名册里做一轮粗筛把与任务不相关的技能直接踢出去。后来我统计过这个粗筛机制一加上API的token消耗直接降低了接近一半。原因很简单技能描述少了模型在无关技能上产生的“选择困难”就少了上下文窗口也宽敞多了。3.2 技能描述模板为什么我用“岗位JD”格式而不是“代码注释”格式我把每个技能的描述文件单独拆出来放在skills/skill_name/SKILL.md。这个文件是技能的灵魂模型能不能正确触发和调用七成靠它。我打磨出的描述模板分为六段身份与目标这个技能存在的意义一句话说清触发条件什么样的用户请求应该用这个技能包含正例和反例执行步骤具体到先调用哪个工具、中间如何解析结果、最后如何整理输出参数规范参数的类型、格式、默认值、取值范围、单位必须有示例边界与异常什么情况必须停止、什么情况需要向用户确认、什么情况要降级处理质量要求输出的格式、长度、风格以及不能出现的错误举个例子一个“应用内搜索”技能的“执行步骤”是这么写的1. 解析用户查询去停用词提取核心关键词 2. 调用 SearchTool (query关键词, filter可选过滤条件, limit10) 3. 对返回的10条结果进行相关度排序 4. 优先筛选 statepublished 且发布时间在30天内 5. 输出前3条附标题、摘要、发布时间如果结果少于3条必须向用户说明搜索范围较窄用岗位JD的思维写技能描述效果立竿见影。模型不再像一个刚毕业的学生对着接口文档发愣而是像一个入职第一天就拿到了完整SOP的老员工。3.3 技能血缘关系和版本管理改了一个底层工具怎么知道哪些技能受影响技能之间不是孤立的。很多技能会复用同一个底层API或者同一个通用函数这就会引发连锁反应——底层工具改了行为上层一堆技能全部失效而你根本不知道。我的解决方案是在注册表里建立一张轻量的依赖表。每次构建新的技能版本时跑一个依赖检查脚本把“技能 → 底层工具/API → 外部服务”的关系列出来。任何依赖变化都会在花名册里标记为dirty状态提醒我对受影响的技能重新跑一遍测试套件。这套机制不是一次到位是踩了两次“悄悄改坏”的坑才补上的。现在我的提交规范是改底层工具必须同步提交受影响技能的测试结果否则代码审查不过。听起来繁琐但长期回报非常大尤其是你打算在一个技能数量超过20个的库上做持续迭代时这类基础设施就是你的生命线。4. 手写一个技能的全过程从需求拆解到测试跑通的实操复盘理论说多了没用直接走一遍我在 agent-skills 项目里调试最久、也最常被复用的“语义搜索摘要生成”技能的完整开发流程。你拿到手就能照着改。4.1 明确技能边界不做什么比做什么更重要在写任何代码之前要先画清楚技能的边界。 “语义搜索摘要生成”听起来很清晰但仔细一想全是问题搜什么范围的文档是搜内部知识库还是公网网页摘要长度多少哪个模型生成摘要摘要风格是客观复述还是带解读用户明确只想要答案不要摘要时怎么办我花了一下午把所有边界问题整理成了一张决策表确定了“只能检索预先授权的知识库”“摘要由独立模型生成控制在200字以内”“若用户要求时间敏感数据必须标注数据截止日期”等硬性规则。这一步的价值在于你把模糊的自然语言需求固化成了模型可以判断的确定性规则。4.2 搭建技能的骨架代码和自省描述技能本身不复杂核心是一个run(query, filters)方法。但为了配合agent-skills自省机制必须额外实现一个can_handle(query)判定函数用来做初筛路由。# skills/kb_summery/skill.py class KBSummarySkill: name knowledge_base_summary version 2.3.0 def can_handle(self, query: str) - float: 返回0~1的置信度超过0.7才进入候选 keywords [总结, 摘要, 要点, 综述, 这篇, 这个文档] score sum(1 for kw in keywords if kw in query) return min(score / 2, 1.0) def run(self, query: str, filters: dict None): docs self.search(query, filters) if not docs: return {status: empty, message: 没有找到相关文档} summary self.generate_summary(docs) return { status: ok, summary: summary, sources: [d[url] for d in docs[:3]], data_fingerprint: hashlib.md5( json.dumps(docs, ensure_asciiFalse).encode() ).hexdigest() }关键的设计点在于返回值里加了data_fingerprint这个数据指纹是用来给主Agent做真实性校验的如果模型生成的最终回答里没有引用这个指纹对应的数据系统就知道它要么没调用工具要么就是在自由发挥。4.3 测试技能别只测“正常流”必须测“意外流”技能写完之后我建的测试规则是“两条正常路径、五条异常路径、两条对抗路径”。正常路径覆盖常规提问和模糊商品词追问异常路径覆盖搜不到结果、文档解析失败、摘要模型超时对抗路径覆盖用户故意用歧义句诱导错误触发、以及用户要求技能越权摘取未授权内容。对抗路径测试特别重要。举个例子用户说“帮我总结一下最近股市走势”如果技能库里只有“内部知识库总结”技能它的can_handle判定是高的但实际上它没有能力获取实时股市数据。这时候就考验技能在“边界与异常”里如何自证不适用——正确的做法是返回一个“超出本技能能力范围”的置信度低信号让路由层重新匹配其他技能而不是硬接任务然后编数据。5. Token成本、延迟和失败率技能库的三本经济账技能库跑通功能只是第一步。真正放到生产环境你会发现三个拦路虎费用、延迟、失败率。agent-skills 项目里我做了不少针对性的优化这些经验在很多Agent项目里都通用。5.1 Token成本核算一个被忽略的大头是“技能描述反复进入上下文”很多人算Agent调用成本时只算了主对话的input和output token忽略了每次请求都要把可用技能的描述拼进系统提示词里传输一遍。如果技能库有20个技能每个技能描述平均500个token那光技能描述一次请求就吃掉1万token。对于一个高频调用的Agent服务这可不是小数目。我的优化方案是多级路由第一级用一个轻量模型比如带分类能力的embedding模型对用户query做粗分类把候选技能从20个过滤到5个以内第二级再把这5个技能的详细描述拼进完整系统提示词第三级执行阶段用运行日志验证调用实际命中情况反馈给粗分类层持续调参这三级漏斗让单次请求的token开销从1万左右降到两千成本直接下降近八成而没有牺牲功能完整性。5.2 延迟优化串行调用改并行注意工具之间的依赖关系多个技能并行执行时延迟收益很大。但要注意技能之间的依赖关系决定了能否并行。比如“搜索相关文档”和“生成摘要”有明确的先后关系就只能串行而“搜索技术文档”和“查询API状态”互不依赖就可以丢进线程池并发执行。我在技能声明里加了一个dependencies字段专门标记与当前技能有依赖关系的其他技能。调度器在规划执行计划时会自动构建一个有向无环图DAG在这里我用手写拓扑排序实现没有引入重量级框架能并行的绝不串行必须串行的自动排好顺序。这个改造完成后一个典型的多技能复合任务的端到端延迟大约减少了40%。5.3 失败率治理失败不可怕可怕的是失败藏起来Agent技能调用的失败率和普通API的失败率不是一个量级。普通API失败会抛异常回去Agent却会尝试“智能地”绕过错误然后给出一个貌似正常的回答这是最危险的。我的对策是强制要求技能在遇到异常时返回结构化错误并且把错误信息原样暴露给上层不允许技能内部“吞掉”异常。对用户展示暂时无法完成XX原因检索服务超时请稍后再试 对监控系统展示skillkb_summary errortimeout_duration5s attempt3加了这个机制后故障定位时间从小时级降低到了分钟级。而且用户收到的反馈不再是AI编造的“系统一切正常”而是明确知道哪里出了问题。6. 两个生产环境的实战案例拆解技能组合的调用逻辑理论框架再完整也得在真实场景里压一压。这里分享两个投入生产使用最多的场景它们都依赖多个技能协作完成。6.1 案例一多技能协作的“工单分诊”机器人场景是处理客服工单用户提交一条描述系统自动打标、判定紧急程度、查询相似历史工单、给出建议分类和解决方案。最初实现时我把所有逻辑塞进一个巨大的“工单处理”技能里结果模型在步骤衔接处频繁出错比如先查询历史工单再打标把无关的历史记录带进了分类预测里。重构后拆成五个技能工单标签抽取用少量关键词和正则从描述中提取标签历史工单检索根据标签和描述向量检索相似工单紧急度判定根据描述中的时间表述和业务规则输出高/中/低三级解决方案推荐基于历史工单的处理结果做推荐工单摘要生成把所有信息汇总为一段不超过80字的摘要调度层根据工单类型动态组合这些技能。比如退款类工单直接走“历史工单检索解决方案推荐”投诉类工单则额外挂“紧急度判定”和“标签抽取”。技能化改造之后工单处理准确率从原来的78%提升到了92%。6.2 案例二一个技能的两次迭代从“能用”到“好用”第二个例子说迭代。最开始我的“周报生成”技能只是把固定模板套上去把数据填进去输出一份静态报告。第一次迭代我在技能描述里加了“洞察生成”步骤——在关键指标变化超过阈值时自动追加原因分析建议。第二次迭代我加了一个“可读性校验”步骤——生成内容超过设定字数时必须自动压缩表述并确保关键数字不丢失。每一次迭代的流程都一样先在测试技能库里调整描述和代码用历史周报数据做回归验证再小流量灰度到真实周报任务跑一周看反馈再全量放开。这个流程让我在迭代过程中从没有引入新的重大bug。7. 关于技能库的演进方向与我的最终建议折腾了整个 agent-skills 项目之后我对技能库这个设计模式有了更清晰的判断。它不会是终极形态但至少在未来两年内它会是Agent从玩具走向工具的最务实路径。7.1 自动生成技能让Agent自己写新技能边界在哪里一个自然的演进方向是“技能生成技能”——Agent在遇到无法处理的新任务时自己编写一个新的技能描述并注册进库。理论上这可行我甚至在实验环境里做过简化版本Agent根据用户的多次请求模式归纳出一个新技能的初始版本交给人工审核后入库。但我要泼一盆冷水现阶段自动生成的技能描述质量波动很大尤其是边界定义部分经常忽略异常场景。我的建议是自动生成的技能只能作为“候选草稿”必须经过人工评审和测试流程才能进入生产环境。完全放手让模型自迭代你迟早会被“技能库自己膨胀到失控”反噬。7.2 个人实践中的三条底层经验第一技能描述像文档一样需要持续维护。模型版本升级、工具API微调、业务规则变化都会让旧技能描述逐渐失真。我给每个技能设了“过期时间”超过一个月没有通过的测试自动触发告警。第二技能并非越多越好精而少才是王道。技能库里每个技能都占用上下文窗口、增加路由决策复杂度、提升测试覆盖成本。一个能覆盖80%需求的10个技能库远好于一个覆盖95%需求但管理混乱的50个技能库。第三永远不要相信模型在没有调用技能的情况下给出的“答案”。你再怎么调优技能描述和路由机制也架不住模型基于训练记忆的自信编造。这个原则我会继续坚持。7.3 如果你要从零开始做技能库我的最小落地清单第一个技能选一个高频、低风险、逻辑清晰的任务不要一上来就做复杂编排给每个技能单独建目录SKILL.md 按“身份目标、触发条件、执行步骤、参数规范、边界异常、质量要求”六段来写注册表里记录版本号、依赖关系和最后验证时间一旦依赖变化立刻标记待测返回结果里加数据指纹或其他可校验标识杜绝无根据输出测试不只测正常路径必须覆盖查无结果、接口超时、边界参数、对抗性歧义先把成本统计埋点做好再谈优化没有数据的优化都是盲人摸象我做完 agent-skills 这套体系后最大的感知是AI智能体的能力上限不取决于底层大模型有多强而取决于你给了它多少高质量、边界清晰、可验证的行动单元。把技能库当成一支高素质团队来经营——招人宁缺毋滥、岗位说明书要清晰、日常有绩效评估、变化有版本管理这支团队才能真正帮你把事办成。 从聊天玩具到能干活同事：构建AI Agent技能库的实战指南
agent-skills我是怎么把AI智能体从“聊天玩具”调教成“能干活同事”的先说清楚这文章写的是什么过去几个月我一直在搞一个叫 agent-skills 的技能库项目。它不是某个大厂发布的框架也不是什么开箱即用的产品而是一套让我手里的AI智能体真正开始干活的方法论加落地代码。如果你也被“AI很聪明但啥都干不成”这个悖论折磨过或者你刚接手一个Agent项目正在为怎么设计技能目录、怎么写技能描述、怎么控制token成本发愁这篇文章应该能让你少走至少两个月的弯路。整件事的起点挺朴素我手上有十几个GPT类模型接口、一个能跑函数调用的后端服务、一堆内部工具的API文档但这堆东西放在一起什么都做不了。和我对话的AI能写诗、能解数学题、能一本正经地胡说八道但你要它“帮我把这几个Excel合并了顺便提取出销售额最高的三条记录发到群里”它就懵了。不是模型不够聪明是模型没有“手脚”。后来我把“技能”这个概念从ChatGPT的Plugin和OpenAI的Function Calling里拆了出来做成了独立于模型之外的技能层。真正运行起来之后我的Agent才从“只会聊天的实习生”变成了“能独立推进任务的同事”。这篇文章捋一遍我在 agent-skills 项目里做的核心设计决策、踩过的坑、还有抄作业级别的实践步骤。1. 技能机制是怎么火起来的从对话玩具到能干活工具的进化拐点在动手写任何一行代码之前得先搞清楚Agent为什么需要技能层以及这一层和传统的API调用到底差在哪。这个认知不到位后面所有设计都会走偏。1.1 一次失败的项目给我上的课模型再聪明没有手脚也白搭去年下半年我做了一个内部知识库问答机器人技术栈没毛病向量数据库、Rerank、大模型流式输出全部到位演示的时候领导连连点头。但一到真实业务场景就翻车——运营同事问“帮我统计一下这周各渠道的退款率超过5%的渠道重点标注”机器人只能回复一大段“您可以通过XX报表查看”的官话。气得我要死。因为统计逻辑非常简单报表接口我早就封装好了。问题出在哪出在模型不知道自己有工具可以用也不知道用户这句话切换到业务场景里其实是一次包含“取数、计算、格式化、输出预警名单”的连续操作。这就是Agent和ChatBot的分水岭ChatBot负责把话说好Agent负责把事办成。而“办成”的载体就是技能。1.2 技能的准确定义一次把大模型、参数、工具函数串起来的完整行为单元我想给 agent-skills 里“技能”下一个精确的、可用于工程实现的定义技能是一段结构化的说明加上一组可执行的代码/配置它告诉模型“在什么情境下、按照什么步骤、调用哪个工具、拿到结果后怎么处理”而不是简单地暴露一个函数签名让模型自己猜。用最直白的生活类比来说API是螺丝刀技能是“用螺丝刀把机箱侧板拆下来并妥善放置”这一整套动作。你给一个新人一把螺丝刀他大概率不知道怎么下手你给他一份图文并茂的拆机SOP他就能干。这个观念转变是 agent-skills 整个项目的架构基石后续的目录设计、描述模板、评估体系全是从它生长出来的。2. 第一次搭技能库我踩中的三个隐形坑这部分不按教科书路子来直接从我的失败经验切入。你要是正在设计自己的技能体系下面这三条能帮你躲掉绝大多数低级问题。2.1 坑一把技能写成了API文档模型根本读不进去第一版技能描述我写得像后端接口文档每条技能长这样- 功能汇率换算 - 参数amount: float, from_currency: string, to_currency: string - 返回result: float结果模型调用率低得惊人。回头分析日志才发现原因模型不是不知道有“汇率换算”这个工具而是不知道用户哪句话应该触发它。“3000元折合多少美元”这句话里没有“汇率”两个字模型匹配不上。后来我把技能描述从“工具接口”重构成了“业务语义”加了触发场景、口语示例、边界条件- 触发场景用户意图涉及“换钱”“折合”“相当于多少外币”等表述无论是否提到汇率二字 - 口语示例“3000块是多少美金”“帮我看看今天日元价格” - 参数说明金额、原始币种、目标币种币种需归一化为ISO三字母代码 - 边界处理当金额超过10万或币种不支持时必须向用户二次确认改动之后同一个技能调用率提升了三倍多。这件事让我意识到技能描述是给模型这个“特殊员工”看的岗位说明书不是给工程师看的API文档。你写的东西必须贴合模型的语义理解方式。2.2 坑二把技能做成了单体耦合到不敢动最初为了快速上线我把七八个相关功能塞进了一个大的data_analysis_skill函数里表面上模块化实际上内部一个函数几十个参数每个参数还要根据来源加前缀区分。后来需求一变更问题就炸了运营想调整报表维度产品想换图表类型每一项改动都动到“技能”这个整体测试一次要连带跑完所有子功能发布窗口从半小时拖到半天。我用了两周做重构把单体技能拆成原子技能。举个例子“生成周报”不再是一个技能而是“查询数据、生成表格、生成总结、推送消息”四个独立技能的组合。调用时由模型自行规划调用顺序而不是我在代码里写死。每一块都能独立测试、独立迭代、独立回滚这才是技能库该有的样子。2.3 坑三依赖模型超能力没有兜底机制我在早期特别迷信大模型的Instruction Following能力觉得只要提示词写到位模型就能正确调用技能。事实证明幻觉和“自作主张”在任务型场景里比对话场景更致命。印象最深的翻车现场一个查询天气的技能模型没调用天气API而是基于训练数据知识在回答里自己编了一个20度晴天的天气情况。为什么因为大模型的很多训练数据里本身包含一些真实的、但过期的天气信息模型在响应技能描述时被“先入为主”带偏了。从那以后我定了条死规矩凡是技能声明了要调用工具的必须对工具返回结果做结构化校验模型输出的最终答案里必须携带工具返回的数据指纹否则判为无效调用。宁可多一次确认、多一次报错也不能让AI把编的内容端给业务方。3. 自省设计让技能库自己知道自己有什么用如果把技能库看成一支团队每个技能是一个成员那还缺一个统筹全局的角色它知道团队里有什么人、每个人擅长什么、什么活儿该找谁。3.1 技能注册表给所有技能做“身份登记”agent-skills 项目里有一个 SKILLS.md 文件我私下管它叫“技能花名册”。花名册写清楚每个技能的元数据包括技能名称、版本号、功能摘要、依赖关系、负责人维护人联系方式、最后验证时间。别小看这些信息。在项目中期技能数量超过二十个的时候我靠这个花名册才把混乱理清楚——哪个技能过时了、哪个技能和哪个技能功能重叠一目了然。它也直接决定了启动时加载哪些技能进系统提示词而不是每次对话把所有技能描述一股脑塞给模型。用工程术语说这是技能的动态路由依据。模型每拿到一次任务系统会先在花名册里做一轮粗筛把与任务不相关的技能直接踢出去。后来我统计过这个粗筛机制一加上API的token消耗直接降低了接近一半。原因很简单技能描述少了模型在无关技能上产生的“选择困难”就少了上下文窗口也宽敞多了。3.2 技能描述模板为什么我用“岗位JD”格式而不是“代码注释”格式我把每个技能的描述文件单独拆出来放在skills/skill_name/SKILL.md。这个文件是技能的灵魂模型能不能正确触发和调用七成靠它。我打磨出的描述模板分为六段身份与目标这个技能存在的意义一句话说清触发条件什么样的用户请求应该用这个技能包含正例和反例执行步骤具体到先调用哪个工具、中间如何解析结果、最后如何整理输出参数规范参数的类型、格式、默认值、取值范围、单位必须有示例边界与异常什么情况必须停止、什么情况需要向用户确认、什么情况要降级处理质量要求输出的格式、长度、风格以及不能出现的错误举个例子一个“应用内搜索”技能的“执行步骤”是这么写的1. 解析用户查询去停用词提取核心关键词 2. 调用 SearchTool (query关键词, filter可选过滤条件, limit10) 3. 对返回的10条结果进行相关度排序 4. 优先筛选 statepublished 且发布时间在30天内 5. 输出前3条附标题、摘要、发布时间如果结果少于3条必须向用户说明搜索范围较窄用岗位JD的思维写技能描述效果立竿见影。模型不再像一个刚毕业的学生对着接口文档发愣而是像一个入职第一天就拿到了完整SOP的老员工。3.3 技能血缘关系和版本管理改了一个底层工具怎么知道哪些技能受影响技能之间不是孤立的。很多技能会复用同一个底层API或者同一个通用函数这就会引发连锁反应——底层工具改了行为上层一堆技能全部失效而你根本不知道。我的解决方案是在注册表里建立一张轻量的依赖表。每次构建新的技能版本时跑一个依赖检查脚本把“技能 → 底层工具/API → 外部服务”的关系列出来。任何依赖变化都会在花名册里标记为dirty状态提醒我对受影响的技能重新跑一遍测试套件。这套机制不是一次到位是踩了两次“悄悄改坏”的坑才补上的。现在我的提交规范是改底层工具必须同步提交受影响技能的测试结果否则代码审查不过。听起来繁琐但长期回报非常大尤其是你打算在一个技能数量超过20个的库上做持续迭代时这类基础设施就是你的生命线。4. 手写一个技能的全过程从需求拆解到测试跑通的实操复盘理论说多了没用直接走一遍我在 agent-skills 项目里调试最久、也最常被复用的“语义搜索摘要生成”技能的完整开发流程。你拿到手就能照着改。4.1 明确技能边界不做什么比做什么更重要在写任何代码之前要先画清楚技能的边界。 “语义搜索摘要生成”听起来很清晰但仔细一想全是问题搜什么范围的文档是搜内部知识库还是公网网页摘要长度多少哪个模型生成摘要摘要风格是客观复述还是带解读用户明确只想要答案不要摘要时怎么办我花了一下午把所有边界问题整理成了一张决策表确定了“只能检索预先授权的知识库”“摘要由独立模型生成控制在200字以内”“若用户要求时间敏感数据必须标注数据截止日期”等硬性规则。这一步的价值在于你把模糊的自然语言需求固化成了模型可以判断的确定性规则。4.2 搭建技能的骨架代码和自省描述技能本身不复杂核心是一个run(query, filters)方法。但为了配合agent-skills自省机制必须额外实现一个can_handle(query)判定函数用来做初筛路由。# skills/kb_summery/skill.py class KBSummarySkill: name knowledge_base_summary version 2.3.0 def can_handle(self, query: str) - float: 返回0~1的置信度超过0.7才进入候选 keywords [总结, 摘要, 要点, 综述, 这篇, 这个文档] score sum(1 for kw in keywords if kw in query) return min(score / 2, 1.0) def run(self, query: str, filters: dict None): docs self.search(query, filters) if not docs: return {status: empty, message: 没有找到相关文档} summary self.generate_summary(docs) return { status: ok, summary: summary, sources: [d[url] for d in docs[:3]], data_fingerprint: hashlib.md5( json.dumps(docs, ensure_asciiFalse).encode() ).hexdigest() }关键的设计点在于返回值里加了data_fingerprint这个数据指纹是用来给主Agent做真实性校验的如果模型生成的最终回答里没有引用这个指纹对应的数据系统就知道它要么没调用工具要么就是在自由发挥。4.3 测试技能别只测“正常流”必须测“意外流”技能写完之后我建的测试规则是“两条正常路径、五条异常路径、两条对抗路径”。正常路径覆盖常规提问和模糊商品词追问异常路径覆盖搜不到结果、文档解析失败、摘要模型超时对抗路径覆盖用户故意用歧义句诱导错误触发、以及用户要求技能越权摘取未授权内容。对抗路径测试特别重要。举个例子用户说“帮我总结一下最近股市走势”如果技能库里只有“内部知识库总结”技能它的can_handle判定是高的但实际上它没有能力获取实时股市数据。这时候就考验技能在“边界与异常”里如何自证不适用——正确的做法是返回一个“超出本技能能力范围”的置信度低信号让路由层重新匹配其他技能而不是硬接任务然后编数据。5. Token成本、延迟和失败率技能库的三本经济账技能库跑通功能只是第一步。真正放到生产环境你会发现三个拦路虎费用、延迟、失败率。agent-skills 项目里我做了不少针对性的优化这些经验在很多Agent项目里都通用。5.1 Token成本核算一个被忽略的大头是“技能描述反复进入上下文”很多人算Agent调用成本时只算了主对话的input和output token忽略了每次请求都要把可用技能的描述拼进系统提示词里传输一遍。如果技能库有20个技能每个技能描述平均500个token那光技能描述一次请求就吃掉1万token。对于一个高频调用的Agent服务这可不是小数目。我的优化方案是多级路由第一级用一个轻量模型比如带分类能力的embedding模型对用户query做粗分类把候选技能从20个过滤到5个以内第二级再把这5个技能的详细描述拼进完整系统提示词第三级执行阶段用运行日志验证调用实际命中情况反馈给粗分类层持续调参这三级漏斗让单次请求的token开销从1万左右降到两千成本直接下降近八成而没有牺牲功能完整性。5.2 延迟优化串行调用改并行注意工具之间的依赖关系多个技能并行执行时延迟收益很大。但要注意技能之间的依赖关系决定了能否并行。比如“搜索相关文档”和“生成摘要”有明确的先后关系就只能串行而“搜索技术文档”和“查询API状态”互不依赖就可以丢进线程池并发执行。我在技能声明里加了一个dependencies字段专门标记与当前技能有依赖关系的其他技能。调度器在规划执行计划时会自动构建一个有向无环图DAG在这里我用手写拓扑排序实现没有引入重量级框架能并行的绝不串行必须串行的自动排好顺序。这个改造完成后一个典型的多技能复合任务的端到端延迟大约减少了40%。5.3 失败率治理失败不可怕可怕的是失败藏起来Agent技能调用的失败率和普通API的失败率不是一个量级。普通API失败会抛异常回去Agent却会尝试“智能地”绕过错误然后给出一个貌似正常的回答这是最危险的。我的对策是强制要求技能在遇到异常时返回结构化错误并且把错误信息原样暴露给上层不允许技能内部“吞掉”异常。对用户展示暂时无法完成XX原因检索服务超时请稍后再试 对监控系统展示skillkb_summary errortimeout_duration5s attempt3加了这个机制后故障定位时间从小时级降低到了分钟级。而且用户收到的反馈不再是AI编造的“系统一切正常”而是明确知道哪里出了问题。6. 两个生产环境的实战案例拆解技能组合的调用逻辑理论框架再完整也得在真实场景里压一压。这里分享两个投入生产使用最多的场景它们都依赖多个技能协作完成。6.1 案例一多技能协作的“工单分诊”机器人场景是处理客服工单用户提交一条描述系统自动打标、判定紧急程度、查询相似历史工单、给出建议分类和解决方案。最初实现时我把所有逻辑塞进一个巨大的“工单处理”技能里结果模型在步骤衔接处频繁出错比如先查询历史工单再打标把无关的历史记录带进了分类预测里。重构后拆成五个技能工单标签抽取用少量关键词和正则从描述中提取标签历史工单检索根据标签和描述向量检索相似工单紧急度判定根据描述中的时间表述和业务规则输出高/中/低三级解决方案推荐基于历史工单的处理结果做推荐工单摘要生成把所有信息汇总为一段不超过80字的摘要调度层根据工单类型动态组合这些技能。比如退款类工单直接走“历史工单检索解决方案推荐”投诉类工单则额外挂“紧急度判定”和“标签抽取”。技能化改造之后工单处理准确率从原来的78%提升到了92%。6.2 案例二一个技能的两次迭代从“能用”到“好用”第二个例子说迭代。最开始我的“周报生成”技能只是把固定模板套上去把数据填进去输出一份静态报告。第一次迭代我在技能描述里加了“洞察生成”步骤——在关键指标变化超过阈值时自动追加原因分析建议。第二次迭代我加了一个“可读性校验”步骤——生成内容超过设定字数时必须自动压缩表述并确保关键数字不丢失。每一次迭代的流程都一样先在测试技能库里调整描述和代码用历史周报数据做回归验证再小流量灰度到真实周报任务跑一周看反馈再全量放开。这个流程让我在迭代过程中从没有引入新的重大bug。7. 关于技能库的演进方向与我的最终建议折腾了整个 agent-skills 项目之后我对技能库这个设计模式有了更清晰的判断。它不会是终极形态但至少在未来两年内它会是Agent从玩具走向工具的最务实路径。7.1 自动生成技能让Agent自己写新技能边界在哪里一个自然的演进方向是“技能生成技能”——Agent在遇到无法处理的新任务时自己编写一个新的技能描述并注册进库。理论上这可行我甚至在实验环境里做过简化版本Agent根据用户的多次请求模式归纳出一个新技能的初始版本交给人工审核后入库。但我要泼一盆冷水现阶段自动生成的技能描述质量波动很大尤其是边界定义部分经常忽略异常场景。我的建议是自动生成的技能只能作为“候选草稿”必须经过人工评审和测试流程才能进入生产环境。完全放手让模型自迭代你迟早会被“技能库自己膨胀到失控”反噬。7.2 个人实践中的三条底层经验第一技能描述像文档一样需要持续维护。模型版本升级、工具API微调、业务规则变化都会让旧技能描述逐渐失真。我给每个技能设了“过期时间”超过一个月没有通过的测试自动触发告警。第二技能并非越多越好精而少才是王道。技能库里每个技能都占用上下文窗口、增加路由决策复杂度、提升测试覆盖成本。一个能覆盖80%需求的10个技能库远好于一个覆盖95%需求但管理混乱的50个技能库。第三永远不要相信模型在没有调用技能的情况下给出的“答案”。你再怎么调优技能描述和路由机制也架不住模型基于训练记忆的自信编造。这个原则我会继续坚持。7.3 如果你要从零开始做技能库我的最小落地清单第一个技能选一个高频、低风险、逻辑清晰的任务不要一上来就做复杂编排给每个技能单独建目录SKILL.md 按“身份目标、触发条件、执行步骤、参数规范、边界异常、质量要求”六段来写注册表里记录版本号、依赖关系和最后验证时间一旦依赖变化立刻标记待测返回结果里加数据指纹或其他可校验标识杜绝无根据输出测试不只测正常路径必须覆盖查无结果、接口超时、边界参数、对抗性歧义先把成本统计埋点做好再谈优化没有数据的优化都是盲人摸象我做完 agent-skills 这套体系后最大的感知是AI智能体的能力上限不取决于底层大模型有多强而取决于你给了它多少高质量、边界清晰、可验证的行动单元。把技能库当成一支高素质团队来经营——招人宁缺毋滥、岗位说明书要清晰、日常有绩效评估、变化有版本管理这支团队才能真正帮你把事办成。