做 Agent 开发的人十有八九都遇到过这样一个场景功能写了一堆但每次换个项目、换套提示词、换条业务线就得重新缝缝补补。我这两年一直在做 Agent 相关的落地应用最深的感受是——真正拖垮团队的往往不是模型能力而是技能的组织方式。Agent Skills 这个词最近频繁出现在各种技术讨论里说白了就是把你让 Agent 做某类事情的能力沉淀成一套可复用、可组合、可调度的“技能包”。这篇文章不聊虚的我会把自己从零搭建一套 Agent 技能体系的思路、协议设计、实操步骤和踩坑记录完整梳理一遍适合正在做智能体应用、想把工具调用和提示词工程系统化的开发者参考。先说清楚这套东西能解决什么问题。当你只有三五个工具函数时硬编码就够了但当 Agent 要面对几十个工具、多种上下文、多步操作时你就需要一个机制让大模型知道“什么场景该用什么技能”让技能本身能独立迭代、测试和复用。我下面写的内容就是从“工具堆砌”走向“技能工程”的完整路线图覆盖了技能描述协议、注册发现机制、组合编排、上下文管理和失败排查内容偏实战也补了一些原理层面的解释新手可以先看前面两章老手可以直接跳到第 3 章以后的实操部分。1. 为什么需要 Agent Skills从工具堆砌到技能工程1.1 核心痛点你的 Agent 真的“会”做事吗先讲个我实际遇到的案例。之前团队里有一个客服助手项目最初只接了订单查询、物流查询、退款申请三个功能代码写得很直接大模型输出一个函数名和参数后端把结果塞回去。效果还不错。但后来要加会员积分查询、优惠券核销、发票申请……功能越来越多提示词里塞满了各种工具说明结果模型开始“乱点技能”——用户问积分它去调了订单接口用户要开发票它反复调用优惠券接口。排查了很久才发现问题不在于接口本身而在于我们根本没有定义清楚“什么场景下该用什么技能”。这就是 Agent Skills 要解决的核心问题技能不仅仅是“一个函数”而是“某个能力的完整封装”包括触发条件、适用场景、参数约束、输出格式、异常处理策略。就像人做事一样“知道怎么做”只是基础更重要的是“知道自己什么时候该这么做”。从开发效率角度也一样难受。我们当时把提示词、工具定义、后处理逻辑分别放在不同地方每调整一次功能就要动三四处代码测试也几乎靠手工。没有一套统一技能协议复用就成了空话——你在这个项目里写得再好的摘要能力换到另一个项目完全带不走。1.2 Agent Skills、Function Calling、Plugin 和 Workflow 到底什么关系很多人刚开始接触 Agent Skills 时会和 Function Calling、Plugin、Workflow 混在一起。我用自己的理解做个区分Function Calling 是模型层的机制解决的是“模型如何输出结构化调用意图”属于底层能力。Plugin 是应用层的集成方式解决的是“Agent 如何接入第三方服务”强调的是入口和权限。Workflow 是流程层的编排方式解决的是“多步骤之间如何串行或并行流转”强调的是过程控制。Agent Skills 则是能力层的抽象它可以在以上任何一层之上构建。一个技能内部可能就是一个 Function Calling 调用也可能是一段完整的多步 Workflow甚至是由多个子技能组合而成。用生活化类比来说Function Calling 是“手”Plugin 是“门把手”Workflow 是“路线图”而 Agent Skills 是“肌肉记忆”。肌肉记忆不是单一动作而是一整套协调反应——什么时候发力、动作做到什么幅度、遇到阻力怎么调整这些都被固化在一个技能里。这也是为什么我会建议把技能层单独抽出来。有了这一层Agent 的主逻辑可以保持精简它只需要理解“我现在需要达成什么目标我手里有哪些技能可用”而不必关心每个技能底下的复杂实现。后续不管是换模型、换接口、还是加新功能影响范围都被限制在技能内部主流程几乎不用动。1.3 技能复用带来的三个直接好处把技能抽出来之后最直观的变化有三个。第一测试成本大幅下降。技能边界清晰之后我可以对每个技能单独做效果评估不必每次都在完整对话链路里验证。某个技能升级了只需要跑它的测试集看看通过率和回归情况就能判断能不能上线。第二Agent 的行为可预期性提高了。以前大模型在几十个工具之间“自由选择”经常出现令人意外的组合。有了技能描述和触发条件之后模型的选择空间被约束在一个合理的范围里虽然不是百分之百稳定但至少大部分错误可以从“乱调工具”降到“技能内部的参数偏差”排查难度完全不是一个量级。第三知识积累真正发生了。技能里沉淀的不只是代码还有调试过程里总结出来的提示词约定、边界条件、失败应对策略。团队里新同学接手时不需要再去翻几十条历史聊天记录找经验直接看技能的 README 和测试用例就能上手。2. 技能库的整体设计结构、命名与协议2.1 技能描述文件让模型“看懂”技能做 Agent Skills 最容易忽略的一件事是技能不是写给人看的更是写给大模型看的。所以技能描述文件是整套体系里最关键的部件。一个合格的描述文件至少包含四类信息技能标识名字、版本、所属领域用于定位和依赖管理。功能描述这个技能能做什么解决什么问题必须用自然语言写清楚且要写成模型容易理解的方式。注意这里不是写给开发者的技术注释而是写给模型的任务说明书。多写“当用户想要做 X 时使用本技能”、“本技能适用于……不适用于……”这类明确边界的话。输入输出协议需要哪些参数、每个参数的类型和约束、输出是什么结构。这里建议用 JSON Schema 定义大模型对结构化的参数理解比自由文本好得多。使用约束什么情况下不能使用、需要什么样的前置条件、失败时怎么处理。以一个“网页内容提炼”技能为例它的描述文件核心部分大概是这样的{ name: web_page_summarizer, version: 1.2.0, description: 当用户需要快速了解一个网页的核心内容、要点提炼、观点归纳时使用。输入为URL或网页正文。如果用户只是提出摘要需求但没有提供链接应先询问具体目标地址。本技能不适用于对结构化表格数据的深度分析。, input_schema: { type: object, properties: { url: {type: string, format: uri}, max_length: {type: integer, default: 500} }, required: [url] }, output_schema: { type: object, properties: { summary: {type: string}, keywords: {type: array, items: {type: string}}, source_type: {type: string, enum: [article, product_page, forum, other]} } } }很多刚接触这个概念的开发者会把描述写得太笼统比如“提供网页摘要功能”。模型确实能理解“摘要”这个词但它不知道什么时候该优先选这个技能、输入不完整时应该怎么做、输出格式是什么样的。描述文件的质量基本决定了技能选对率值得反复打磨。2.2 技能实现层提示词策略与工具编排描述文件只是门面真正决定技能效果的是内部的实现层。我把实现层拆成两个部分提示词策略和工具编排。提示词策略指的是技能内部如何构建模型对话上下文。最常见的方式有两种。一种是固定式提示词适用于逻辑稳定、步骤明确的技能另一种是模板式提示词适用于需要结合运行时动态信息的技能。比如“代码评审”技能它需要根据代码语言、代码规模动态调整提示词的重点要求。“这是一段 Python 代码长度约 200 行请重点检查资源释放和异常处理”——这类信息的绑定就需要模板。工具编排方面技能内部会调用多少个工具、顺序如何、中间结果如何缓存这些都需要在设计时确定。我建议技能内部尽量保持“薄实现”风格也就是技能只做一件事把事做到位不要贪多。一个技能内部塞五六个工具调用会让调试变得非常痛苦。如果确实需要多步操作可以拆成多个小技能再通过组合机制串起来。2.3 技能注册与发现机制技能库有了几个技能之后就要考虑注册和发现。这套机制解决的是“模型如何知道有哪些技能可选”的问题。我目前采用的方式是建立“技能索引”每次请求时把全部技能的名称、简述、适用条件汇总成一段索引文档注入系统提示词模型判断需要哪个技能时再去加载对应技能的完整描述。这样做的好处是控制上下文长度——几十个技能每个都带完整描述的话光技能说明就能把上下文塞爆而且会分散模型注意力。注册机制上每个技能目录下有一个 manifest 文件里面除了描述协议需要的信息外还可以记录依赖关系、运行权限要求、版本兼容性。这个 manifest 会被一个脚本扫描自动生成技能索引不需要手动维护。索引里我会特别注意为每个技能给出“相关技能”字段比如“网页内容提炼”和“网页内容翻译”相关模型在拿不准时可以参考相近技能的边界描述降低选错概率。3. 从 0 到 1 搭建一套 Agent 技能库的实操流程3.1 第一步需求盘点不要凭想象定义技能动手写代码之前先花一到两天做需求盘点。我会把计划中要支持的场景全部列出来然后逐个回答三个问题用户在什么情境下会触发这个能力完成这个能力需要哪些外部依赖工具、数据源、模型能力失败之后用户能接受什么样的降级方案举个例子我们内部做过一个“会议纪要整理”技能最初觉得很简单——把录音转文字、整理成要点。但盘点后发现用户在意的不是文字转写准确率而是“会议上的行动项有没有被准确提取出来”。于是这个技能的设计重点就从“转写”转移到了“行动项识别与负责人关联”工具选择也随之调整。需求盘点还有一个作用就是帮助你判断什么场景不需要做成技能。如果一个任务用固定流程就能实现且中间没有任何模型判断空间那直接写传统代码可能更稳定更省钱。Agent 技能的价值在“需要理解、归类和决策”的任务上机械性的步骤别硬塞给模型。3.2 第二步设计目录结构与技能模板技能库的目录结构建议一开始就规范化不然后期技能多了会非常混乱。我现在用的结构是这样的skills/ common/ text_sanitizer/ manifest.json README.md run.py tests/ content_summarizer/ manifest.json README.md run.py tests/ analysis/ data_inspector/ manifest.json README.md run.py tests/每个技能目录里至少包含四部分manifest.json技能描述、输入输出协议、依赖声明。README.md给人类开发者看的说明包括设计背景、已知局限、运维注意事项。run.py技能的实际执行逻辑入口统一。tests/离线测试用例和预期输出。模板的好处是让团队对“一个技能应该长什么样”有统一预期。新技能从模板复制一份再改写格式正确率远高于从零手写。这个细节看起来简单实际节省了大量沟通成本。3.3 第三步实现一个完整技能实战示例现在用一个完整例子展示技能实现过程。以“日志异常检测”技能为例这是运维场景里非常常见的能力。先是 manifest.json 的核心字段{ name: log_anomaly_detector, version: 0.3.0, description: 当用户提供系统日志文本或日志文件路径需要找出异常条目、错误原因、影响范围时使用。适用于应用日志、访问日志、系统日志。不适用于二进制日志直接解析。如果日志量超过1万行应先做采样或分段。, input_schema: { type: object, properties: { log_path: {type: string}, log_text: {type: string}, time_range: {type: string, description: 如 2025-01-01T00:00:00Z 到 2025-01-01T23:59:59Z} }, one_of: [log_path, log_text] } }然后是实现逻辑 run.py核心思路是三步走def run(context): log_entries fetch_logs(context.input) analysis_prompt build_analysis_prompt(log_entries) result call_llm(analysis_prompt) return format_result(result)第一步获取日志这一步通常要处理文件编码、日志格式不统一的问题。第二步构建分析提示词提示词里除了日志内容外还要加上“你是一个 SRE 工程师”这类角色设定以及“请按时间线梳理异常事件并区分错误根因与次生错误”这类分析要求。第三步把模型输出格式化为统一结构方便上层 Agent 后续处理。这里有个我踩过不少次的坑不要在提示词里把原始日志全部塞进去就完事。日志里充斥着大量无意义的信息模型注意力会被带偏。我在实践中发现先做一轮规则过滤去掉DEBUG级别、去掉已知健康检查日志、提取统一时间戳格式再交给模型分析准确率能提升不少。这就是前面说的“技能内部可以实现规则与模型混合逻辑”不是所有步骤都非得用大模型。3.4 第四步技能测试和效果评估方法技能开发完成后必须配套测试。我总结下来的测试层级分四层单元测试验证 run.py 里的纯函数逻辑是否正确比如时间格式转换、日志过滤规则、输出格式化。场景测试给定一组输入对话验证模型是否能正确触发该技能以及参数传递是否准确。场景测试里一定要包含负面样例比如用户问了个与技能无关的问题模型应该触发别的技能或礼貌拒绝。输出质量评估这是最难的。我的做法是建立一个评测集每条数据标注了“完美输出”“可接受输出”“不可接受输出”三档标准然后定期跑一遍统计分布变化。评测集不用一开始就很大50 条精挑细选的用例比 500 条粗制滥造的有用得多。回归测试每次技能升级后除了跑自己的测试集还要跑相关技能的测试集防止改动影响全局。测试这块我特别想强调一点不要只测“正常情况”。Agent 应用里模型误判、参数缺失、外部接口超时才是常态。我在每个技能的测试集里都放了两成以上的“边界用例”——没有输入、输入格式怪异、输入内容超出技能适用范围。这部分的通过率往往最能反映技能的鲁棒性。3.5 第五步发布、版本管理与下线策略技能开发完并不算结束发布流程同样重要。我把技能发布分成三个渠道沙箱环境本地或测试环境可以随意调试。预发环境和线上共用技能库但不影响正式流量。生产环境真正被 Agent 调度使用的版本。版本管理方面我采用语义化版本号。主版本号变化代表技能协议不兼容比如输入输出结构改了次版本号代表兼容性升级比如新增了可选的参数补丁号代表内部修复对调用方无感知。每次发布都要记录 changelog写清楚本次改动对模型行为可能带来的影响。还有一个容易被忽略的问题技能下线。技能长时间没人用、或者被新技能取代后如果不做处理技能索引会越来越臃肿反而干扰模型判断。我现在每个季度会跑一次技能使用统计把连续三个月调用量为零的技能标记为“不活跃”再过一个月确认没有依赖后就移出默认索引但保留在库里供历史兼容。清楚地说这个机制帮我避免了很多“不知道什么时候改了什么导致整体效果变差”的糊涂账。4. 组合、路由与上下文管理4.1 Agent 如何决定调用哪个技能路由策略设计技能库建好之后下一步关键问题是Agent 怎么从一堆技能里选出正确的那个。目前我尝试过的路由策略有三种各有优劣。第一种是纯模型路由。把所有技能索引注入系统提示词让模型自行选择。优点是灵活适合技能之间差异性大、场景开放的情况缺点是上下文开销大且模型在面对相似技能时容易混淆。第二种是规则优先路由。先根据用户输入做关键词和意图分类命中规则就直接指定技能没命中再交给模型判断。这种方式在意图特别明确的任务上效果极好比如用户输入里包含“查订单”就优先走订单技能时效性高、不会错。第三种是混合路由。规则判断 模型兜底。我最终采用的就是这种方式先跑一轮轻量级意图分类器把明显不过来捋一遍如果意图置信度足够高就直接路由否则进入模型路由让模型结合技能索引做决定。选路由策略还有个不太起眼但很重要的细节要给模型留出“不选技能”的出口。很多 Agent 设计里强制模型必须选一个技能结果用户在闲聊时模型也硬套技能答非所问。正确做法是允许模型判定“当前不需要调用技能”直接基于自身知识回答。这个设定让整体行为自然很多。4.2 多技能组合编排把简单技能变成复杂能力单技能能力有限组合才是 Agent 真正的威力所在。组合方式我总结了三种基础模式顺序执行上一个技能的输出作为下一个技能的输入类似流水线。比如“网页内容提炼”之后接“要点翻译”完成双语摘要。条件分支根据前提技能的结果决定下一步走哪一个分支。比如先判断文档类型再决定走“合同解析”还是“论文解析”。并行执行多个互不依赖的技能同时执行最后汇总结果。比如需求信息收集后同时跑“舆情分析”“竞品对比”“成本估算”三个技能最后整合成完整报告。组合设计时最关键的是要明确定义技能间的“接口契约”。每个技能的输出不应该是一个自由格式的文本而是带有结构字段的对象。这样下一个技能才能可靠地取用上游结果。比如“网页内容提炼”技能输出里有 source_type 字段后续“要点翻译”技能就可以根据 source_type 决定翻译风格。如果上游输出是一段杂乱文本下游技能就需要二次解析既浪费 token 又不稳定。4.3 上下文窗口与记忆管理的实用方法技能组合会带来上下文膨胀问题。一个技能内部可能就消耗几千 token多个技能串起来之后很容易触及上下文上限。我常用的缓解手段有三个。第一中间结果剪裁。技能组合之间只传递必要字段而不是把完整输出全部塞给下游。比如“数据分析”技能的完整输出可能包含图表分析和数值明细但下游“报告生成”技能只需要结论摘要和关键指标中间做好裁剪再传。第二技能内部使用局部记忆。如果技能运行过程中需要多轮调用同一个模型接口可以采用“两轮之间只传递已提炼的摘要”而不是完整历史。这有点像人读文件时不会反复从头读而是拿着印象再回查关键段落。第三对长文档采用分块策略。单个技能处理内容超过上下文容量时不硬塞而是切片处理后再汇总。但要注意切片策略本身可能影响技能效果比如语义关联较远的段落被切断了线索。所以分块时必须保留足够的交叉信息比如段落标题序号、相邻段落的一两句话摘要。还有一条实践经验把“技能运行过程中的中间状态”和“技能运行结束后的输出”放在不同的上下文区域。前者用完即弃后者才作为长期记忆保留。这样既降低 token 消耗也减少无关历史对模型后续判断的干扰。4.4 技能之间的依赖关系与冲突处理技能多了以后依赖关系会变成一张网。A 技能依赖 B 技能B 技能又依赖 C 技能一旦升级了 C 技能A 的行为可能悄然变化这种“隐性耦合”最容易在线上引发问题。我的解法是两层一层是依赖声明。技能 manifest 里明确写出依赖的其他技能及版本范围。这里要警惕循环依赖比如 A 依赖 B、B 又依赖 A模型调度时死循环。代码层面已经做了循环检测但设计阶段能避免就避免。另一层是行为冲突处理。当两个技能可能对同一场景给出不同结论时需要明确优先级。我在技能描述里会增加一个字段“当可能与 X 技能产生冲突时以本技能为准/需要外部确认”。举个例子“代码生成”和“代码安全审查”两个技能如果生成结果被安全审查发现问题默认安全结论优先Agent 应该中止交付并告知用户风险而不是继续执行。这套依赖管理做起来确实繁琐但它决定了技能库能不能越滚越大而不失控。我见过不少团队前期不做依赖管理技能库冲到一百多个之后几乎没人敢动老技能因为不知道牵一发动全身会坏什么。5. 实测中的高频问题与排查实录5.1 模型选错技能是描述问题还是路由问题这是出现频率最高的问题。表现形式是用户问“帮我总结一下这个网页”模型却调了“网页翻译”技能或者什么技能都没调直接把原文复述了一遍。排查思路分三步。第一确认技能描述是否足够精准。很多“选错”其实是描述里的歧义导致的。比如摘要技能和翻译技能都提到“处理网页内容”模型就很容易混淆。解决办法是在描述里加入排除性说明“本技能只做内容提炼不做语言转换”。第二检查路由层的意图分类结果。如果规则优先路由阶段就把意图分偏了模型层面再努力也没用。我会把用户输入和意图分类结果打日志看是规则配置的问题还是模型理解的问题。第三再看技能索引的排序。模型对排在靠前、描述更具体的技能有选择倾向。如果发现某个技能总是被错误选中可能是它的名字或描述在索引里过于突出适当调整措辞或顺序往往就解决了。5.2 技能输出不稳定同一个输入效果时好时坏这个问题通常出在提示词或参数设置上但也有几个隐蔽原因。一个是模型超参数扰动。温度设置过高输出风格和内容就会飘。经过对比测试技能内部调用默认温度建议设置为 0 或接近 0除非技能本身需要创意生成。你可能会觉得输出“差不多”但在长链路 Agent 里“差不多”的输出会导致下游技能解析失败连锁反应很大。另一个原因是输入顺序。模型对文本顺序敏感同一批日志排列顺序不同分析结果会有差异。解决办法是在技能内部预先对输入做固定排序比如按时间戳升序消除顺序带来的随机性。还有一种情况是提示词里“负面指令”过多。比如“不要输出无关内容”这句模型可能反而更加关注“无关内容”这个词。更有效的做法是正面给出输出范式比如“输出格式为结论、证据列表、建议”让模型有清晰的模仿对象。5.3 重复调用和循环调用Agent 卡死的老大难组合技能之后循环调用是个很难排查的问题。表现形式是 Agent 在几个技能之间来回切换反复执行同一类动作迟迟不产出最终结果。这种问题的根因通常是“技能输出和技能入口条件高度相似”。比如“内容提炼”技能的输出里包含文本而它入口条件又是“用户需要处理文本”于是模型认为还需要再提炼一次。排查时要把 Agent 的每一步调用日志完整记录下来看它的循环路径。我见过一个案例Agent 在“数据读取”和“数据清理”两个技能之间循环了 7 次最后查日志才发现读取技能的输出格式和清理技能的输入格式是重叠的。解决思路有两个方向一是在技能描述里增加“输出终止条件”字段明确告诉模型“当输出已经是结构化结果时不再调用本技能”二是在 Agent 调度层做循环计数器同一技能在一个任务中被调用超过 N 次就强制终止并上报人工处理。后者是兜底方案虽然不太优雅但能避免浪费大量 token。5.4 成本和延迟失控技能不是越多越好Agent 技能库变得庞大之后成本和延迟问题会逐渐浮现。每个技能内部都有多次模型调用组合链路一长单次用户请求可能要几秒钟甚至更久费用也会线性上涨。我做过的有效优化有四个技能内部优先用规则和小模型做前置过滤减少送进大模型的数据量。对输出稳定的技能开启缓存。同样的输入在短时间内重复请求时直接返回之前的缓存结果能省不少钱。但缓存要注意失效策略避免给用户返回过期信息。对技能进行分级。高成本技能比如涉及多轮推理或长文档处理的在调用前增加一步确认机制向用户说明“这个操作可能比较慢/消耗较大是否继续”。组合链路里做结果复用。前面技能已经算出来的中间指标不再重复调用其他技能重新计算而是直接引用上游输出字段。延迟方面我还有一个体验优化技巧技能运行时间较长时先推送一个“处理中”的中间响应给用户避免用户以为 Agent 失联。这个虽然不改变实际耗时但显著降低了用户焦虑感体验分提升很明显。5.5 技能库扩容时如何保持稳定技能库从 10 个扩到 100 个的过程中一定会出现“技能间边界模糊”“索引过大”“模型决策准确率下降”等问题。我的经验是把“扩容”做成一个定期流程而不是想起来就加一个技能。每次扩容走四步需求确认验证新技能和现有技能没有重复协议评审检查新技能的输入输出设计和描述质量测试集更新把新技能的场景和边界用例并入全局回归索引调整更新系统提示词中的技能列表必要时精简描述篇幅。还有一条比较重要的经验技能库需要“负增长”。定期删除和合并技能和技术能力本身一样重要。一个新技能上线后如果没带来明显效果提升反而占了上下文空间那就应该果断下线。我每个季度会做一次技能体检把那些调用率低、效果一般、与其他技能重叠度高的技能合并或移除。清掉冗余技能之后模型选对率通常会有肉眼可见的提升。最后分享一点个人体会技能体系对 Agent 开发的价值不是立竿见影式的而是“润物细无声”式的。我在刚开始做技能抽象时一度觉得这套流程太重——又是 manifest、又是测试集、又是依赖管理远不如直接堆功能来得快。但坚持做了两个月之后效果开始复利式显现新功能开发速度变快了老功能维护不再提心吊胆团队协作也更顺畅。这里面的关键不是“技能”这个名词本身而是你愿不愿意为长期的可维护性付出当下的额外成本。另一个感受是Agent 技能体系没有标准答案你的路由方式、描述风格、技能颗粒度都会因为业务场景的不同而有很大差异。不要照搬任何模板从自己最常遇到的痛点入手先做两三个技能跑通全流程再逐步扩大。这套方法论在任何场景下都适用先用最小闭环验证思路再规模化复制。如果你也在做 Agent 应用不妨从今天开始挑一个使用频率最高的功能把它重构成第一个技能试试看。