给Agent加技能这件事我最近刚好在一个内部项目里完整趟了一遍踩了不少坑也总结了一些可以复用的经验。今天就把“agent-skills”这套东西从头到尾拆开聊包括它到底解决什么问题、技能体系怎么设计、一个技能从写到上线要经过哪些环节以及几个你早晚会撞上的坑。如果你正在做AI Agent相关的开发或者刚接触LLM应用开发想知道除了写Prompt之外怎么让模型稳定“会干活”这篇文章应该能给你一套可以直接照抄的思路。我不会只贴概念会尽量落到目录结构、定义文件、注册逻辑和排查手段这些细节上。1. 先搞清楚Agent Skills 到底在解决什么问题1.1 从一次“教Agent干活”的失败经历说起大概半年前我在做一个偏企业内部的AI助手最开始的做法很朴素把各种操作说明写进系统提示词让模型按步骤执行。比如“查天气就调weather_api(query城市名)”“发邮件就调send_email(to, subject, body)”。试了两个星期效果一言难尽。模型经常在步骤之间自己发挥参数拼错、漏传、把两件事合并成一件做甚至偶尔会编一个完全不存在的接口出来。当时我就意识到问题不在于模型笨而在于我把“技能”和“指令”混为一谈了。指令是在特定上下文里给模型的一句吩咐而技能应该是可复用、有边界、有明确输入输出契约的能力单元。就好比你让一个新同事干活光跟他说“你帮我去处理一下那个客户的合同”是不够的你得先让他知道公司有哪些工具、每个工具的正确用法、边界在哪、出错找谁——agent-skills做的就是这件事。1.2 技能化思维把“一次性指令”变成“可复用能力”把技能和指令分开之后整个系统的稳定性上了两个台阶。技能化思维的核心就一句话把模型要执行的每一个动作都封装成有名字、有描述、有参数声明、有实现逻辑的独立模块而不是散落在提示词里的自然语言描述。这么做有几个显而易见的好处。第一是可复用一个“会议纪要整理”技能可以在周报生成、知识库归档、项目复盘等多个场景里被反复调用不需要每个场景重写一遍。第二是可测试技能是独立的函数单元可以单独写单元测试甚至可以离线跑通再接入Agent。第三是可治理谁写的技能、版本多少、依赖哪些权限、由谁审核都变成可管理的资产而不是一段“魔法咒语”。我当时把项目取名为agent-skills其实本地想强调的就是技能的目录化、标准化和流水线化。1.3 和工具调用、插件、MCP的关系很多人会问Agent Skills和Function Calling、Plugin、MCP到底什么关系我个人的理解是这样的Function Calling是一种模型交互机制解决的是“模型怎么输出一个调用请求”Plugin是产品形态解决的是“第三方能力怎么接入Agent”MCP是一套通信协议解决的是“不同工具之间怎么标准化互连”而Agent Skills是一个更上层的组织范式解决的是“一个Agent怎么管理自己会的一堆事情”。你可以把Agent Skills看作是在Function Calling之上加了一层“能力管理层”。Function Calling给的是一块黑板模型可以在上面写“我要调用foo函数参数是bar”Agent Skills则是把黑板分成了格子每个格子上贴着标签、说明书、注意事项和负责人。没有这层管理当技能数量超过20个甚至100个的时候模型选错工具的概率会指数级上升系统会变得不可维护。所以如果你只是玩票性质地接两三个APIFunction Calling直接写就够了。但如果你想正经做一个能持续迭代的AI产品技能层早晚要建赶早不赶晚。2. 设计一套技能体系前先把这几个核心定下来2.1 技能描述决定模型能不能正确挑选技能在Agent技能体系里最容易被低估也最影响效果的是技能的“描述”。很多团队写技能时把精力全放在实现逻辑上描述就随手来一句“查天气用的”结果模型到了现场一脸懵根本不知道应该在什么时候用这个技能。我总结的写法是这样的描述里必须包含“技能是做什么的、适合在什么场景使用、不适合在什么场景使用、使用后会产生什么副作用”。比如查天气技能好的描述不是“查询天气”而是“根据城市名查询实时天气和未来3天预报适合用户询问天气、出行准备、活动安排时使用不适合查询历史气候那是climate_skill的职责”。别嫌啰嗦模型就是靠这段文字做“技能路由”的你给的信息越准确它选错的概率就越低。另外我建议在描述里加上几条典型触发示例比如“用户说‘明天上海冷不冷’时优先使用本技能”。这比抽象描述管用得多因为模型对具体例子的理解能力远强于对抽象说教的理解能力。2.2 输入输出契约参数声明比实现代码更重要技能接口的参数声明是整个体系里最不能糊弄的部分。我见过有人把所有参数都塞进一个json字符串让模型自己解析这种做法在demo阶段看着挺灵活一上真实场景就崩——模型解析键名时经常大小写不一致少传参数也毫无感知。正确的做法是给每个参数定义清楚五件事参数名、类型、是否必填、默认值、取值范围或枚举。别小看这个“取值范围”它能帮你挡掉一大堆脏输入。比如状态筛选你声明只接受“open|closed|all”模型就不太会传一个“全部”进来。再比如日期参数明确要求ISO 8601格式YYYY-MM-DD并且注明“代表自然日不含时分秒”模型传错的概率就低很多。输入输出契约还要想清楚“技能被外界调用之后返回什么”。我强烈建议所有技能都返回统一的结构比如{ success: true, data: { ...: ... }, error: null, meta: { duration_ms: 120, source: cached } }这样无论模型在做什么任务它处理技能返回结果的方式都是一致的。你不会希望一个技能返回纯文本、另一个返回markdown、还有一个返回数组那会让后续的推理步骤变得非常脆弱。2.3 依赖与权限技能不是越强越好设计技能体系时权限和依赖一定要控制住。这点我在项目初期吃过亏图省事给实验性的“文件读取”技能开了整个服务器的读写权限结果模型在一次任务里把日志目录里的敏感内容读出来拼进了总结文档。虽然没造成实际事故但那次之后我意识到技能权限必须遵循最小化原则一个技能只能访问它完成任务所需的最少资源。具体到实操上我给每个技能都配了独立的权限声明。访问数据库的技能只能连业务库的只读账号操作文件系统的技能只能访问约定的工作目录调用外部API的技能必须走统一的网关不能私自配密钥。听起来像基础设施的事其实跟技能设计关系很大你在技能描述里承诺“安全可靠”结果底层权限一团糟等于自己扇自己脸。依赖方面也要显式声明。技能A依赖配置中心里的哪个配置项、依赖哪个内部服务的哪个版本、依赖Redis里哪个key的规范都写在技能的manifest文件里。这样技能迁移、复用、下线时都能自动检查依赖是否满足而不是等到运行期炸了才去翻日志。2.4 技能命名与粒度拆得越细越好吗技能命名有个很朴素的规则让模型一看名字就知道这个技能管什么、不管什么。比如“get_weather”比“weather”好“get_user_info_by_id”比“user”好因为后者太宽泛模型不敢确定调用它是否会带来额外副作用。技能粒度比命名更让人纠结。拆得太粗一个技能塞了十几种能力描述写得像论文模型容易困惑拆得太细“查用户姓名”“查用户手机号”各是一个技能技能数量爆炸选择成本和维护成本都上去了。我个人的经验是粒度划分看“领域模型”而不是“动作数量”同一个业务对象上的强相关操作可以合并成一个技能通过方法名区分跨领域、跨资源类型的动作必须拆开。拿用户模块举例。“根据ID查询用户信息”和“根据手机号查询用户信息”本质都是用户查询合并成一个user_query_skill参数里支持by_id和by_phone两种查询方式比两个独立技能更合理。但“更新用户资料”就必须单独一个user_update_skill因为它的副作用写入操作完全不一样模型需要非常明确地知道“这个调用会改数据”。3. 从零实现一个可落地的 Agent Skill3.1 目录结构一个技能就是一个自包含的包先说结论我最推荐的技能目录结构是这样的skills/ weather_skill/ SKILL.md manifest.json src/ __init__.py main.py tests/ test_weather.py assets/ examples.json核心原则是“一个技能就是一个自包含的包”——独立的功能、独立的测试、独立的文档、独立的版本。这样做的最大好处是技能可以脱离主项目独立开发和调试哪个技能出问题就单独修哪个不会牵一发动全身。SKILL.md是给人看的说明书写清楚技能背景、使用场景、代码结构、如何测试。manifest.json是给Agent和框架看的元数据包括技能ID、名称、版本号、描述、参数声明、依赖资源、权限要求等。src/下面是具体实现代码tests/放单元测试和端到端测试assets/可以放一些示例输入输出供模型或开发者快速理解这个技能的行为。我见过很多团队把技能实现直接写在Agent主项目的utils目录里一开始确实省事等技能多起来就疯了——你根本分不清哪个函数对应哪个技能模型排查问题需要一个一个去翻代码。3.2 技能定义文件怎么写的细节manifest.json是技能体系里最核心的文件之一我直接给一个简化但可用的例子{ id: weather_skill, name: 天气查询, version: 1.3.0, description: 根据城市名查询实时天气和未来3天预报适合用户询问天气、出行准备、活动安排时使用不适合查询历史气候。, examples: [ {query: 明天上海冷不冷, use: true}, {query: 这个月深圳下了多少雨, use: false, reason: 历史气候数据不属于本技能范围} ], params: [ { name: city, type: string, required: true, description: 城市中文名比如北京、上海不要带市字 }, { name: date, type: string, required: false, default: today, enum: [today, tomorrow, day3], description: 查询日期今天是today明天是tomorrow } ], output_schema: { type: object, properties: { temperature: {type: number}, condition: {type: string}, humidity: {type: number} } }, permissions: [network:weather_api], dependencies: [config:weather_api_key] }注意examples这个字段它写的是“什么样的用户问题应该触发本技能、什么样的问题不应该触发”对模型选技能的帮助极大。我强烈建议每个技能都配上5到10个正例和反例效果远超在description里反复强调“只用于XXX场景”。3.3 技能实现内部可以很粗糙接口必须干净技能的内部实现其实相对自由但暴露给Agent的入口必须干净。我通常是给每个技能定义两个入口一个同步的call方法供Agent框架调用一个describe方法返回技能的元信息。伪代码大概是这个样子class WeatherSkill(BaseSkill): def call(self, params: dict, context: dict) - dict: city params.get(city) date params.get(date, today) api_key context.get_secret(weather_api_key) # 调用外部天气API、解析结果、规范输出 ... return self.ok(data{temperature: 28, condition: 晴, humidity: 60}) def describe(self) - dict: # 返回manifest.json或者从manifest.json加载后的内容 return self.manifest内部逻辑哪怕写得糙一点问题都不大只要输出结构符合约定就行。我在实际开发中有个体会技能内部不要试图“帮模型思考”。很多人在实现技能时喜欢在返回结果里附带大段推理文字比如“根据我的经验明天可能会下雨”这种推理性内容会干扰Agent后续的自主推理导致它过度依赖技能的“判断”而不是基于事实数据做分析。所以我的建议是技能返回事实Agent负责推理。除非特殊情况技能不要输出建议和结论那是Agent该干的事。3.4 注册与加载让Agent在启动时发现技能技能写好了还要让Agent框架能发现并加载它。最简单的方式是“目录扫描注册法”在Agent启动时扫描skills/目录读取每个子目录下的manifest.json验证必填字段动态导入src/main.py里的技能类最后注册到技能路由表里。如果技能数量很大或者服务是分布式的建议把技能注册信息放到注册中心或者数据库里这样可以在不重启Agent的情况下动态增删技能。但我还是要提醒一句动态注册听着很美好实际操作中版本兼容性容易出问题。旧会话还在用v1.0的技能新会话已经加载v1.3了逻辑一旦有变化用户会明显感觉“同一个Agent前后行为不一致”。所以我在自己的项目里做了“标签冻结”机制Agent实例在创建时记录自己加载的技能版本快照会话期间一直使用这个快照不动态漂移。这样做牺牲了一点灵活性但换来了行为稳定性和可追溯性。对于做Agent产品的人来说稳定和可追溯远比“今天上线明天生效”更重要。3.5 链路验证从单测到端到端技能上线前至少要经过三层验证。第一层是单元测试直接实例化技能类喂各种正常和异常参数检查返回结构是否正确、边界条件是否处理。这一层不需要模型参与是最快能发现问题的地方。第二层是“模型选择测试”用一批典型的用户query去跑系统的技能路由模块检查模型是否选择了正确的技能。这一层不需要真的执行技能只需要校验选择的正确性。如果模型老选错技能大概率是description和examples写得不够清楚。第三层是端到端测试模拟真实的用户对话让Agent完整走一遍“理解意图→选择技能→调用实现→呈现结果”的链路。这层能暴露的是跨模块问题比如参数从用户文本中抽取时丢了字段、技能返回后被用户上下文策略截断了、结果渲染时没转成合适格式等。三层验证都跑通我才允许技能合并到主干分支。这套流程看着繁琐但能挡掉很多线上事故。毕竟技能是给模型直接调用的一旦接口设计有问题模型会以你意想不到的方式去调用它。4. 做技能编排时比写技能本身更重要的那些事4.1 多技能冲突模型到底该用哪个技能数量一多“该用哪个”就成了最头疼的问题。两个技能同时匹配用户意图的情况非常常见比如用户问“帮我把这个客户的信息整理成周报”同时命中“客户信息查询”和“周报生成”两个技能模型如果只选一个任务就完不成如果两个都选顺序怎么定又是一个问题。我建议在Agent框架里加一个“技能路由评分层”在模型自己选择之前先用规则做一次预筛选。预筛选的逻辑包括技能是否启用了、是否满足前置依赖、是否超出了执行环境的能力范围。预筛选之后再把候选技能列表连同它们的描述一起交给模型做最终决定。这样能明显减少模型“凭空想象一个技能”的概率。如果两个技能确实高度相似我一般处理的办法是要么合并成一个技能并在内部做分支逻辑要么在描述里互相写成互补关系明确写出“本技能只负责X如果要Y请用另一个”。模型的工具选择并不是只能靠调模型参数来优化工程师能做的结构调整和描述优化效果往往更大。4.2 顺序编排一个任务拆成多步技能真实业务里一个用户任务很少只调用一个技能。比如“帮我查下张三上周的考勤顺便总结一下迟到原因”至少要调两个技能“查询考勤数据”和“文本总结”。这两个技能之间有清晰的先后依赖前者输出是后者的输入。做顺序编排我有两个心得。第一尽量把依赖关系声明在技能描述里。比如“文本总结”技能的描述可以写上“当需要总结的数据来自其他技能时请先调用对应查询技能获得原始数据”。这句话模型是能听懂的关键是你得写出来。第二框架层面要做好“中间结果缓存”。两个技能的输入输出经常是同一份数据如果每个技能都从外部API重新拉一遍浪费时间和成本。我在框架里加了简单的内存缓存层同一个会话内技能的输出结果按“会话ID技能ID参数哈希”作为key缓存。数据敏感度不高的场景这么做很香能省掉大量重复请求。4.3 错误处理与降级技能失败不意味着任务失败技能运行失败不应该让整个Agent任务直接崩溃。我在设计错误处理时定了一条铁律技能的错误也要变成一种结构化数据而不是让异常一路往上抛。具体来说技能内部捕获到异常后应该返回一个包含错误码、错误信息、可选重试建议的结构由Agent框架统一决定下一步怎么做。举个例子天气API超时了技能不要直接抛TimeoutError而是返回{ success: false, error: { code: UPSTREAM_TIMEOUT, message: 天气API请求超时服务端无响应, retryable: true } }Agent框架看到retryable为true可以自动重试一次重试还不行就切换备用数据源没有备用源再向用户坦白“当前天气服务暂时不可用建议稍后再试”。整个降级路径是预先设计好并写在编排逻辑里的而不是临时让模型发挥。模型在异常处理的临场发挥说实话没人敢赌。4.4 技能评估怎么衡量一个技能好不好技能做完不是终点还要持续评估。“能用”和“好用”之间差距很大我主要看四个指标第一是调用准确率即用户意图与技能匹配的正确率。这个指标决定技能路由模型的质量数据可以从对话日志里抽样本人工标注也可以用LLM做辅助评测。第二是参数解析成功率和填充正确率。很多时候模型选对了技能但参数抽取出错任务照样完不成。第三是端到端成功率即从用户提问到最终结果呈现的全链路成功率这是用户真正感知到的指标。第四是平均延迟和成本即调用一个技能平均耗时多少毫秒、消耗多少token这决定了系统能不能跑得下去。定期把这四个指标纳入版本评审每次技能升级都拿旧版本做对比而不是只看“这次好像变聪明了”。能让技能体系稳定迭代而不是三天两头回退。5. 实战中踩过的坑和排查技巧实录5.1 模型总不调用你的技能这是我最常被问到的问题技能都写好了描述也写得挺详细但模型就是视而不见还是按自己的知识硬答。这个问题大概率不是模型的锅而是你的技能“曝光度”不够。技能路由在底层其实是“把技能描述拼进提示词让模型在候选列表里挑”如果你的技能排在列表第20位描述又有2000字模型很可能根本没读完就选了第一个技能。我的排查顺序是先看技能加载了没有再看技能描述是否被完整传给了模型然后精简描述控制在500字以内最后把正例examples放到描述前面。这四步能解决80%的“模型不调用技能”问题。剩下的20%可能是模型选技能的能力确实受限那就需要减少候选技能数量或者对技能做分类先把大类选出来再选具体技能。5.2 参数渲染与解析不一致参数问题是我踩坑最多的领域。最常见的是日期格式不一致技能要求“YYYY-MM-DD”用户说“明天”模型抽取后可能生成“2025-03-01”也可能生成“明天”还可能生成“下周一”。你没法保证模型每次都抽取得一模一样所以必须在技能入口做一层参数校验和标准化把“明天”这类自然语言先解析成具体日期。另一个高频问题是把字符串数组传成了JSON字符串。模型在生成参数时偶尔会把整个数组当作字符串塞进一个字段里如果技能实现端不校验类型就会拿到一个“看起来像数组其实是字符串”的脏数据。我建议所有技能入口都加上严格的schema校验不满足就直接返回参数错误让模型自己改正而不是在技能内部做兼容和容错。容错多了模型会越来越放肆。5.3 上下文被技能描述塞爆技能数量超过30个之后所有技能描述加起来可能轻松超过1万token直接挤占用户对话和历史记忆的空间。这时候的Agent会变得“健忘”——用户刚说的事情模型转头就忘因为它脑子里塞满了技能说明书。通用的解法是“分层技能路由”。先让模型在一个只有大类描述的“第一层路由表”里选择确定属于哪一类比如“查询类”“写入类”“生成类”再加载这个大类下具体技能的详细描述做第二次选择。两级结构能大幅降低每次提示词的技能描述长度让宝贵的上下文窗口用在真正重要的对话内容上。如果分层路由还不够就得考虑把技能描述编码成向量用检索的方式动态塞入最相关的技能。这相当于给Agent装了一个“技能搜索引擎”只在需要时加载。B端场景技能多且有明确边界这个方案尤其有效。5.4 技能升级后旧会话不生效技能升级了但用户开了很多旧会话每个会话里Agent还在用旧技能。这种“版本漂移”如果不处理轻则用户觉得改动没生效重则旧会话里技能逻辑与当前数据不再兼容。我前面提到过的“标签冻结”方案可以解决这件事这本质上是给每个会话打上技能版本快照运行期按快照执行。不过这种做法的代价是如果你修复了一个技能里的严重bug正在进行的旧会话还是会继续踩坑直到会话结束或手动干预。我的折中方案是小改动走快照不追平修复高危bug时强推版本允许旧会话自动升级到新版本并给出提示。这样安全性和灵活性之间能取得一个相对合理的平衡。5.5 热更新与灰度发布的个人做法最后聊一下技能的热更新和灰度。我现在用的是“技能版本流量切分”的做法一个技能可以同时部署多个版本线上流量按比例切分到不同版本上比如v1.3占90%、v1.4占10%持续观察端到端成功率和延迟指标确认没问题再把流量逐步切到新版本上。这个方案其实不复杂核心是技能的调用入口要统一走一层“版本路由”不要让业务代码直接import具体的技能类。所有技能调用都经过框架的SkillRegistryRegistry根据配置决定把请求分发到哪个版本。做来做去你会发现给Agent做技能管理跟给微服务做API版本管理面对的很多问题是一样的思路完全可以借鉴。还有一点是关于技能下线的很多时候不是技能写得不好而是用完该下线了。下线前先看调用日志确认近30天没有真实调用然后停用路由再保留代码仓库一段时间备查最后才真正删除。整个过程要留痕否则哪天审计来查“这个技能为什么访问过敏感数据”你说不清。我在实际操练agent-skills这套体系的过程中最大的体会是Agent能不能稳定干活拼的不是模型有多聪明而是底层的工具、技能、规范有多扎实。技能描述多写几句、参数校验多写一层、错误处理多想一条线上事故就会少很多。这个项目到现在还在持续迭代目前技能数量已经上百靠的并不是某一次“聪明”的设计而是把技能当作正经软件资产来管理一点一点积累出来的。