Agent Skills这几年在AI Agent圈子里出现的频率越来越高，尤其是在围绕大模型做自动化任务设计的团队中，几乎成了标配概念。我最早接触这个方向，是在给一个内部运营机器人做能力抽象的时候，当时模型调用工具的准确率一直上不去，后来把技能库（agent-skills）独立抽出来做工程化治理，才真正解决了问题。这篇内容想结合自己的实操经验，聊聊Agent技能库的设计思路、实现方式，以及我在落地过程中踩过的一些坑。
这套东西适合谁参考？如果你正在做大模型应用开发、Agent框架搭建、自动化流程编排，或者你只是想让自己写的Prompt更稳定、更可控，那这篇文章应该能给你一些可以直接复用的思路。
1. Agent Skills到底解决了什么问题
1.1 从“会聊天”到“会办事”的那道坎
大语言模型的核心能力是推测和生成语言，但落到实际业务场景里，我们要的不是它“会说话”，而是它“能办事”。比如你让它“帮我把上周的销售数据整理成日报”，模型得知道去哪里拿数据、需要哪些字段、以什么格式输出、异常情况怎么处理。这些内容如果全部塞进Prompt里，模型的理解负担会非常重，执行结果也容易飘。
Agent Skills的出发点，就是把“做一件事的能力”封装成一套可供模型调用的结构化模块。每个技能内部包含了明确的执行逻辑、入参定义、输出格式、边界条件和错误处理机制。模型只需要理解“这个技能是做什么用的、什么时候该调用它”，至于技能内部怎么实现，模型不需要关心。
我在项目里的体会是，这种方式让模型的注意力从“怎么做”转移到了“该做什么”上。模型不再需要去推理繁琐的执行细节，只需要完成一次选择：当前任务对应哪个技能。这个选择一旦变简单，整体稳定性就会明显上升。
1.2 技能和Function Calling、Prompt模板有什么本质区别
很多刚开始接触Agent开发的人会问：我有Function Calling了，为什么还要做一套技能库？我的理解是，这两者的定位完全不同，解决的问题也不同。Function Calling解决的是“模型如何触发一个工具调用”，它偏底层通信；而Agent Skills解决的是“业务能力如何被组织、描述、编排和复用”，它偏架构设计。
做一个对比就清楚了：
| 维度 | Function Calling | Agent Skills |
|---|---|---|
| 抽象层级 | 单体工具触发 | 业务能力封装 |
| 核心问题 | 模型怎么调工具 | 技能怎么描述和组合 |
| 组织粒度 | 单一函数 | 多工具/多步骤组合体 |
| 复用方式 | 接口级复用 | 任务级复用 |
| 治理难度 | 工具多了会混乱 | 需要系统的注册、检索、编排机制 |
| 稳定性来源 | 参数schema清晰 | 描述质量+编排逻辑+评估闭环 |
用一句大白话来说，Function Calling是让模型“叫得上一个人的名字”，Agent Skills是让模型“知道这个人擅长什么、什么时候该找他、他做事的流程是什么”。如果你只依赖Function Calling，工具数量一多，模型就会出现“叫错名字”或者“不知道该叫谁”的情况。有了技能库，这个选择过程就变得有据可循了。
2. 技能库的第一步：设计一份能被模型“看懂”的技能描述
2.1 技能描述的结构化设计：名称、描述、参数、触发逻辑
技能描述是整个技能库最关键的部分，直接决定模型能不能在合适的时机选中它、能不能用对方式调用它。我见过很多团队前期做了大量工具开发，最后因为描述写得模糊，导致模型根本不知道什么场景下该用，白费了功夫。
我在实际项目中总结出一套基本的技能描述规范，通常包含以下几个核心字段：
技能名称（name）：简短明确，一眼能看出用途。不要用“数据处理器”这样含混的名字，直接用“销售日报生成器”“工单状态查询器”这种语义密集的名称。命名时有一个隐含的排序逻辑在里面：框架通常会按名称或描述做相关性排序，关键词密度越高的技能越容易在早期被选中。
功能描述（description）：需要用一两句话把技能的能力边界说清楚，包括“能做什么”和“不能做什么”。这部分是模型判断是否调用的主要依据，建议写成动作导向的句式。比如“根据用户提供的日期范围和区域，生成销售日报Excel文件，支持按天/周/月聚合”就比“查看销售数据”要准确得多。
参数定义（parameters）：用JSON Schema描述每个入参的名称、类型、取值范围、是否必填。这里有一个容易被忽略的点：参数的约束条件写得越严，模型越不容易产生参数幻觉。比如你明确写了enum: ["day", "week", "month"]，模型就不太会输错值。
触发逻辑（trigger）：现在很多技能库框架支持语义化触发，也就是模型根据描述自动匹配。但我会在实践里额外给每个技能写一段“触发条件”说明，明确什么场景下必须调用、什么场景下不要调用。这个对防止模型“乱调技能”非常有效。
2.2 描述质量决定调用准确率：写好“触发描述”的几个技巧
实践下来，技能描述的质量直接决定模型调用的准确率，比参数定义的影响还大。模型本质上是在做语义匹配，描述里没有覆盖到的场景，它很难凭空推理出来。
第一个技巧是用对话场景反向梳理描述。不要坐在电脑前凭空写技能描述，而是先收集真实用户的提问方式和典型需求，再从中提取共性和变体。比如用户会问“上个季度的销售情况怎么样”“帮我看看华东区的业绩”“同比环比是怎么变化的”，这些问法都指向同一个技能，你就可以在描述里把这些触发点都隐含进去。
第二个技巧是描述里明确负面边界。这是很多人忽略的。一个技能如果不写清楚“什么情况不适用”，模型在模糊任务面前就会倾向于调用它。比如一个“周报生成器”，如果你不写明“仅支持中文周报、仅支持内部系统数据”，哪天用户说“帮我写一篇英文周报”，模型就会傻傻地调用它，然后跑出一个残缺结果。
第三个技巧是给技能写“一句话示例”。在描述末尾附上一个典型调用示例，相当于给模型一个锚点。比如“例如：用户说‘帮我看看上个月北京门店的销售情况’，此时应调用本技能并传入 region=北京, month=上个月”。这听起来简单，但实测下来，调用准确率的提升往往非常明显。
我一直反复跟团队强调一个观点：技能描述不是写给人看的，是写给模型看的。文字的精确度、信息密度和边界清晰度，比文笔优美重要得多。
3. 实操：从零搭建一套Agent Skills技能库
3.1 技能注册与JSON Schema定义
有了设计规范，接下来就是落地的部分。我先分享一个最小可行的技能库实现方式。这里不绑定具体框架，用的是一个轻量级的技能注册思路，你可以迁移到LangChain、CrewAI、自研框架或者任何你正在用的Agent框架里。
每个技能我先定义一个JSON元数据文件，包含技能的基础信息、参数结构、校验规则和实现入口：
{ "skill_name": "daily_sales_report", "display_name": "销售日报生成器", "version": "1.2.0", "description": "根据日期范围和区域生成销售日报Excel文件，支持按天、按周、按月聚合，只支持内部CRM系统数据。当用户询问销售汇总、业绩统计、日报生成时使用。注意：仅支持已接入门店的区域数据，不包含电商平台渠道。", "trigger_examples": [ "帮我生成昨天的销售日报", "看一下最近一周华东区的业绩情况" ], "parameters": { "type": "object", "properties": { "region": { "type": "string", "description": "区域名称，支持华北、华东、华南、西部", "enum": ["华北", "华东", "华南", "西部"] }, "date_range": { "type": "object", "properties": { "start_date": { "type": "string", "format": "date" }, "end_date": { "type": "string", "format": "date" } }, "required": ["start_date", "end_date"] }, "granularity": { "type": "string", "enum": ["day", "week", "month"], "default": "day" } }, "required": ["region", "date_range"] }, "execution_metadata": { "entry_point": "skills/sales_report/run.py", "timeout_seconds": 30, "allowed_retries": 1 } }这里有几个我建议重点关注的细节。description字段我采用了“能力说明 + 触发条件 + 负面边界”的三段式结构，这样可以显著降低模型在模糊场景下的误判率。enum和default是参数幻觉的防火墙，必填项收敛在required里，模型没拿到必需参数时就会主动向用户追问，而不是自行脑补。version字段很多人会忽略，但在技能迭代频繁的项目里，这个字段是排查线上问题的关键线索，哪天模型行为突然变了，先查版本有没有被覆盖。
注册层面，我会在服务启动时扫描skills/目录下的所有元数据文件，构建一个技能索引列表。这个列表就是后面模型检索技能时用的“候选名单”。索引里保存的不只是原始JSON，还包括预处理好的检索向量和关键词映射，具体做法后面会提到。
3.2 技能编排与组合：把简单技能拼成复杂工作流
单项技能只能解决单点任务，真实的业务场景往往需要组合多个技能。比如“把上周的客户反馈整理成PPT发到工作群”这个需求，拆解下来至少涉及数据查询、文本总结、PPT生成、消息推送四个技能。编排层的核心任务，就是把这种组合逻辑以可控的方式组织起来。
我实践下来比较稳妥的思路是“三层分解”。第一步，对用户需求做能力拆解，识别出任务涉及哪几个技能。第二步，定义技能之间的数据依赖关系，比如文本总结技能需要数据查询技能的返回结果作为输入。第三步，为每一步配置失败回退策略，比如PPT生成失败了，是直接重试、换模板重试，还是转人工介入。
这里面最值得提醒的一点是控制好任务分解的粒度。拆得太粗，模型需要每一步都做较大自由度发挥，结果不稳定；拆得太细，又会引入大量交互相干和上下文切换开销，执行链路变得又慢又脆。就我自己的项目体验来说，单任务的技能编排层数控制在3到5层比较合适，超过这个量级中间的异常就很难追溯了。
举个例子，我自己做过一个“竞品动态简报”的技能组合：
- 数据采集技能：抓取指定竞品的公开动态和产品更新
- 信息清洗技能：过滤广告信息和非产品相关内容
- 趋势总结技能：基于清洗后的内容生成本周变化摘要
- 简报生成技能：按固定模板输出为Markdown或PPT
这个流程看起来简单，但每两个技能之间都需要定义清晰的“中间产出格式”，比如清洗后数据要用统一的JSON存储，总结技能才有稳定的输入。这个产出格式的设计，需要提前做，不能边跑边调。
3.3 技能评估与回归：没有评估体系的技能库是债
技能库是一个非常典型的“建设容易维护难”的系统。刚搭建时只有几十个技能，模型调用效果看起来不错；等技能数量增长到几百个，新技能和老技能之间会产生描述重叠、触发语义冲突，整体准确率反而会下降。如果不建立评估体系，技能库就是在背债。
我在项目中做一个叫“技能回归集”的东西：把线上真实用户请求中最典型的100到300条问题收集起来，给每条问题标注“期望调用技能”和“期望参数输出”。每次技能库有变更，比如新增技能、修改描述、更新参数规范，都会跑一遍回归集，观察两个核心指标：技能命中准确率和参数规范化准确率。
这个机制的威力在技能数量膨胀时体现得最明显。有一次我们新增了一个“客户画像查询”技能，发现回归集中有接近三成原本应该命中“客户信息查询”的用例被分流到了新技能上。原因就是两个技能的description语义太接近，模型无法区分。没有回归集，这种问题就像温水煮青蛙，哪天线上用户告诉你“你们机器人怎么突然变傻了”，你才意识到之前的技术债已经积累到失控的地步了。
回归集还有一个额外的好处：它能作为Prompt调优的试金石。每当你觉得某个技能描述写得不够精确，或者某个编排逻辑不够稳定，可以先在回归集上做实验对比，用数据说话，而不是靠“感觉上好像变聪明了”。
4. 实战中踩过的坑与排查思路
4.1 技能冲突：多个技能描述相似时模型乱选
这是技能库规模上来之后第一个踩到的坑。两个技能都涉及“查询订单”，但一个是查CRM里的订单，一个是查电商平台的订单。如果描述里没有做充分的边界区隔，模型在“帮我看看最近有没有新订单”这种请求面前，就会随机抽签选择。
排查这类问题，我的思路是不要只看模型最终选了哪个技能，而是要把模型在调用前的“思考过程”打出来。大多数Agent框架都支持打印中间推理步骤，从推理里能看到模型在两个技能之间的纠结。解决方案通常不是去改模型，而是改描述：
- 在触发条件里加明确的场景词：比如“CRM订单查询”描述里写“仅限内部销售系统”，“电商订单查询”里写“仅限天猫、京东等电商渠道”
- 在负面边界里互斥引用：明确写“本技能不处理来自电商平台的订单数据”
- 把高频混淆的请求高频词放进正确的技能描述里
实测效果来看，描述调整的作用远大于模型升级。很多时候你换一个大模型版本，这个问题并不会自动好转，但描述改清晰了，原来会冲突的模型版本也能表现得很稳定。
4.2 参数幻觉：模型填错参数类型和枚举值
参数幻觉是技能调用中另一个高发问题。模型明明看到了enum定义，还是会传一个不在枚举里的值；或者把日期格式从YYYY-MM-DD写成了YYYY/MM/DD。原因倒不是模型“故意犯错”，而是它在自由度较高的生成场景里，倾向于按照自己熟悉的语言习惯推断参数，而不是严格遵循schema约束。
常规解法有两个层次。第一层是前端的，也就是在系统提示或技能描述里强调严格按照参数定义取值。这个对部分模型有效，但不稳定。第二层是更实用的——在技能执行入口做参数编译和强制规范化，把“模型传参”看作“用户输入”，执行前先经过一层校验和转换：
- 枚举值：做模糊匹配，比如“华东区”和“华东”映射到同一个值
- 日期格式：统一解析后转成标准格式，防止格式混乱
- 缺失必填值：触发追问逻辑，而不是直接拿空值往下跑
我更喜欢在技能入口做一层“解析器中间层”，把模型的原始输出转成一个经过验证的执行指令。这样即使模型传的参数不太规范，底层的执行逻辑也不会被拖垮。这跟写接口时做入参清洗是同一个道理。
4.3 技能数量膨胀：几百个技能时如何保证检索效率
当技能库规模达到几百个时，把全部技能描述一次性塞进系统提示词已经不可行了，token消耗和语义干扰都会失控。这时候就必须引入技能检索机制，把“所有技能给模型看”改成“先把候选技能筛选到20个以内，再给模型挑”。
我遇到过最典型的现象是：技能数量在300个以上时，即使把所有技能名连同描述一起放进Prompt，模型的选择准确率反而更差。信息过载导致模型对早期位置的技能有偏好，而后面技能即便匹配度更高，也常常被忽略。解决这个问题没有捷径，只能靠检索。
具体做法上，我同时使用两路检索：
- 关键词倒排索引：基于技能名称和核心触发词，用BM25这类算法做词粒度匹配
- 向量语义检索：对description和trigger_examples做embedding，用余弦相似度召回候选技能
最终把两路结果做融合去重，再送去排序。我给每个技能预设了max_tokens预算，候选技能控制在5到20个，技能描述和参数schema才会拼进最终消息里。加了这层检索之后，模型在300多个技能的场景下命中准确率回到了95%以上，和几十个技能时的表现基本持平。
| 问题现象 | 根因分析 | 解决方式 |
|---|---|---|
| 多个技能描述相似时随机调用 | 触发语义边界不清晰 | 重写描述，加负面边界、场景词互斥 |
| 模型传入非法枚举值 | 参数约束不够严格 | 入口做参数编译和模糊映射 |
| 技能多了以后调用准确率下降 | 全量塞Prompt导致信息过载 | 引入关键词+向量双路检索，预筛候选技能 |
| 回归集用例频繁翻车 | 改技能描述没有回归验证 | 建立回归集，变更技能库时必跑 |
| 中间步骤失败难以定位 | 编排链路缺少观测 | 打印调用链日志，记录技能间产物 |
5. 再进阶一点：技能版本管理与效果观测
5.1 技能版本灰度发布：先小流量验证再全量
技能库上线之后，还有一个绕不开的问题：怎么安全地迭代。我见过很多团队改完技能描述直接发布，结果模型行为突变，线上用户立刻感知到“机器人变傻了”。这里缺的其实就是版本管理和灰度发布。
技能本质上是一种“代码”，但它的行为又受大模型的不确定性影响，所以比传统代码更需要灰度验证。我在项目里的做法是给每个技能增加version字段，同时用线上流量做A/B对比。比如新版本技能只放5%的流量进去，观察命中率、参数规范率和任务完成率，比起旧版更优才逐步放量。
顺带提一句版本兼容性的问题。技能的参数schema一旦上线，就成了其他技能和编排流程的依赖，改param字段要极其小心。我自己的原则是：可以新增可选参数，不轻易改已有必填参数含义，必须改时同步更新引用该技能的所有编排逻辑。
5.2 效果观测的三件套：命中率、中断率和用户反馈
很多团队上线了技能库，但不知道该怎么判断它到底做得好不好。我的经验是盯三个核心指标：
技能命中准确率指系统推送的技能列表里是否有正确技能，或者说模型最终调用的技能是否匹配用户意图。这个指标能反映描述质量和检索效果。
任务中断率指技能执行过程中发生异常、未正常返回结果的比例。这个指标能反映技能内部逻辑的健壮性，以及参数校验是否到位。
用户反馈修正率指用户对结果不满意、主动纠正或重发请求的比例。这个指标是最直接的体验晴雨表，它下降通常意味着技能库整体在变好。
这三个指标配合回归集一起看，就能形成一个比较完整的效果闭环。没有这些数据，你很难判断一次技能描述调整到底是优化还是退化。
6. 关于Agent Skills，几点实践心得
做到最后你会发现，Agent Skills的深层价值不在于“让模型学会调几个工具”，而在于它逼着你把模糊的业务需求拆解成清晰的、可验证的、可组合的单元。这件事本身就是Agent应用走向工程化的必经之路。
一个小经验分享给大家：技能描述的文字风格、缩写习惯、标点使用都要尽量保持一致。模型对格式混乱的内容理解起来更吃力，统一的风格能一定程度上降低它误判的概率。比如我在团队里定了规则：时间全部写中文日期格式、范围描述必须写清起始点和排除项、动词优先用“生成、查询、汇总、推送”等明确动作词，很少再用“处理”“操作”这种模糊词。
另外，技能库不是搭完就结束的东西。它在使用过程中要不断根据线上行为和用户反馈更新、迭代、治理。那些真正好用的Agent产品，背后的技能库永远处在活跃修改中。如果你刚起步，我建议不要一开始就上大而全的框架，先手工定义20个左右技能，跑通“注册、检索、调用、回归”这个最小闭环，再逐步扩大规模。这条路我走过，确实是最稳的方式。
