直接说结论agent-skills不是一个具体框架也不是某个公司的官方项目名而是一类正在快速成型的设计模式——把 AI Agent智能体的能力拆成一个个可复用、可维护、可编排的“技能单元”再让模型在合适的时机自动选择并调用它们。这一两年我做过的几个 Agent 项目从最早“把所有工具塞进一个大 prompt”的粗暴阶段到后来逐步转向“技能化”组织踩坑很多收获也很大。如果你正在做 Agent 相关的开发或者想给自己的 AI 应用加一层更强的工具执行能力这篇内容应该能帮你在动手前把整体思路理顺。很多人会把“技能”理解成“给模型多配几个 function”这种理解不能说错但很片面。我在实际操作中的体会是技能化带来的最大变化不是“能调的东西变多了”而是 Agent 的行为边界、诊断路径、扩展方式都变得清晰了。过去模型拿到十几个工具的 JSON 定义后经常出现“工具选择混乱、参数编造、来回反复”的情况把这些工具改造成有明确输入输出、有验证逻辑、有失败反馈的技能模块后同样一个模型任务完成率和可调试性都上了一个台阶。1. 先说清楚agent-skills 到底是什么1.1 一个让我印象深刻的实践我去年做一个企业知识库问答 Agent 时开始时给模型挂了五个搜索接口、两个文档解析接口、一个权限校验接口。模型经常做的事是用户问“帮我查一下上季度的报销制度”它真的会先去调权限接口再用搜索接口跑一遍全库扫描然后给用户返回一段很长的“我权限不够所以没法精确回答”的内容。问题不在搜索质量而在于模型根本不知道这些接口之间的关系和调用边界。后来我重新整理思路把每个接口都包装成带明确“适用判断”的技能。比如“制度检索”技能自己就先判断权限无权限就直接返回明确的拒绝消息而不是把底层错误堆给用户再比如“报销流程查询”技能只处理流程类问题一旦识别到用户问的是“标准金额”而不是“流程步骤”它会主动转给另一技能。改完之后同一个模型、同一个知识库任务完成率从不到 60% 提升到 85% 以上。这让我下决心把整套逻辑拆清楚。1.2 技能和普通提示词的区别在很多博客里“技能”Skill通常被描述为一段特定的 prompt 模板比如“联网搜索技能”“代码解释技能”。但在我实际落地的项目里一个真正可用的技能单元至少包含四个部分触达判断该技能在什么条件下被激活什么条件下不会被激活这部分负责“决策”。执行步骤技能内部要调用的模型、工具 API、代码逻辑以及它们之间的顺序这部分负责“行动”。输入输出契约技能对外暴露的参数结构、返回数据格式、异常类型这部分负责“对接”。反馈与教学技能执行失败时Agent 如何根据错误信息调整后续行为这部分负责“闭环”。这跟传统意义上的 prompt 模板有本质区别模板是静态的适用于单一对话场景技能是动态的带执行逻辑、带状态管理、带错误处理。你可以把它理解成把原本写在“思维链”里的步骤升级成了有独立生命周期的模块。1.3 为什么现在大家开始关注这个设计核心原因只有一个模型的上下文窗口再大也装不下无限量的工具说明和示例。你给模型说清楚“什么时候用搜索、什么时候用计算器、什么时候用代码执行”标注十条示例和标注五十条示例效果差距不大但 token 开销成倍上涨响应速度明显变慢。技能化的思路是——让模型先决定“调用哪个技能”再把该技能的详细说明注入上下文。这样既控制了 token 消耗又让模型每次只专注理解一个领域内的规则准确率自然变高。另一个原因是工程协作的需要。以前 Agent 的工具定义、prompt、逻辑散落在不同文件里改一处常常牵动全局。技能化之后每个技能都像一个独立的小微服务由不同的人维护各自的逻辑相互之间只需保证输入输出契约稳定。我团队里现在就是这样分工基础技能搜索、计算、代码执行由平台组维护业务技能订单查询、售后处理、退换货判断由业务组维护两边通过契约文档对接开发效率高了很多。2. 技能的颗粒度划分从工具到工作流的组合逻辑2.1 原子技能、复合技能、工作流的定义我在实际设计中最常被问到的问题是“一个技能应该多大才算合适”我自己的标准很简单看它能不能被别的技能复用。如果一个技能只做一件事且这件事无法再往下拆比如“将当前时间转换为 Unix 时间戳”“提取文本中所有邮箱地址”“对一段代码执行静态检查”那它就是原子技能。原子技能的特点是最小、最稳、最容易测试。凡是能拆出原子技能的都尽量不要和其他逻辑裹在一起。当几个原子技能按固定顺序组合完成一个相对完整的业务目标时比如“搜索某关键词 → 提取前十条结果的标题和摘要 → 翻译成中文”我就把它叫做复合技能。复合技能内部同样有自己的 prompt 和执行逻辑但对外暴露的接口只有一个——外界无需关心它内部调了几个原子技能。再往上跨多个复合技能、带条件分支和动态路由的完整流程我习惯称之为工作流。工作流通常不直接面向底层工具而是面向业务目标比如“处理客户退款申请”“生成月度数据分析报告”。这种分级的核心价值在于底层技能越多组合能力越强但模型决策难度也越大顶层工作流越明确模型决策越容易但灵活性越低。你需要在这两者之间找到平衡点。2.2 怎么划分才算合理这里分享一个我自己常用的判断方法把模型可能收到的用户请求列出来逐个分析触达路径。如果两条请求的触达路径有 80% 重叠只有尾部处理逻辑不同那就说明它们可能共享同一个复合技能只是尾部走不同分支如果两条请求的触达路径完全不同连前置判断条件都不同那它们更适合拆成两个独立技能。举例来说“查询订单状态”和“查询物流轨迹”这两个请求触达路径其实高度一致——都需要先验证用户身份、获取订单号、判断订单是否属于当前用户只有最后一步调用的接口不同。这种情况下拆成两个独立技能会浪费大量重复验证逻辑还容易让模型选错合并成一个“订单查询”技能内部根据用户意图分流到“状态”或“物流”分支体验反而好很多。如果一段逻辑在多个场景里反复出现比如“判断用户是否登录”“检查用户是否有某权限”“清理输入文本中的敏感信息”那就应该抽成独立的原子技能让多个复合技能共用。在我做的客服 Agent 里“登录判断”这个原子技能被二十多个业务技能引用一旦身份校验逻辑更新只需要改这一处所有调用方自动生效省掉了很多重复维护成本。2.3 我从几次失败里总结的设计经验第一次做技能拆分时我犯了一个典型错误把技能切得过碎。当时觉得“能拆就拆”是衡量设计水平的标准于是把“读取文件”拆成“读取 CSV”“读取 Excel”“读取 JSON”“读取 Markdown”四个技能。结果那份 Agent 在用户说“帮我打开桌面上那个表格”时直接懵掉因为它不知道“表格”到底对应哪个技能——模型需要花很大力气去做实体映射而映射的失败率比想象中高得多。后来又犯过一个相反的错误把“处理售后问题”这个大技能里塞进了退款、换货、维修、补偿四套逻辑和十几个参数。技能描述写得又长又复杂模型经常漏传参数或者把一个业务场景的参数错误地带到另一个场景里。现在我的平衡原则有三条基本能避开这两类坑一个技能必须有明确的“单一职责描述句”如果描述句里用了“和”“同时”“以及”这类连接词说明它该拆分了。一个技能对外暴露的参数尽量控制在五个以内超过七个参数模型漏传、乱传的概率会直线上升这点我后面细说。复用频率高的逻辑优先下沉为原子技能业务专属逻辑留在复合技能层保持清晰的层级关系。3. 搭建一个可复用的技能库选型思路与目录组织3.1 技术选型Python YAML JSON Schema 的思路技能库的底层实现我建议用 Python原因不是什么性能优势而是生态匹配度。当前主流的 Agent 框架基本都是 Python 生态模型调用、函数定义、数据校验都有现成库不用重复造轮子。真正值得花心思的是技能的“描述文件”格式。我采用的方式是每个技能一个目录里面包含一份SKILL.yaml文件和若干可执行的.py脚本。SKILL.yaml负责记录技能的元信息技能名称、适用场景、参数定义、返回格式、失败反馈文案。.py脚本则承载真正的执行逻辑。这样做的最大好处是模型的决策层只关心 YAML 里的人类可读描述不用关心底层实现工程师维护逻辑时也不需要反复阅读模型层的 prompt 文本。YAML 文件里的参数定义我强烈建议配合 JSON Schema 做校验。原因很实际模型生成的参数经常出现字段缺失、类型错误、枚举值越界等问题如果不做校验错误会在下游接口里暴露得非常难查。加上 JSON Schema 之后技能层可以统一捕获校验失败信息把“缺了哪个字段、哪个字段类型不对”清晰反馈给模型让模型基于确切错误信息自行修复。3.2 技能目录的组织方式目录组织上我参考了 Unix 工具的设计思路按能力域分一级目录按具体技能分二级目录每个技能目录内固定包含描述文件和实现代码。一个典型结构长这样skills/ ├── common/ # 基础原子技能 │ ├── datetime_tools/ │ │ ├── SKILL.yaml │ │ └── implement.py │ ├── text_utils/ │ │ ├── SKILL.yaml │ │ └── implement.py │ └── web_search/ │ ├── SKILL.yaml │ └── implement.py ├── business/ # 业务复合技能 │ ├── order_query/ │ │ ├── SKILL.yaml │ │ └── implement.py │ └── after_sale/ │ ├── SKILL.yaml │ └── implement.py └── workflows/ # 跨技能工作流 └── refund_process/ ├── SKILL.yaml ├── workflow.py └── steps/ ├── step1_validate.py └── step2_execute_refund.pycommon目录下放所有通用原子技能business目录下放各个业务域的复合技能workflows目录放跨技能编排的工作流。层级别超过三层超过三层之后模型定位技能的效率显著下降维护成本也会跟着涨。3.3 一份技能清单示例拿一个客服场景举例我把技能清单简化为这样一份表格技能名称类型触发场景核心参数输出内容用户身份验证原子技能所有需要确认身份的请求user_id, token验证结果订单状态查询复合技能用户询问订单进展order_id, user_id订单状态与流转记录物流轨迹查询复合技能用户询问物流位置order_id, carrier物流轨迹列表退款申请处理工作流用户发起退款order_id, reason, amount申请结果与工单号售后政策解读复合技能用户询问退换货规则category, question政策要点与解释每个技能在注册到模型时只会暴露上述表格中的信息而不会把内部实现的细节全部塞给模型。这跟“把所有函数定义堆在一起交给模型”的做法差异巨大决策层的负担小很多模型的选择准确率也高很多。4. 用好技能的关键上下文控制与调用策略4.1 控制上下文窗口的几种手段技能化表面上解决的是“工具变多模型选不对”的问题深层看是在控制上下文窗口的使用方式。我实测过频繁注入大量工具定义的效果当函数定义总量超过 20 个时模型不仅选择准确率下降第一轮响应的延迟也会明显增加因为模型需要处理的信息量太大。我的做法是在系统层做一个“技能路由预筛”先用一个轻量的分类模型或者一套启发式规则根据用户输入快速锁定可能相关的三到五个技能只把这几个技能的定义注入主模型的上下文。这本质上是“粗筛 细选”的思路粗筛阶段用低成本手段缩小候选集细选阶段让主模型从三五个候选里挑一个。这样做的准确率比让模型从二十个甚至更多技能里盲选要高很多token 开销也更可控。另一个控制上下文的手段是“技能描述压缩”。每个技能的描述尽量控制在二百个字以内把长说明放到技能的usage_examples字段里只在该技能被选中后才注入。如果一开始就位每个技能都附上五个示例上下文早就塞爆了。4.2 技能描述里该写什么、不该写什么这是整个设计中最容易被低估的环节。模型能不能正确选择技能很大程度上取决于描述写得是否“可判别”。我总结了一个基本框架该写的技能的触发场景用具体业务语言描述例如“用户想查询某订单的发货时间或配送位置”。技能的相反场景明确说明不能用在哪例如“本技能不处理退换货退换货请参考售后政策技能”。参数的取值规范尤其是枚举值和格式要求例如“carrier 仅支持 sft、zto、yto 三个值”。不该写的不要写内部实现细节例如“调用 HTTP 接口 GET /api/order”这类内容只会干扰模型判断。不要写与调用决策无关的修饰词例如“本技能非常强大、很高效”这种描述纯粹浪费 token。不要把多个技能写在一段模糊描述里模型会因为表述不清而做出错误路由。我自己踩过最大的坑是技能描述写得过于模糊比如“处理用户查询”结果模型几乎把所有问题都路由到这个技能上。后来我改了描述加上“仅处理订单类查询”这种边界定语路由准确率立刻改善。描述里多一点限定词背后是帮模型省去无数猜测。4.3 动态加载与RAG式技能检索当技能数量超过三十个甚至上百个时靠分类模型做粗筛也不太够了。这时候可以考虑引入向量检索把所有技能的描述文本向量化用户请求进来后先和技能描述做相似度检索取出相关度最高的 Top-K 个技能再交给主模型做最终判断。这种方式实际上是把“技能选择”从一次决策变成两级决策第一级用向量检索做初步召回第二级用主模型做精细化选择。我在一个技能数近百的文档处理 Agent 上试过这个方案效果比单纯依赖模型选择高出一截尤其是在技能之间描述相似度较高的时候向量检索能先把领域锁对再让模型在领域内做精确判断。这里需要提醒一点向量检索的召回率受描述文本质量影响极大。技能描述如果全是抽象术语检索效果会很差描述里带一些具体业务词汇、常见用户表达方式召回质量会明显改善。所以我一般会让一线业务人员参与技能描述撰写他们知道用户真实会怎么表达。5. 常见问题与排查技巧实录5.1 模型不按预期调用技能这是所有 Agent 项目里出现频率最高的问题。模型放着现成技能不用非要凭记忆瞎答或者选了个毫不相干的技能执行。出现这种情况时我的排查顺序是先看技能描述是否与用户常见表达匹配再检查技能的命名是否出现歧义最后看是否是上下文里其他信息干扰了模型判断。有一次我们做法律文档问答技能“法条检索”在用户问“工伤认定标准是什么”时总不被调用。排查后发现团队给技能写的描述是“检索相关法规条文”模型理解成只有用户明确说“查法条”时才触发。后来改成“用户询问法律条款、认定标准、赔偿标准时调用”触发率立刻上来了。技能描述一定要跟着用户的表达习惯走而不是照着开发者的专业术语写。5.2 多技能互相干扰当多个技能描述中存在相似词或重叠场景时模型会经常把 A 技能误判成 B 技能。解决思路是给每个技能加上“反例描述”明确说明哪些情况绝不归它管。这种方法在执行层很容易落地却往往能解决模型层最头疼的路由问题。例如“订单状态查询”技能和“物流轨迹查询”技能描述里都含有“订单”字样模型就容易混淆。我给前者加了“仅返回订单审核状态不返回发货后的物流位置”给后者加了“仅在用户询问包裹到哪里时使用”两个技能的选择准确率就从七成直接提升到九成以上。别小看这几句话它等于帮模型划清了决策边界。5.3 技能执行时参数校验失败模型生成的参数经常不满足要求尤其在日期格式、数字范围、枚举值这几个方面。我的经验是不要试图让模型直接生成规范参数而应在技能内部做一层“参数包容转换”。比如用户说“帮我查下周一的订单”模型可能把“下周一”转换成格式不标准的日期字符串与其报错不如设计一个日期解析函数把所有常见中文日期表达统一转换成标准格式。把参数兼容逻辑下沉到技能内部模型容错率会大幅提高。我会在技能里预置一组格式统一函数模型负责提取关键实体技能负责把实体映射成规范参数。这一步在早期项目中经常被忽略结果表现为“用户请求很正常Agent 经常执行失败”排查半天才发现是参数规范化的问题。5.4 技能执行超时与失败重试Agent 技能执行时还会遇到一个工程侧很头痛的问题技能内调用第三方 API偶尔网络超时或服务返回 500模型被错误信息卡住开始反复自我修正甚至出现死循环。我的做法是给技能执行设定明确的超时阈值同时准备降级路径——主技能失败后自动切换备用技能而不是把原始错误甩给模型。举例来说订单查询技能主接口超时后自动触发备用库查询逻辑这在技术上没有任何特殊之处但对用户体验的稳定性提升是巨大的。另外我会在技能返回结构里增加一个fallback_used字段方便后续日志分析判断什么场景下需要走备用链路再针对性优化主链路的稳定性。6. 一点个人经验与后续扩展思考这些内容写到这里核心的思路和实操方法基本都覆盖了。最后分享几个我在实际项目里沉淀下来的经验。第一个经验技能库一定是从业务场景里长出来的不是一次性设计出来的。不要试图在项目第一天就把技能体系规划得尽善尽美。更务实的做法是从三五个反复出现的核心场景做起先跑通端到端链路再根据实际对话日志持续拆分和合并技能。我最早那份客服 Agent 的技能数量从最初的 7 个涨到 28 个又精简到 19 个每次调整都是因为实际对话数据暴露出了问题。设计时追求完美反而容易做出过度模块化的空壳。第二个经验一定要为技能设计“可观测性”。每个技能被谁调用、输入是什么、输出是什么、消耗多少 token、耗时多久这些数据都要记下来。没有这些数据后续优化技能描述颗粒度、调整路由策略都会变成拍脑袋决策。我后来用一套简单的日志聚合把技能调用链路可视化很多隐蔽问题立刻清晰起来。第三个经验关于模型选型别盲目追求大模型。层级化技能库设计的一个附带收益是——你可以用较小的模型做路由粗筛用中尺寸模型处理具体技能调用用大模型只处理复杂推理。这种混合架构能在成本和效果之间找到更好的平衡点。我刚做 Agent 时默认所有环节都用最强模型后来在技能路由层换成小型模型后整体成本下降了三成路由准确率几乎没有下降。再往后扩展几个方向值得跟进技能质量的红线检测与自愈机制、技能版本管理与灰度发布、技能之间的依赖图谱与自动编排。这些方向都是在“技能可用”之后再进一步追求“技能体系成熟”。如果这篇内容能帮你对 agent-skills 的整体架构有个清晰认识那我的目的就达到了。