1. 从“技能”这个词说起为什么我们需要重新理解Agent的能力边界“agent-skills”这个标题看起来简单但它背后指向的是一个正在快速演化的技术方向——如何让智能体Agent具备可复用、可组合、可扩展的技能体系。如果你最近在关注AI应用开发大概率已经注意到一个趋势大家不再满足于让模型“回答问题”而是希望它能“做事”。而“做事”的核心就是技能。我最初接触这个概念时也走过弯路。当时我以为所谓的Agent技能无非就是给模型挂几个API、写几段提示词让它能查天气、能算数学题。但真正动手做项目之后才发现事情远没有这么简单。一个真正可用的Agent技能体系需要解决三个层面的问题技能如何定义、技能如何调度、技能如何组合。这三个问题不解决你的Agent就永远停留在“玩具”阶段。这篇文章适合谁看如果你是正在做AI应用开发的工程师或者是对Agent架构感兴趣的产品经理又或者是想把自己的业务能力封装成Agent技能的技术负责人那接下来的内容应该能帮你少走不少弯路。我会从技能的定义方式讲起一直聊到多技能协同的实战细节中间会穿插我自己踩过的坑和总结出来的经验。先给一个最直观的理解Agent技能就像给一个刚入职的实习生配了一套工具箱。工具箱里有什么、怎么用、什么时候用哪个这些都需要你提前设计好。而“agent-skills”这个项目标题本质上就是在探讨这套工具箱的设计方法论。2. 技能的定义方式从硬编码到声明式描述2.1 为什么硬编码技能是条死路我最早做Agent技能的时候采用的是最直接的方式——在代码里写死。比如用户问天气我就写一个get_weather函数然后在提示词里告诉模型“你可以调用get_weather”。这种方式在技能数量少于5个的时候还能凑合一旦超过10个问题就来了。首先是提示词会变得极其臃肿。每个技能都需要描述、需要参数说明、需要调用示例这些内容全部塞进系统提示词里很快就会撑爆上下文窗口。其次是维护成本极高每加一个技能就要改一次提示词改完还要重新测试所有已有技能是否还能正常工作。最要命的是模型在技能数量多了之后选择准确率会明显下降——它经常在该用A技能的时候选了B技能。后来我意识到硬编码的本质问题是把“技能的定义”和“技能的调度”混在了一起。技能的定义应该是独立的、自包含的而调度应该是动态的、按需加载的。这个认知转变是我做Agent技能体系的一个关键转折点。2.2 声明式技能描述的结构设计转向声明式之后每个技能都变成一个独立的结构化描述。我目前用的格式大致是这样的{ name: search_knowledge_base, description: 在内部知识库中搜索相关文档适用于需要查询产品文档、技术规范、历史工单的场景, parameters: { query: { type: string, description: 搜索关键词建议使用具体的名词短语而非完整句子, required: true }, max_results: { type: integer, description: 返回结果数量上限默认5最大20, required: false, default: 5 } }, returns: { type: array, description: 匹配的文档列表每项包含标题、摘要、相关度评分 } }这个结构看起来简单但每个字段都有讲究。description不能只写“搜索知识库”而要写清楚“什么时候该用这个技能”。这一点非常关键——模型选择技能的依据很大程度上就是看这个描述是否匹配当前任务场景。我试过把描述写得很简短结果模型经常在不需要搜索的时候也去调搜索技能浪费了大量token。parameters里的description同样重要。特别是query参数我明确写了“建议使用具体的名词短语而非完整句子”这是因为实测发现模型如果直接把用户的原话塞进去搜索效果往往不好。加上这句提示之后模型会主动做一次查询改写把“我想知道那个关于数据同步的问题怎么解决”改成“数据同步 问题 解决方案”召回率明显提升。2.3 技能描述的粒度控制另一个容易踩坑的地方是技能粒度。我一开始把技能拆得很细比如“读取文件”“写入文件”“列出目录”各算一个技能。结果模型在执行一个简单任务时需要连续调用五六个技能中间任何一步出错都会导致整个任务失败。后来我调整了策略按“用户意图”而不是“底层操作”来划分技能。比如把文件操作合并成一个manage_files技能通过action参数来区分具体操作。这样模型只需要调用一次内部逻辑由技能自己处理。当然粒度也不能太粗否则参数会变得极其复杂模型很难正确填充。我的经验法则是如果一个技能需要超过5个参数或者描述超过200字就说明粒度太粗了应该考虑拆分。反过来如果两个技能在80%的场景下都是一起被调用的那它们就应该合并。3. 技能调度的核心机制让模型学会“什么时候用什么”3.1 基于语义匹配的技能召回技能定义好了之后下一个问题就是当用户提出一个请求时如何从几十甚至上百个技能中快速找到最相关的几个最朴素的做法是把所有技能描述都塞进提示词让模型自己选。但前面说过技能多了之后这样做效果很差。我目前采用的方案是两阶段召回。第一阶段用向量相似度做粗筛把用户请求和所有技能的描述分别向量化取相似度最高的前10个技能。第二阶段再把这10个技能的完整描述放进提示词让模型做最终选择。这样既控制了提示词长度又保证了选择准确率。这里有个细节值得注意向量化的时候不要只用技能名称而要用“技能名称描述典型使用场景”拼接后的文本。我试过只用名称召回效果很差加上描述之后召回率提升了将近40%。另外如果技能数量超过200个可以考虑先用关键词做一次硬过滤再做向量召回速度会快很多。3.2 多技能协同的编排逻辑单个技能调用相对简单真正复杂的是多个技能协同完成一个任务。比如用户说“帮我查一下上个月的销售数据然后生成一份报告发给团队”这至少涉及三个技能查数据、生成报告、发送邮件。我一开始的做法是让模型自己决定调用顺序结果经常出现顺序错乱——比如还没查到数据就开始生成报告。后来我引入了一个简单的编排层把常见任务模式抽象成“技能链”。每个技能链定义了技能的调用顺序和数据传递方式。模型只需要识别出当前任务属于哪个技能链然后按预定义的流程执行。当然技能链不能覆盖所有情况。对于技能链覆盖不到的任务我还是让模型自由编排但加了一个约束每个技能的输出必须经过一个校验步骤确认数据格式正确后才能传给下一个技能。这个校验步骤看起来多余但实际上避免了很多“垃圾进垃圾出”的问题。3.3 技能执行失败的降级策略技能调用失败是常态不是异常。网络超时、参数错误、权限不足、返回结果为空这些情况我都遇到过。如果每次失败都直接报错给用户体验会非常差。我的做法是为每个技能定义一个降级策略。比如搜索技能失败时降级为“告知用户搜索暂时不可用建议稍后重试”数据查询技能失败时降级为“返回缓存中的最近一次数据并标注数据可能不是最新”。降级策略写在技能定义里由调度层统一处理。还有一个技巧对于关键技能我会配置重试机制。但不是简单重试而是带参数调整的重试。比如第一次搜索用原始查询词如果返回结果为空第二次自动放宽搜索条件第三次尝试同义词替换。这样能把很多“假失败”救回来。4. 技能组合的实战场景从单点能力到完整工作流4.1 信息检索类技能的串联模式信息检索是最常见的Agent应用场景也是最能体现技能组合价值的场景。一个完整的检索流程通常包含查询理解、多源检索、结果融合、摘要生成四个环节。查询理解环节我会用一个专门的技能来做意图识别和查询改写。这个技能接收用户原始问题输出结构化的查询意图和改写后的查询词。多源检索环节根据查询意图并行调用多个检索技能——比如同时查内部知识库、查工单系统、查产品文档。结果融合环节把多个来源的结果去重、排序、合并。摘要生成环节基于融合后的结果生成自然语言回答。这套流程听起来顺理成章但实操中有个关键点并行检索的结果返回时间不一致。有的源快有的源慢。如果等所有源都返回再融合整体延迟会很高。我的做法是设置一个超时窗口比如2秒超过2秒还没返回的源就先用已有结果后续如果返回了再补充。这样在延迟和完整性之间取一个平衡。4.2 数据处理类技能的错误传播控制数据处理类任务对错误特别敏感。一个环节算错了后面全错。我在做数据清洗和转换的Agent时踩过一个典型的坑某个技能返回了空值但下游技能没有做空值检查直接把空值当0处理最后生成了完全错误的报表。从那以后我在技能定义里强制要求每个技能声明它的输出约束。比如“返回字段X必须为非空字符串”“返回数组长度必须在1到100之间”。调度层在把数据传给下一个技能之前会先校验这些约束。不满足约束就触发降级或报错而不是让错误数据继续往下流。另外对于数据处理链路我会在关键节点保存中间结果。这样如果最后一步出错不需要从头重跑可以从最近的检查点恢复。这个做法在调试阶段特别有用能快速定位到底是哪个环节出了问题。4.3 人机协作类技能的交互设计有些技能不是全自动的需要人工介入。比如“发送邮件”这个技能在正式发送前应该让用户确认收件人和内容。这类技能的设计要点是在自动流程中插入确认节点但确认节点不能太频繁否则用户会觉得烦。我的做法是把确认节点放在“不可逆操作”之前。查询、计算、生成草稿这些可逆操作不需要确认直接执行。发送、删除、修改这些不可逆操作才需要确认。而且确认信息要足够具体不能只问“是否继续”而要展示“即将发送给张三、李四主题是XXX内容摘要如下”。还有一个细节确认超时怎么处理。如果用户一直不确认任务不能永远挂在那里。我会设置一个合理的超时时间比如5分钟超时后自动取消任务并通知用户。如果用户后续想继续可以从任务列表里重新发起。5. 技能体系的维护与演进上线只是开始5.1 技能使用数据的采集与分析技能上线之后如果不采集使用数据你根本不知道哪些技能在被用、哪些技能有问题。我一开始只记录了调用次数后来发现这远远不够。现在我会记录每个调用的完整链路用户原始请求、召回的候选技能、最终选择的技能、传入参数、返回结果、执行耗时、是否成功。这些数据能回答很多关键问题。比如某个技能调用成功率突然下降可能是上游数据源出了问题。某个技能经常被召回但很少被选中说明它的描述可能不够准确。某个技能的平均执行时间越来越长可能需要优化内部实现。分析的时候我特别关注两个指标技能选择准确率和端到端任务完成率。前者衡量模型是否选对了技能后者衡量整个任务是否成功完成。这两个指标结合起来看能快速定位问题是出在调度层还是执行层。5.2 技能版本的灰度发布策略技能更新不能一次性全量发布风险太大。我采用的是灰度发布策略新版本技能先只对10%的流量生效观察一段时间没问题再逐步扩大比例。灰度发布的关键是做好版本隔离。每个技能调用请求都要带上版本标识确保同一个任务链路里的所有技能调用都使用同一版本。否则如果A技能用了新版本、B技能用了旧版本可能会出现兼容性问题。回滚机制也要提前准备好。一旦发现新版本有问题要能在一分钟内切回旧版本。我一般会保留最近三个版本的技能定义确保随时可以回滚。5.3 技能废弃与迁移的处理技能也会“死亡”。有些技能随着业务变化不再需要了有些技能被更好的实现替代了。废弃技能不能直接删掉因为可能还有历史任务在引用它。我的做法是先把技能标记为“已废弃”在描述里注明替代技能是什么。调度层看到已废弃的技能时会自动重定向到替代技能。这样运行一段时间后确认没有任务再引用旧技能了才真正删除。迁移的时候要注意参数兼容性。如果新旧技能的参数结构不同需要在重定向层做参数转换。这个转换逻辑最好写在配置里而不是代码里方便随时调整。6. 我踩过的那些坑技能体系构建中的真实教训6.1 技能描述过于抽象导致的调度混乱早期我写技能描述的时候喜欢用比较抽象的语言。比如“处理用户请求”“管理数据”这种。结果模型完全不知道该什么时候用这些技能经常在不该调用的时候调用。后来我强制自己遵守一个规则技能描述里必须包含至少一个具体的名词和一个具体的动词。比如“在内部知识库中搜索相关文档”就比“处理搜索请求”好得多。另外描述里要明确写出“不适用场景”。比如搜索技能要注明“不适用于实时数据查询”这样能避免模型在需要实时数据时错误地选择搜索技能。6.2 参数校验缺失引发的连锁故障前面提到过空值问题这里再展开说一下。参数校验缺失导致的故障往往不是单个技能的问题而是整个链路的雪崩。我遇到过一次某个技能返回了格式错误的日期字符串下游技能解析失败再下游技能因为拿不到日期就用了默认值最后生成了一份日期完全错误的报表。修复方案是在每个技能的入口和出口都加校验。入口校验参数是否符合定义出口校验返回值是否符合声明。校验不通过就立即中断当前链路返回明确的错误信息。虽然这样会增加一些开发工作量但比起线上出故障的代价这点投入完全值得。6.3 技能粒度过细带来的性能问题前面提过粒度控制这里补充一个性能角度的考量。技能调用是有开销的——每次调用都需要一次模型推理用于选择技能和填充参数再加上技能本身的执行时间。如果粒度太细一个任务需要调用十几次技能总耗时可能达到几十秒用户体验很差。我的优化经验是对于高频出现的技能组合考虑合并成一个复合技能。比如“搜索摘要”经常一起出现就合并成一个search_and_summarize技能。这样模型只需要调用一次内部串行执行两个步骤省去了一次模型推理的开销。6.4 忽视技能执行环境的差异性最后一个坑比较隐蔽技能执行环境的差异性。我在开发环境测试技能时一切正常上线后却频繁失败。排查后发现是生产环境的网络策略更严格某些外部API调用被限制了。从那以后我在技能定义里增加了一个environment_requirements字段声明技能运行所需的环境条件。比如“需要访问外部网络”“需要读取本地文件系统”“需要特定权限”。部署的时候会根据这些声明做环境检查不满足条件的技能会被标记为不可用而不是等到调用时才报错。7. 写给正在构建Agent技能体系的你如果你正在着手构建自己的Agent技能体系我的建议是从小处着手但把架构想清楚。先实现三五个核心技能把定义、调度、执行的完整链路跑通。这个过程中你会遇到各种预料之外的问题但正是这些问题能帮你把架构打磨得更健壮。技能描述的质量直接决定了整个体系的上限。花时间打磨每个技能的描述确保它清晰、具体、无歧义。这件事的投入产出比极高值得反复迭代。不要追求一步到位。技能体系是演化出来的不是设计出来的。先上线采集数据根据实际使用情况持续调整。我现在的技能体系和最初版本相比几乎每个技能都经过了至少三轮重构。最后分享一个我最近在用的技巧定期做“技能审计”。把所有技能列出来逐个问三个问题——这个技能最近30天被调用了多少次调用成功率是多少如果删掉它哪些任务会受影响回答完这三个问题你就知道哪些技能该优化、哪些该合并、哪些该废弃了。这个习惯帮我保持了技能体系的精简和高效。