做AI应用这两年我踩过一个很大的坑给大模型接了一堆工具结果它真正跑起来的时候反而不知道什么时候该用哪一个经常在无关的工具之间来回横跳。后来我把整套交互方式改成了Agent Skills——把每一个工具变成一份带使用说明、参数契约和触发条件的技能卡片让模型像装新技能一样按需调用整套系统才真正稳定下来。这篇是系列教程的第10篇也是从入门到进阶的一个阶段性收尾前面九篇我把大模型的基础调用、提示词工程、检索增强和工具调用都梳理了一遍这一篇专门讲Agent Skills它是什么、为什么值得学、怎么从零写出能上生产环境的技能。不管你是刚接触大模型开发的新手还是已经在做智能体应用但总觉得“模型不太听话”的开发者这篇都适合你。我会用一套完整的实操案例把技能设计、注册、路由、编排和调试的完整链路讲清楚附带我在真实项目里反复踩过的坑。1. 一句话说清Agent Skills它到底解决什么问题1.1 没有技能的大模型Agent像一个只会空谈的顾问我们先回到一个最基础的问题大模型本身只是“会说话”它能写文案、能推理、能总结但让它去查数据库、算复杂公式、调用外部系统它就抓瞎了。于是有了工具调用Function Calling / Tool Use让模型可以申请调用某个函数再把结果拿回来继续思考。但在真实项目里工具调用的体验远没有想象中顺滑。我见过太多团队把几十个工具一股脑塞给模型结果模型选择工具的正确率惨不忍睹。问题出在哪出在工具本身缺少“使用说明书”。打个比方这就像你给一个实习生一把电钻、一把扳手、一台示波器告诉他这些都是工具需要的时候自己选。实习生当然一脸懵——他都不知道电钻该用在哪、扳手拧多大扭矩、示波器怎么接线。Agent Skills要做的事情就是把这些“工具”升级成“技能卡”每张卡片上写清楚这个技能解决什么问题、什么时候该用、参数怎么填、输出长什么样、有哪些限制。模型拿到技能卡以后不需要靠猜而是像人一样按照使用说明去操作。1.2 Skills与其他Agent机制的边界别再傻傻分不清入门Agent开发最容易被绕晕的就是一堆概念Function Calling、ReAct、Tool Use、MCP、Agent Skills。我用自己的话给它们划条线概念定位与Agent Skills的关系Function Calling模型输出结构化调用指令的能力技能落地的底层机制之一ReAct推理-行动-观察的循环范式技能被调用时的执行流程Tool Use让模型使用外部功能的通用方式技能是工具的“升级包”MCP将工具能力统一封装成标准化服务技能可以是MCP服务的轻量替代或补充Agent Skills带完整语义描述、验证逻辑和上下文约束的可执行能力单元面向任务的最高层抽象一句话总结Function Calling是“手”MCP是“物流网络”而Agent Skills是“带岗位说明书的员工”。它不光告诉你有什么工具还告诉你什么时候用、怎么用、用完怎么处理。我在实际项目里见过很多团队纠结“我要不要上Skills还是继续用普通Tool”。我的判断标准很简单如果你的工具数量少于5个且每个工具的边界非常清晰普通Tool够了但一旦工具超过10个、参数复杂、调用之间存在依赖关系不上Skills体系基本等着在调试中崩溃。2. 为什么我用技能化方案重构了整套智能体架构2.1 从“自由工具调用”到“技能封装”的思路转变最早我做Agent时采用的是最朴素的方案把所有工具定义成JSON Schema塞进system prompt让模型自己选。一开始只有3个工具很正常后来业务扩张到20多个工具问题接踵而至。第一个问题是描述冲突。两个工具看起来都能“查数据”模型经常选错。第二个问题是参数幻觉。工具需要“日期范围”模型经常编一个不存在的格式。第三个问题是上下文污染。全部工具定义塞进prompt里光工具描述就占了几千个token模型注意力被稀释主任务反而做不好。技能化方案的核心思路是把“工具清单”变成“技能库”。每一个技能不是孤立的函数签名而是一个包含多维度描述的对象技能名称和别名方便模型检索适用场景和禁忌场景减少误用参数Schema、必填项、格式示例减少幻觉执行入口、超时策略、幂等性说明典型输入输出对示例few-shot样例帮助模型理解预期行为。我重构之后的第一感受是模型不再“乱撞”了。因为它看到的不再是30个平铺的函数而是带着目录索引和说明书的技能库决策路径清晰得多。2.2 设计一份好用的SKILL.md技能的“灵魂”在描述里很多框架这里不特指某个商业化产品而是社区常见的技能化实践采用一个约定每个技能目录里放一个SKILL.md作为该技能的声明文件。SKILL.md的写法直接决定技能好不好用。我总结过一份模板核心结构如下--- name: sales_data_query description: 查询销售数据的技能支持按时间、地区、产品线维度筛选并返回聚合统计结果。 when_to_use: 当用户询问销售额、销量、同比环比等指标时使用。 when_not_to_use: 当用户仅询问定性分析或未来预测时不要使用本技能。 version: 1.2.0 parameters: start_date: type: string format: YYYY-MM-DD required: true description: 查询起始日期注意时区为UTC8。 region: type: string enum: [east, south, west, north] required: false description: 区域筛选不传代表全国。 --- # 执行说明 1. 调用 query_sales_table 获取明细数据。 2. 对返回结果按 dimension 参数做聚合。 3. 输出格式要求先给结论数字再给趋势说明。 # 示例 用户问题: 上个月华东区销售额是多少 技能调用: - start_date: 2025-05-01 - end_date: 2025-05-31 - region: east这里最容易被忽略的是when_not_to_use字段。早期我写技能描述只写“什么时候用”结果模型把许多不该调用技能的请求也路由过来白白消耗时间和token。后来我研究了一批被错误触发的case发现绝大多数是因为模型“不确定但觉得试试也行”。加上“什么时候不用”之后误触发率直接下降了一大截。description字段也别写得像说明书那么干。我习惯在里面加“业务目标描述”比如这个技能是为谁服务的、输出给谁看。模型对“目标导向”的描述理解能力明显强于“结构导向”的描述。2.3 技能注册表与路由机制模型是怎么找到正确技能的当技能数量超过一定规模后你不能把所有技能的SKILL.md都塞进每次对话的上下文中token消耗和注意力分散都受不了。我的做法是引入两级路由机制。第一级是技能索引路由。维护一份全部技能的目录索引每个技能只用一句话描述整体塞进上下文的开销很小。模型先根据用户问题在这份索引里选出top-k个候选技能。第二级是技能详情注入。系统把选中的候选技能对应的完整SKILL.md注入到上下文中模型再据此决定是否调用、如何填参。这种两级设计很像人类查资料的过程先翻目录确定大致方向再找到对应章节细读。我在项目里把top-k设为3实测效果最好。k太小容易漏掉正确技能k太大会让模型在多个相似技能之间纠结。路由策略优点缺点适用场景全量注入实现简单模型信息完整token开销大干扰增多技能少于10个索引详情两级路由开销可控命中率稳定需要维护索引质量技能10~100个向量检索路由支持语义匹配扩展性强需要维护向量库冷启动麻烦技能100个以上我在生产项目里用的是两级路由因为技能数量长期维持在30个上下向量检索引擎在这个数量级上收益有限反而多了一层延迟和索引一致性问题。如果你的技能库将来会突破几百个再考虑在上层加一个向量召回层会比较稳妥。3. 从入门到进阶的落地实操一套完整的技能开发流水线3.1 阶段一入门先写一个真正能用起来的技能很多教程让你一上来就搞一个多技能编排系统我建议先稳扎稳打写一个技能跑通全流程。我们做一个“时间处理技能”解决一个很常见的大模型痛点模型算不准日期比如“下周三”到底是几月几号。技能目录结构大致如下skills/ └── date_calculator/ ├── SKILL.md └── execute.pySKILL.md核心内容--- name: date_calculator description: 计算相对日期、工作日、时间区间的技能。当用户提到“下周三”“三天后”“本季度最后一天”等相对时间表达时使用本技能。 when_to_use: 对话中需要将自然语言时间转换为具体日期或进行日期加减。 when_not_to_use: 用户已给出明确日期如2025年6月1日时直接使用该日期无需调用本技能。 parameters: expression: type: string required: true description: 自然语言时间表达式如下周三、三天后、本月最后一天。 base_date: type: string format: YYYY-MM-DD required: false description: 基准日期默认为当前日期。 --- # 执行说明 1. 解析 expression 参数中的自然语言时间描述。 2. 若提供base_date以该日期为基准计算否则以系统当前日期为基准。 3. 返回格式YYYY-MM-DD并附一句话说明推算依据。execute.py核心逻辑示意from datetime import datetime, timedelta import parsedatetime # 一个常见的自然语言时间解析库示例 def execute(expression: str, base_date: str None) - dict: base datetime.strptime(base_date, %Y-%m-%d) if base_date else datetime.now() cal parsedatetime.Calendar() time_struct, parse_status cal.parse(expression, base) if parse_status 0: raise ValueError(f无法解析时间表达式: {expression}) result datetime(*time_struct[:6]) return { result_date: result.strftime(%Y-%m-%d), explanation: f以{base.strftime(%Y-%m-%d)}为基准根据表达式「{expression}」推算得到{result.strftime(%Y-%m-%d)} }跑通这个技能的关键不是代码而是“让模型真正理解什么时候该调”。我当时做了一次验证分别用“普通工具描述”和“SKILL.md完整描述”两种方式让同一模型完成一组包含相对时间表达的任务。结果显示完整技能描述下模型调用准确率从67%提升到了92%差距非常直观。3.2 阶段二进阶技能编排与组合让技能之间学会协作单个技能跑通后下一步是让多个技能协作完成复杂任务。这是从“会写技能”到“会做Agent”的分水岭。我在项目里经常遇到一类需求用户问“帮我分析上季度华东区销售下滑的原因并生成一份简要报告”。这个任务至少涉及三个技能数据查询、指标分析、报告生成。但你不能简单地把三个技能并列丢给模型因为技能之间有数据依赖。我的做法是引入任务编排层允许技能声明“前置依赖”和“输出契约”。例如# 指标分析技能 SKILL.md 片段 depends_on: - sales_data_query output_contract: type: analysis_result fields: [trend, anomaly_points, contributing_factors]执行时编排层先启动数据查询技能拿到结构化数据后再触发分析技能最后把分析结果交给报告生成技能。这种设计把“模型自由发挥怎么调用”变成了“在约束DAG里做调度选择”稳定性大幅提升。我也尝试过全交给模型自由编排也就是让模型自己决定调用顺序但实践中发现它经常跳步或重复调用。比如在分析任务中模型可能先调了报告生成发现没数据又回头调查询白白浪费了一轮延迟。设置依赖关系之后这类问题基本绝迹。这里有一个重要的心得技能编排不要设计得太死。我在依赖声明里加了一个optional标志允许部分技能在数据缺失时“跳过但不报错”。这样既保证了流程的方向感又给模型留了容错空间。3.3 阶段三进阶技能的可观测性与调试手段技能上了生产环境后最头疼的问题就是“模型今天调对了明天调错了”而且你还不知道为什么。我建议每个技能执行时都记录一份调用轨迹包含以下字段字段说明我为什么关心它trigger_query触发本次调用的原始用户问题排查误触发route_score路由阶段模型对技能选择的置信度判断路由边界是否清晰param_values实际传入的参数检查参数幻觉execution_time技能执行耗时发现性能瓶颈error_message执行阶段的报错信息定位故障final_response技能返回给模型的最终结果评估输出质量我在项目里把Agent Skills的调试分成三层第一层是路由调试。如果技能被错误触发多半是SKILL.md里的when_to_use和when_not_to_use写得不到位。这时候我会直接在技能描述里补反例。比如时间技能一开始没写“用户已给出明确日期时不要调用”于是模型经常画蛇添足调一下。补上反例之后立刻好转。第二层是参数调试。模型传参经常出现格式错误解决办法不是指望模型变聪明而是在技能执行入口做防御性校验并给模型即时反馈。比如日期格式不对时返回一个包含正确格式示例的错误信息模型看到后会自动纠正重试。# 参数校验失败时的返回示例 { error: INVALID_ARGUMENT, message: start_date必须使用YYYY-MM-DD格式例如2025-06-01。当前收到值: 06/01/2025, suggestion: 请将start_date转换为2025-06-01后重新调用 }第三层是结果调试。技能返回的结果如果语义不对模型后续推理就会被带偏。我习惯在每个技能返回结构里增加data_quality_hints字段比如数据完整度、异常值标记让模型知道“这份数据有哪些地方不可信”。这套三层调试体系上线后我在项目里定位问题的时间平均缩短了七成。以前是一个个查日志猜原因现在直接顺着轨迹看是哪一层出了问题。4. 常见问题与排查技巧实录我把踩过的坑都写在这里4.1 模型总在相似技能之间纠结怎么破症状两个技能功能相近比如“查询销售额”和“查询订单量”模型经常二选一选错。我试过的解法里最有效的是在SKILL.md里做“差异化强调”。与其写“本技能用于查询销售额”不如写“本技能用于查询销售额汇总数据输入维度是时间/地区/产品线如果你需要查询订单明细或单笔订单状态请使用另一个技能”。另一个实用技巧是在技能索引里为相似技能添加“互斥提示”。当一个问题命中技能A时系统在注入的上下文里直接附一行备注“注意此问题不应路由到技能B因为技能B处理的是XX场景。”这相当于给模型递小抄实测能把相似技能的混淆率降低一半。4.2 技能描述太长token开销扛不住技能写得太详细虽然准确率高但全部注入上下文会让单轮对话的token用量暴涨。我的折中方案是SKILL.md保持完整版供高层编排读取但注入模型上下文时使用压缩版。压缩版只保留四个字段技能名、一句话说明、参数Schema精简版、触发条件的正反例各一条。我实测压缩后token开销减少约60%而技能命中率只下降2~3个百分点——这个交换完全值得。4.3 技能执行报错后模型陷入死循环当技能执行抛出异常时如果反馈信息不够明确模型会选择不断重试同一个错误调用形成死循环。我见过一个项目里模型连续调用了8次同一个报错的技能浪费了大量时间和费用。解法是在错误反馈里加一个retry_advice字段明确告诉模型“不要重试请向用户说明当前无法获取数据或者尝试提供替代方案”。大多数模型会遵循这个指引跳出循环。另外我在编排层还加了一个硬性限制同一个技能单次对话最多允许失败重试2次超过则强制要求模型放弃该技能。问题根因我的处理方案相似技能经常选错技能描述缺乏互斥边界增加差异化说明和互斥提示模型传参格式错误参数示例缺失增加格式示例和类型校验反馈错误后无限重试错误信息不够明确增加retry_advice并限制重试次数技能该调不调when_to_use写得过于模糊补充具体触发示例和正反案例多个技能协作时跳步依赖关系未声明在SKILL.md中增加depends_on声明4.4 小心“技能过拟合”描述写得太死反而不会变通这里要提醒一个进阶陷阱。我在早期做技能描述时太想追求准确率把 when_to_use 写得极其细比如只会匹配“销售额”“营收”这两个词。结果用户换一种问法——“上个月赚了多少”——模型就识别不出应该调用销售查询技能了。后来我把技能描述改成“语义场景”而不是“关键词清单”。不再罗列具体词而是描述用户意图“当用户表达对收入、业绩、销售规模的数字或趋势感兴趣时”。改完之后模型对多样化表达的泛化能力明显增强。这个度和很多调参工作一样需要反复测试。我的经验是先用宽松描述跑一批真实问题找出所有“误触发”和“漏触发”case再针对性地收紧或放宽边界一般迭代三轮左右能稳定下来。5. 技能化Agent的下一步我用在真实项目中的几点体会最后聊聊这个方向。Agent Skills 之所以值得投入精力学习是因为它把“大模型能力”和“业务能力”做了很好的解耦。模型负责判断和生成技能负责稳定地完成具体动作。哪块业务逻辑变了只需要替换对应的技能包而不需要动整个Agent框架。这种模块化思路在项目规模变大之后带来的维护红利会非常明显。我在某个跨平台数据分析项目中做过一次对比早期用单一Agent加十多个平铺工具迭代一个业务变更往往要改三到四个文件还容易影响其他功能重构为技能化方案后大部分变更收敛到单个技能目录内回归测试也只需要聚焦对应技能。这种隔离性对团队协作的改善是单纯看代码量看不出效果的。如果你准备在自己的项目里引入Agent Skills我的建议是别一开始就追求大而全。先挑一个调用频率最高、边界最清晰的功能做技能化试点跑通后再逐步扩展。过程中保留好调用轨迹日志它们会是你优化技能描述最宝贵的依据。我在实际调试中还有一个“压箱底”的小技巧在技能库里故意加入一个名为noop的占位技能它的描述是“当其他技能都不合适时直接返回用户说明自己无法处理”。别小看这个设计它给了模型一个体面的“拒绝出口”避免了模型为了完成指令而硬凑一个不合适的技能。加入这个占位技能后整个系统的不当调用率下降了一个量级。这个做法如果对你有启发不妨直接在下一个项目里试一下。