1. 从工具调用到技能抽象agent-skills 解决的真实痛点做 AI Agent 开发做到一定程度很多人都会撞上一堵墙功能好像都有但 Agent 就是不会干活。功能都有但 Agent 就是不会干活。你在代码里定义了几十个 function把它们的 name、description、parameters 一股脑塞给模型模型也确实能按格式调用。可真当一个任务需要连续操作文件、查询数据库、再调用外部 API 时各种问题就全冒出来了。工具描述写得越细提示词越长模型的选择就越不稳定工具之间隐式的依赖关系全靠人工在 system prompt 里维护改一个字段就要全局排查。我去年维护的一个 Agent 项目就是这样工具函数从 12 个涨到 40 个之后单次任务的平均 API 调用量翻了将近三倍成功率反而降了约两成。agent-skills 这个概念正是冲着这个问题来的。它的核心思路是不要继续在函数调用的粒度上组织 Agent 的能力而是把能力提升到技能的粒度。一个技能不是单纯的执行某个函数而是完成一件有明确目标的事情所需要的完整行为模板——包括该做什么、不该做什么、用什么工具、按什么顺序、出错了怎么处理。说得直白点工具调用是让 Agent 学会伸手技能系统是让 Agent 学会做动作。这两者的差异决定了 Agent 只能处理单步请求还是能自主完成一个多步骤的交付任务。这篇文章基于我在几个实际项目里落地 agent-skills 设计模式的经验整理而成适合正在纠结为什么我的 Agent 有工具却很蠢的开发者也适合想从零搭一套可插拔 Agent 能力的架构师。我会先讲清楚技能抽象背后到底改变了什么再给出技能文件的定义规范、注册加载机制、编排执行链路最后分享我在真实场景里踩过的三个比较深的坑以及一套完整的最小可行落地方案。先说清楚一个容易混淆的概念技能skill和工具tool到底有什么区别。工具是最小可执行单元通常对应一个函数或 API输入输出都是结构化参数本身不包含决策逻辑。技能则是带决策逻辑的工作流模板它可能封装了多个工具的调用顺序、前置条件、备选路径和终止条件。举个具体的例子单个查天气API 是工具而根据城市名规划周末出行方案这个能力就是技能——它内部会先查天气、再查交通、再结合时间段做推荐三个步骤之间有依赖关系需要按序执行、异常回退。用函数调用去硬编码这套逻辑会非常痛苦但用技能声明来描述就自然得多。另一个背景是 2024 年后各大 Agent 框架加速推动的Skills概念落地。这套模式逐渐形成几个共识性的组成部分技能的声明式描述文件通常叫 SKILL.md 或类似格式、技能的注册与发现机制、技能的选择策略以及技能执行时的失败恢复策略。下面几个章节我会逐一拆开讲并附上可以直接拿来改的代码和配置。2. 技能的核心载体SKILL.md 声明式描述与注册机制2.1 为什么需要一份技能说明书我在最开始的设计里走过一段弯路把技能直接写成 Python 类每个技能一个类类的 docstring 里写描述方法里写调用逻辑。这样做的第一个问题是Agent 的大模型只能看到 model 层面的文本描述它不认识你的 Python 类结构所以你必须把所有关键信息转成文本喂给模型——那就等于又回到堆提示词的老路了。第二个问题是技能之间相互引用的元信息比如这个技能依赖上一个技能的输出格式散落在代码里根本无法做静态分析和动态编排。现在更成熟的做法是把技能文件拆成两个部分一份人类可读、模型可读的声明文件以及一份可执行代码。声明文件通常采用 Markdown 格式核心字段包括技能的 name、description、when_to_use、dependencies、main_workflow、fallback 等。我见过不少团队一开始觉得这个文件多余直接只在代码层写注释。但实测下来声明文件有两个不可替代的作用第一它是模型做技能选择时的唯一事实来源模型不需要理解代码只需要能读懂这份说明就能判断当前任务该不该调用这个技能第二它可以独立做校验、版本管理和热加载不需要重新部署 Agent 主进程。这里直接给出一份我实际项目里用过的 SKILL.md 模板字段不多但每个字段在模型决策链路里都有明确用途--- name: weekly_report_generator description: 根据项目工作日志生成周报支持按团队过滤、统计工时、输出 Markdown 或 Excel 格式。 when_to_use: 当用户要求生成周报、汇总近期工作内容、统计团队产出的场景。 dependencies: - skill: project_log_reader version: 1.2 - tool: excel_exporter version: ^2.0 main_workflow: - step: 读取指定时间范围内的项目日志 use: project_log_reader - step: 按团队成员分组并统计工时 use: internal_calculator - step: 按目标格式输出报告 use: [markdown_renderer, excel_exporter] fallback: - when: 项目日志接口超时 then: 尝试读取本地缓存目录中的最近一次日志备份 - when: 报告格式参数冲突 then: 默认输出 Markdown 格式并提示用户手动选择 ---注意 description 和 when_to_use 这两个字段它们直接决定了模型会不会选错技能。我见过太多团队把 description 写成了该技能用于生成周报这种泛泛描述结果遇到帮我总结一下这周干了啥这种请求时模型举棋不定在多个技能之间反复试探。好的描述应该写输入需要什么、输出是什么、处理的大致过程而 when_to_use 要写清楚触发场景甚至可以加反例比如不要在会议记录整理场景使用那是 meeting_minutes_sumarizer 的职责。2.2 注册表与动态发现如何让 Agent 知道自己会什么有了技能文件下一步是把它们注册到一个 Agent 能感知的地方。这里有两种主流路线静态注册和动态发现。静态注册就是在启动时把所有技能文件路径写进配置动态发现则是让 Agent 在运行时扫描指定目录读取每个 SKILL.md 的元数据构建一个技能索引列表。我强烈建议走动态发现原因很实际技能文件会越来越多你不可能每次加一个技能都要改主配置然后重启服务动态扫描目录的方式让新增技能的成本几乎为零。我的做法是建一个 skills/ 目录每个子目录放一个技能结构大概是这样的skills/ weekly_report_generator/ SKILL.md main.py requirements.txt project_log_reader/ SKILL.md main.py excel_exporter/ SKILL.md exporter.py启动时写一个简单的 SkillRegistry扫描目录、解析 SKILL.md 的 frontmatter、构建技能清单。这个清单实际是一段增强后的文本会被拼接进 Agent 的 system prompt 里。这里要特别注意控制清单的长度技能数量超过 20 个时全量拼接会让模型输入 token 快速膨胀选择准确率反而下降。实测下来更合理的做法是对技能描述做编码向量化在每次请求到来时先做一次 embedding 相似度检索只把 top-k比如 5 到 8 个候选技能描述注入上下文。这套检索式技能召回是后面选择准确率稳定在 90% 以上的关键。下面是一段简化版的注册与召回代码用的库是开源的只有核心逻辑示意# skill_registry.py from pathlib import Path import yaml import re class SkillRegistry: def __init__(self, skills_root: Path): self.skills_root skills_root self._skills [] def scan(self): for skill_dir in self.skills_root.iterdir(): skill_md skill_dir / SKILL.md if not skill_md.exists(): continue content skill_md.read_text(encodingutf-8) meta self._parse_frontmatter(content) meta[path] str(skill_dir) self._skills.append(meta) return self def _parse_frontmatter(self, content: str): match re.match(r^---\n(.*?)\n---, content, re.DOTALL) if not match: raise ValueError(SKILL.md 缺少 frontmatter 元数据块) return yaml.safe_load(match.group(1)) def list_descriptions(self): return [f技能名: {s[name]}\n描述: {s[description]}\n适用场景: {s[when_to_use]} for s in self._skills]召回侧我用的是 sentence-transformers 里的一个轻量模型做向量化存储直接扔进内存列表就够用不用上向量数据库因为技能数量通常不会超过几百个。每次请求的流程是先对用户输入做 embedding然后和所有技能描述的 embedding 算余弦相似度取最高的前几个作为候选再把候选的完整描述注入 system prompt。这个过程的延迟大约在几十毫秒相对模型调用来说完全可以忽略。2.3 技能描述的质量控制清单技能描述是整条链路上唯一同时影响选择准确性和执行正确性的文本我把自己的检查清单列在这里每一条都是从失败案例里反向总结出来的description 里必须写清楚输入要求和输出格式例如输入是项目 ID 列表输出是 JSON 数组每个元素包含项目名、负责人和本周工时总和。when_to_use 要写触发场景和反例宁可啰嗦不要含混我见过的最好的写法是列三个正例加一个反例。dependencies 字段里引用的技能和工具要标注版本范围否则技能升级后可能出现接口不兼容导致执行中报错。main_workflow 里每一步都要标注 use 的目标技能或工具这不仅是给模型看的执行计划也是后面编排引擎做依赖解析的依据。fallback 必须写什么情况触发 替换方案是什么的二元结构缺失 fallback 的技能相当于没有保险丝一出错整条任务就崩。提示如果你看到模型频繁调用一个技能但执行结果不对十有八九是 description 里没写清楚输入要求模型以为它会把完整数据传进去实际上技能要的是结构化参数。先把 description 里的输入输出规范写死再调参数不要急着改模型温度或换大模型。3. 技能编排与执行链路一个任务如何被拆成一组技能3.1 技能选择的决策路径模型自主选 vs 规则路由技能系统跑起来之后第一个要回答的问题是某个任务来了到底由谁决定调用哪个技能我见过两种极端方案一边是完全交给模型自由选择一边是完全用 if-else 规则硬编码。两种我都试过都有明显问题。完全交给模型的问题是模型对技能的适用边界判断并不稳定尤其在技能描述相似度高时模型经常挑错技能。举例来说我定义了一个深度内容总结技能和一个要点提取技能两者 description 都涉及总结结果模型遇到一批需要逐条概括并保留逻辑关系的文档时选到了只输出 bullet list 的要点提取产出质量完全不对。后来我加了 when_to_use 反例描述情况好一些但依然有差不多 8% 的选择错误率。在任务失败会带来明显成本的生产环境这个概率还是偏高。完全规则路由的方案则走向另一个极端。规则一旦写多很快退化成每个技能一个 if技能之间的组合逻辑根本表达不出来。比如先读日志再生成周报这个流程用规则你得专门写一个周报任务分支里面再套子分支。如果将来加了读日志生成日报呢读日志写汇报邮件呢每多一种组合就要写一条规则代码很快就膨胀到不可维护这恰恰是当初用技能抽象想解决的问题。现在验证下来比较稳的折中方案是场景分类器 技能候选召回 模型最终选择三层决策。第一层用一个轻量分类器或者一个规则优先的粗筛把请求归到几个大类比如报告生成类数据查询类内容处理类;第二层在各类型对应的技能池里做 embedding 召回 top-k第三层才把候选技能描述交给大模型做最终选择。这样的好处是模型面对的不是几十个技能而只有几个选择空间变小准确率会明显提升。我在某个内部工具上做了对比实验只用模型自由选择时准确率是 82%加了两层预筛后提升到 94%误调用的概率下降了接近 60%。3.2 技能执行时的上下文管理跑起来才知道的组合问题选对技能只是第一步。技能真正执行起来比选错更常见的问题是两个技能之间的数据传递。在纯函数调用时代上一个函数的返回值直接作为下一个函数的输入这个链路是显式写死的。但技能执行时模型会根据实际情况调整执行顺序甚至跳过某一步这时候如果上下文里的数据结构对不上整个链路就崩了。给你看一个我踩过的真实案例。我的周报生成技能第一步依赖项目日志读取技能的输出日志读取技能返回的是一组记录对象字段是{project: 支付中台, hours: 6.5, detail: 完成了退款链路压测}。而周报技能内部写死了要读取字段log_items数组里面每个元素只有title和time_consumed两个字段。两边对不上执行到中间步骤就报 KeyError。这个问题的根源不是代码而是两个技能由不同开发者编写双方的数据契约没有对齐。解决这个问题我现在的做法是在 SKILL.md 里强制增加一个output_schema字段并且在注册时做静态校验凡是main_workflow里声明dependencies的技能启动时必须校验上游技能的output_schema和本技能的输入字段能否匹配。校验逻辑不复杂本质上就是 JSON Schema 的兼容性检查。这个约束条件带来的收益非常大它把运行时才暴露的接口不匹配问题提前到了启动时一次部署前就能发现五六个隐患。我建议任何技能数量超过三个的项目都必须把这一步纳入 CI 流程。# schema_validation.py 片段 from jsonschema import Draft7Validator def validate_dependency(skill_meta, registry): for dep in skill_meta.get(dependencies, []): upstream registry.get_skill(dep[skill]) if upstream is None: raise RuntimeError(f依赖技能 {dep[skill]} 不存在) upstream_schema upstream.get(output_schema) local_input_schema skill_meta.get(input_schema) # 校验本地输入是否是上游输出的子集这里简化成非空校验 if not upstream_schema or not local_input_schema: raise RuntimeError(f技能 {skill_meta[name]} 与 {upstream[name]} 缺少 schema)除了静态契约运行时还需要一个技能执行上下文对象本质是一个类似 dict 的容器记录每一步输出了什么、存在哪个 key 下并且支持嵌套读取。我会在所有技能代码里统一用ctx.get($last_output)和ctx.set(report_data, data)这样的方式做数据传递代替直接写 Python 变量名。这样技能与技能之间唯一的耦合点就是上下文 key而不是具体的数据类后续替换某个技能时只需要对齐 key 就能接入新实现不需要改其他技能的代码。3.3 失败恢复策略为什么 fallback 比重试更可靠技能执行不可能每次都顺顺利利。API 超时、上游返回空数据、参数校验失败这类错误在生产里经常出现。很多人的第一反应是给整个链路加重试执行失败就再来一次。我的经验是无差别重试是性价比最低的方案因为很多失败是确定性的——比如输入数据格式不对重试一万次还是不对。你要做的是把失败分类然后分别设计恢复策略。我按可重试和不可重试把常见故障分成三类第一类是瞬时故障比如网络超时、服务端 503这类可以自动重试但重试次数要限到两次以内且第二次和第三次之间要有指数退避第二类是数据问题例如上游返回了空列表或者字段缺失这类重试没有意义应该直接触发 fallback 逻辑例如读取缓存或换一个上游数据源第三类是技能逻辑内部抛出的业务异常比如参数冲突、依赖文件不存在这类需要把错误信息结构化地返回给模型让模型决定是换一个技能还是直接面向用户说明失败原因。我强烈建议在 SKILL.md 的 fallback 字段里把这些策略写清楚而不是把恢复逻辑全写进代码。因为模型在执行链路中是需要了解 fallback 信息的它得知道如果第一步失败了接下来是继续还是终止才能做出正确的下一步决策。拿生成周报这个技能来说fallback 写明日志接口超时则读取本地缓存目录 /data/log_cache 下的最近文件模型在第二步执行时发现日志读取失败就能自主去尝试缓存路径而不是傻傻地把同样的请求重新发给接口。4. 实测中躲不开的三个坑命名冲突、描述冗长与失败恢复4.1 命名冲突与版本漂移技能多了之后必然遇到技能系统最容易被低估的问题就是命名空间。搜索这个技能可能在内容团队的项目里叫web_search在数据团队的项目里叫data_search。两个技能如果同时注册进同一个 Agent模型在选择时会非常困惑因为它们的 description 可能都写了搜索相关资料。我在一个多团队共建的 Agent 平台上就吃过这个亏两个技能的名字和描述高度相似结果模型总选错导致搜索结果完全不是用户想要的。解决办法是建立统一的技能命名规范强制带上领域前缀比如内容类叫content_search数据类叫data_query_search同时要求 description 的第一句就写明领域和边界。这个规范要写进团队的技术文档并且做成注册时的强校验名字必须匹配^[a-z](_[a-z])*$且不允许和已注册技能同名。第二步是在注册表里加一个别名冲突检测扫描新注册技能的 description 和已有技能的 description 的文本相似度超过阈值就报警提醒人工确认。版本漂移是另一个容易踩的坑。技能升级后老技能的调用方可能还按旧版的输入格式传参数导致运行时报错。我遇到过最严重的一次是日志读取技能升级了输出字段从project_name改成了project结果下游七个技能里有两个没同步更新线上任务直接失败。现在我的做法有两个一是所有技能注册都必须带版本号并且在 SKILL.md 里用version字段声明二是提供兼容层机制技能升级后保留一段时间的旧输出别名例如输出对象里同时写project_name和project等所有下游完成后才删掉旧字段。虽然有点笨但稳定压倒一切。4.2 技能描述过长导致的选择偏差开头我提到了提示词变长会导致模型选择不稳定这里展开讲一个反直觉的现象。我给项目风险识别技能写过一个特别详细的描述把每一步逻辑、每个判断规则、每个输出字段都写了进去想着这样模型一定最清楚什么时候用它。结果是其他技能的选择率整体下降而这个技能无论面对什么任务都容易被选中。后来分析才知道描述过长会让模型产生这个技能内容最丰富、最可靠的错觉本质上类似注意力机制里长文本会占据更多权重。解决这个问题分两步第一把技能的选择描述和执行细节分离。选择描述只保留简短的 name、description、when_to_use、dependencies 和 main_workflow 的步骤概览强制控制在 800 字以内我实际验证的阈值超过 1000 字准确率会明显下滑。执行细节挪进技能代码里的注释或专门的 docs 文件只在执行阶段由执行引擎加载不进入模型的选择上下文。第二在描述里专门加一个排除性提示明确写此技能不适用于哪些场景。这看似矛盾但实测能把误选率降低一半以上。核心逻辑是给模型一个边界感它才知道什么时候不该用这个技能而该用技能本身的效果是让 Agent 从撒网式尝试变成脚手架式执行。4.3 失败恢复的静默失败陷阱我在真实场景里调试过很多次 Agent 任务的失败发现最危险的不是报错失败而是静默失败——进程没有报错任务状态被标记为完成但产出内容根本不对。最典型的一种是日志读取技能在数据源没有匹配记录时返回了一个空列表周报生成技能拿到空列表后没有报错而是直接生成了一份本周无工作内容的周报。对于用户来说这个结果是荒谬的但系统层面所有状态码都是成功的。这个问题暴露之后我才意识到失败恢复策略里最容易被忽视的一点你必须给预期为空和非预期为空设置明确的判定标准。现在我的技能模板里强制加入了一个empty_output_policy字段写明哪些输出字段允许为空、哪些必须非空以及为空时要执行什么动作——是跳过、填充默认值还是整体中断并通知用户。周报生成技能的配置就写了log_items 为空时报错并在回复里提示用户未找到任何日志记录请检查时间范围或数据源。这个字段不会进入选择描述只在执行阶段被读取但它保证了链路不会在用户不知情的情况下产出垃圾结果。我建议所有从外部数据源读取数据后再做加工的技能都必须配置这个策略宁可失败得大声也不要错误得安静。5. 从零搭建最小可用技能系统的完整方案5.1 最小可用技能集怎么定先走通端到端再横向扩展搭建 agent-skills 的第一个项目最容易犯的错误是贪多。我见过一个团队第一天就定义了十六个技能结果一周过去没有一个跑通了端到端流程。我自己的经验是初始技能集不要超过三个而且这三个必须能串成一个完整的业务闭环。举例来说如果你想要一个自动生成周报的 Agent最小技能集就是三个项目日志读取、工时统计/汇总、报告渲染。这三个技能一条链路走通你才算真正掌握了技能系统的注册、选择、编排、恢复整套机制之后再加技能都是顺水推舟的事。技能目录和代码骨架我建议用下面这个最小结构起步agent_project/ skills/ project_log_reader/ SKILL.md main.py summary_calculator/ SKILL.md main.py report_renderer/ SKILL.md main.py registry.py orchestrator.py main.pymain.py 里就是最精简的 Agent 主循环接收请求 - 召回技能 - 模型做选择 - 按工作流执行技能 - 返回结果。把这条主链跑通之后再考虑加缓存、加审计日志、加技能热更新这些外围能力。不要本末倒置——技能系统最核心的价值是结构的确定性这个确定性在你只有三个技能时就能充分体现。5.2 测试与评估怎么知道一套技能真的可用很多人对技能系统的测试止步于每个技能单独跑一次看看能不能返回结果。这远远不够。技能系统真正的风险在组合不在单体所以评估的重心要放在链路上。我常用的方法是建一组端到端的黄金用例集每个用例包含一段用户请求、期望调用的技能序列、期望的输出结构。每次改动技能或配置后跑一遍黄金用例集统计三个指标选择准确率模型选对了技能吗、执行成功率技能跑通了吗、结构符合率输出 schema 和期望的对得上吗。这三个指标里我要特别提醒结构符合率的重要性。技能系统的输出如果每次都长不一样下游的对接成本会持续高涨。我在自己的项目里把输出比作快递单无论搬运的包裹内容怎么变单子上的收件人、地址、电话字段必须永远不变。所以每个技能的核心输出都用 Pydantic 模型或 dataclass 定义死并且单独写 schema 测试任何字段变更都必须显式改版本号不允许无声无息地改结构。另外要给技能系统加日志可观测性。每个技能执行时要把选择了哪个技能、输入了什么、输出了什么、耗时多少、有没有走 fallback都记录下来存成结构化日志。这不是可有可无的运维功能而是技能调优的数据基础。我最初发现模型总选错技能就是靠日志发现某些请求普遍倾向于命中同一个技能再结合具体输入分析才定位到是描述边界不清。没有日志这类问题只能靠用户投诉才知道代价差太多了。最后聊一个容易被忽视的性价比问题技能描述质量的提升对选择准确率的影响远大于换一个更大的模型。我在同一套技能系统上做过对比用原来的小参数模型配合优化后的技能描述和三层决策链路任务成功率比裸用大参数模型还高出一截。所以投入精力的优先级应该是先固化技能描述规范再做召回优化最后才是升级模型。这个顺序反了你会花大价钱买来更聪明的模型却依然喂给它一堆模糊不清的技能清单结果只是把错误犯得更快。
1. 从工具调用到技能抽象agent-skills 解决的真实痛点做 AI Agent 开发做到一定程度很多人都会撞上一堵墙功能好像都有但 Agent 就是不会干活。功能都有但 Agent 就是不会干活。你在代码里定义了几十个 function把它们的 name、description、parameters 一股脑塞给模型模型也确实能按格式调用。可真当一个任务需要连续操作文件、查询数据库、再调用外部 API 时各种问题就全冒出来了。工具描述写得越细提示词越长模型的选择就越不稳定工具之间隐式的依赖关系全靠人工在 system prompt 里维护改一个字段就要全局排查。我去年维护的一个 Agent 项目就是这样工具函数从 12 个涨到 40 个之后单次任务的平均 API 调用量翻了将近三倍成功率反而降了约两成。agent-skills 这个概念正是冲着这个问题来的。它的核心思路是不要继续在函数调用的粒度上组织 Agent 的能力而是把能力提升到技能的粒度。一个技能不是单纯的执行某个函数而是完成一件有明确目标的事情所需要的完整行为模板——包括该做什么、不该做什么、用什么工具、按什么顺序、出错了怎么处理。说得直白点工具调用是让 Agent 学会伸手技能系统是让 Agent 学会做动作。这两者的差异决定了 Agent 只能处理单步请求还是能自主完成一个多步骤的交付任务。这篇文章基于我在几个实际项目里落地 agent-skills 设计模式的经验整理而成适合正在纠结为什么我的 Agent 有工具却很蠢的开发者也适合想从零搭一套可插拔 Agent 能力的架构师。我会先讲清楚技能抽象背后到底改变了什么再给出技能文件的定义规范、注册加载机制、编排执行链路最后分享我在真实场景里踩过的三个比较深的坑以及一套完整的最小可行落地方案。先说清楚一个容易混淆的概念技能skill和工具tool到底有什么区别。工具是最小可执行单元通常对应一个函数或 API输入输出都是结构化参数本身不包含决策逻辑。技能则是带决策逻辑的工作流模板它可能封装了多个工具的调用顺序、前置条件、备选路径和终止条件。举个具体的例子单个查天气API 是工具而根据城市名规划周末出行方案这个能力就是技能——它内部会先查天气、再查交通、再结合时间段做推荐三个步骤之间有依赖关系需要按序执行、异常回退。用函数调用去硬编码这套逻辑会非常痛苦但用技能声明来描述就自然得多。另一个背景是 2024 年后各大 Agent 框架加速推动的Skills概念落地。这套模式逐渐形成几个共识性的组成部分技能的声明式描述文件通常叫 SKILL.md 或类似格式、技能的注册与发现机制、技能的选择策略以及技能执行时的失败恢复策略。下面几个章节我会逐一拆开讲并附上可以直接拿来改的代码和配置。2. 技能的核心载体SKILL.md 声明式描述与注册机制2.1 为什么需要一份技能说明书我在最开始的设计里走过一段弯路把技能直接写成 Python 类每个技能一个类类的 docstring 里写描述方法里写调用逻辑。这样做的第一个问题是Agent 的大模型只能看到 model 层面的文本描述它不认识你的 Python 类结构所以你必须把所有关键信息转成文本喂给模型——那就等于又回到堆提示词的老路了。第二个问题是技能之间相互引用的元信息比如这个技能依赖上一个技能的输出格式散落在代码里根本无法做静态分析和动态编排。现在更成熟的做法是把技能文件拆成两个部分一份人类可读、模型可读的声明文件以及一份可执行代码。声明文件通常采用 Markdown 格式核心字段包括技能的 name、description、when_to_use、dependencies、main_workflow、fallback 等。我见过不少团队一开始觉得这个文件多余直接只在代码层写注释。但实测下来声明文件有两个不可替代的作用第一它是模型做技能选择时的唯一事实来源模型不需要理解代码只需要能读懂这份说明就能判断当前任务该不该调用这个技能第二它可以独立做校验、版本管理和热加载不需要重新部署 Agent 主进程。这里直接给出一份我实际项目里用过的 SKILL.md 模板字段不多但每个字段在模型决策链路里都有明确用途--- name: weekly_report_generator description: 根据项目工作日志生成周报支持按团队过滤、统计工时、输出 Markdown 或 Excel 格式。 when_to_use: 当用户要求生成周报、汇总近期工作内容、统计团队产出的场景。 dependencies: - skill: project_log_reader version: 1.2 - tool: excel_exporter version: ^2.0 main_workflow: - step: 读取指定时间范围内的项目日志 use: project_log_reader - step: 按团队成员分组并统计工时 use: internal_calculator - step: 按目标格式输出报告 use: [markdown_renderer, excel_exporter] fallback: - when: 项目日志接口超时 then: 尝试读取本地缓存目录中的最近一次日志备份 - when: 报告格式参数冲突 then: 默认输出 Markdown 格式并提示用户手动选择 ---注意 description 和 when_to_use 这两个字段它们直接决定了模型会不会选错技能。我见过太多团队把 description 写成了该技能用于生成周报这种泛泛描述结果遇到帮我总结一下这周干了啥这种请求时模型举棋不定在多个技能之间反复试探。好的描述应该写输入需要什么、输出是什么、处理的大致过程而 when_to_use 要写清楚触发场景甚至可以加反例比如不要在会议记录整理场景使用那是 meeting_minutes_sumarizer 的职责。2.2 注册表与动态发现如何让 Agent 知道自己会什么有了技能文件下一步是把它们注册到一个 Agent 能感知的地方。这里有两种主流路线静态注册和动态发现。静态注册就是在启动时把所有技能文件路径写进配置动态发现则是让 Agent 在运行时扫描指定目录读取每个 SKILL.md 的元数据构建一个技能索引列表。我强烈建议走动态发现原因很实际技能文件会越来越多你不可能每次加一个技能都要改主配置然后重启服务动态扫描目录的方式让新增技能的成本几乎为零。我的做法是建一个 skills/ 目录每个子目录放一个技能结构大概是这样的skills/ weekly_report_generator/ SKILL.md main.py requirements.txt project_log_reader/ SKILL.md main.py excel_exporter/ SKILL.md exporter.py启动时写一个简单的 SkillRegistry扫描目录、解析 SKILL.md 的 frontmatter、构建技能清单。这个清单实际是一段增强后的文本会被拼接进 Agent 的 system prompt 里。这里要特别注意控制清单的长度技能数量超过 20 个时全量拼接会让模型输入 token 快速膨胀选择准确率反而下降。实测下来更合理的做法是对技能描述做编码向量化在每次请求到来时先做一次 embedding 相似度检索只把 top-k比如 5 到 8 个候选技能描述注入上下文。这套检索式技能召回是后面选择准确率稳定在 90% 以上的关键。下面是一段简化版的注册与召回代码用的库是开源的只有核心逻辑示意# skill_registry.py from pathlib import Path import yaml import re class SkillRegistry: def __init__(self, skills_root: Path): self.skills_root skills_root self._skills [] def scan(self): for skill_dir in self.skills_root.iterdir(): skill_md skill_dir / SKILL.md if not skill_md.exists(): continue content skill_md.read_text(encodingutf-8) meta self._parse_frontmatter(content) meta[path] str(skill_dir) self._skills.append(meta) return self def _parse_frontmatter(self, content: str): match re.match(r^---\n(.*?)\n---, content, re.DOTALL) if not match: raise ValueError(SKILL.md 缺少 frontmatter 元数据块) return yaml.safe_load(match.group(1)) def list_descriptions(self): return [f技能名: {s[name]}\n描述: {s[description]}\n适用场景: {s[when_to_use]} for s in self._skills]召回侧我用的是 sentence-transformers 里的一个轻量模型做向量化存储直接扔进内存列表就够用不用上向量数据库因为技能数量通常不会超过几百个。每次请求的流程是先对用户输入做 embedding然后和所有技能描述的 embedding 算余弦相似度取最高的前几个作为候选再把候选的完整描述注入 system prompt。这个过程的延迟大约在几十毫秒相对模型调用来说完全可以忽略。2.3 技能描述的质量控制清单技能描述是整条链路上唯一同时影响选择准确性和执行正确性的文本我把自己的检查清单列在这里每一条都是从失败案例里反向总结出来的description 里必须写清楚输入要求和输出格式例如输入是项目 ID 列表输出是 JSON 数组每个元素包含项目名、负责人和本周工时总和。when_to_use 要写触发场景和反例宁可啰嗦不要含混我见过的最好的写法是列三个正例加一个反例。dependencies 字段里引用的技能和工具要标注版本范围否则技能升级后可能出现接口不兼容导致执行中报错。main_workflow 里每一步都要标注 use 的目标技能或工具这不仅是给模型看的执行计划也是后面编排引擎做依赖解析的依据。fallback 必须写什么情况触发 替换方案是什么的二元结构缺失 fallback 的技能相当于没有保险丝一出错整条任务就崩。提示如果你看到模型频繁调用一个技能但执行结果不对十有八九是 description 里没写清楚输入要求模型以为它会把完整数据传进去实际上技能要的是结构化参数。先把 description 里的输入输出规范写死再调参数不要急着改模型温度或换大模型。3. 技能编排与执行链路一个任务如何被拆成一组技能3.1 技能选择的决策路径模型自主选 vs 规则路由技能系统跑起来之后第一个要回答的问题是某个任务来了到底由谁决定调用哪个技能我见过两种极端方案一边是完全交给模型自由选择一边是完全用 if-else 规则硬编码。两种我都试过都有明显问题。完全交给模型的问题是模型对技能的适用边界判断并不稳定尤其在技能描述相似度高时模型经常挑错技能。举例来说我定义了一个深度内容总结技能和一个要点提取技能两者 description 都涉及总结结果模型遇到一批需要逐条概括并保留逻辑关系的文档时选到了只输出 bullet list 的要点提取产出质量完全不对。后来我加了 when_to_use 反例描述情况好一些但依然有差不多 8% 的选择错误率。在任务失败会带来明显成本的生产环境这个概率还是偏高。完全规则路由的方案则走向另一个极端。规则一旦写多很快退化成每个技能一个 if技能之间的组合逻辑根本表达不出来。比如先读日志再生成周报这个流程用规则你得专门写一个周报任务分支里面再套子分支。如果将来加了读日志生成日报呢读日志写汇报邮件呢每多一种组合就要写一条规则代码很快就膨胀到不可维护这恰恰是当初用技能抽象想解决的问题。现在验证下来比较稳的折中方案是场景分类器 技能候选召回 模型最终选择三层决策。第一层用一个轻量分类器或者一个规则优先的粗筛把请求归到几个大类比如报告生成类数据查询类内容处理类;第二层在各类型对应的技能池里做 embedding 召回 top-k第三层才把候选技能描述交给大模型做最终选择。这样的好处是模型面对的不是几十个技能而只有几个选择空间变小准确率会明显提升。我在某个内部工具上做了对比实验只用模型自由选择时准确率是 82%加了两层预筛后提升到 94%误调用的概率下降了接近 60%。3.2 技能执行时的上下文管理跑起来才知道的组合问题选对技能只是第一步。技能真正执行起来比选错更常见的问题是两个技能之间的数据传递。在纯函数调用时代上一个函数的返回值直接作为下一个函数的输入这个链路是显式写死的。但技能执行时模型会根据实际情况调整执行顺序甚至跳过某一步这时候如果上下文里的数据结构对不上整个链路就崩了。给你看一个我踩过的真实案例。我的周报生成技能第一步依赖项目日志读取技能的输出日志读取技能返回的是一组记录对象字段是{project: 支付中台, hours: 6.5, detail: 完成了退款链路压测}。而周报技能内部写死了要读取字段log_items数组里面每个元素只有title和time_consumed两个字段。两边对不上执行到中间步骤就报 KeyError。这个问题的根源不是代码而是两个技能由不同开发者编写双方的数据契约没有对齐。解决这个问题我现在的做法是在 SKILL.md 里强制增加一个output_schema字段并且在注册时做静态校验凡是main_workflow里声明dependencies的技能启动时必须校验上游技能的output_schema和本技能的输入字段能否匹配。校验逻辑不复杂本质上就是 JSON Schema 的兼容性检查。这个约束条件带来的收益非常大它把运行时才暴露的接口不匹配问题提前到了启动时一次部署前就能发现五六个隐患。我建议任何技能数量超过三个的项目都必须把这一步纳入 CI 流程。# schema_validation.py 片段 from jsonschema import Draft7Validator def validate_dependency(skill_meta, registry): for dep in skill_meta.get(dependencies, []): upstream registry.get_skill(dep[skill]) if upstream is None: raise RuntimeError(f依赖技能 {dep[skill]} 不存在) upstream_schema upstream.get(output_schema) local_input_schema skill_meta.get(input_schema) # 校验本地输入是否是上游输出的子集这里简化成非空校验 if not upstream_schema or not local_input_schema: raise RuntimeError(f技能 {skill_meta[name]} 与 {upstream[name]} 缺少 schema)除了静态契约运行时还需要一个技能执行上下文对象本质是一个类似 dict 的容器记录每一步输出了什么、存在哪个 key 下并且支持嵌套读取。我会在所有技能代码里统一用ctx.get($last_output)和ctx.set(report_data, data)这样的方式做数据传递代替直接写 Python 变量名。这样技能与技能之间唯一的耦合点就是上下文 key而不是具体的数据类后续替换某个技能时只需要对齐 key 就能接入新实现不需要改其他技能的代码。3.3 失败恢复策略为什么 fallback 比重试更可靠技能执行不可能每次都顺顺利利。API 超时、上游返回空数据、参数校验失败这类错误在生产里经常出现。很多人的第一反应是给整个链路加重试执行失败就再来一次。我的经验是无差别重试是性价比最低的方案因为很多失败是确定性的——比如输入数据格式不对重试一万次还是不对。你要做的是把失败分类然后分别设计恢复策略。我按可重试和不可重试把常见故障分成三类第一类是瞬时故障比如网络超时、服务端 503这类可以自动重试但重试次数要限到两次以内且第二次和第三次之间要有指数退避第二类是数据问题例如上游返回了空列表或者字段缺失这类重试没有意义应该直接触发 fallback 逻辑例如读取缓存或换一个上游数据源第三类是技能逻辑内部抛出的业务异常比如参数冲突、依赖文件不存在这类需要把错误信息结构化地返回给模型让模型决定是换一个技能还是直接面向用户说明失败原因。我强烈建议在 SKILL.md 的 fallback 字段里把这些策略写清楚而不是把恢复逻辑全写进代码。因为模型在执行链路中是需要了解 fallback 信息的它得知道如果第一步失败了接下来是继续还是终止才能做出正确的下一步决策。拿生成周报这个技能来说fallback 写明日志接口超时则读取本地缓存目录 /data/log_cache 下的最近文件模型在第二步执行时发现日志读取失败就能自主去尝试缓存路径而不是傻傻地把同样的请求重新发给接口。4. 实测中躲不开的三个坑命名冲突、描述冗长与失败恢复4.1 命名冲突与版本漂移技能多了之后必然遇到技能系统最容易被低估的问题就是命名空间。搜索这个技能可能在内容团队的项目里叫web_search在数据团队的项目里叫data_search。两个技能如果同时注册进同一个 Agent模型在选择时会非常困惑因为它们的 description 可能都写了搜索相关资料。我在一个多团队共建的 Agent 平台上就吃过这个亏两个技能的名字和描述高度相似结果模型总选错导致搜索结果完全不是用户想要的。解决办法是建立统一的技能命名规范强制带上领域前缀比如内容类叫content_search数据类叫data_query_search同时要求 description 的第一句就写明领域和边界。这个规范要写进团队的技术文档并且做成注册时的强校验名字必须匹配^[a-z](_[a-z])*$且不允许和已注册技能同名。第二步是在注册表里加一个别名冲突检测扫描新注册技能的 description 和已有技能的 description 的文本相似度超过阈值就报警提醒人工确认。版本漂移是另一个容易踩的坑。技能升级后老技能的调用方可能还按旧版的输入格式传参数导致运行时报错。我遇到过最严重的一次是日志读取技能升级了输出字段从project_name改成了project结果下游七个技能里有两个没同步更新线上任务直接失败。现在我的做法有两个一是所有技能注册都必须带版本号并且在 SKILL.md 里用version字段声明二是提供兼容层机制技能升级后保留一段时间的旧输出别名例如输出对象里同时写project_name和project等所有下游完成后才删掉旧字段。虽然有点笨但稳定压倒一切。4.2 技能描述过长导致的选择偏差开头我提到了提示词变长会导致模型选择不稳定这里展开讲一个反直觉的现象。我给项目风险识别技能写过一个特别详细的描述把每一步逻辑、每个判断规则、每个输出字段都写了进去想着这样模型一定最清楚什么时候用它。结果是其他技能的选择率整体下降而这个技能无论面对什么任务都容易被选中。后来分析才知道描述过长会让模型产生这个技能内容最丰富、最可靠的错觉本质上类似注意力机制里长文本会占据更多权重。解决这个问题分两步第一把技能的选择描述和执行细节分离。选择描述只保留简短的 name、description、when_to_use、dependencies 和 main_workflow 的步骤概览强制控制在 800 字以内我实际验证的阈值超过 1000 字准确率会明显下滑。执行细节挪进技能代码里的注释或专门的 docs 文件只在执行阶段由执行引擎加载不进入模型的选择上下文。第二在描述里专门加一个排除性提示明确写此技能不适用于哪些场景。这看似矛盾但实测能把误选率降低一半以上。核心逻辑是给模型一个边界感它才知道什么时候不该用这个技能而该用技能本身的效果是让 Agent 从撒网式尝试变成脚手架式执行。4.3 失败恢复的静默失败陷阱我在真实场景里调试过很多次 Agent 任务的失败发现最危险的不是报错失败而是静默失败——进程没有报错任务状态被标记为完成但产出内容根本不对。最典型的一种是日志读取技能在数据源没有匹配记录时返回了一个空列表周报生成技能拿到空列表后没有报错而是直接生成了一份本周无工作内容的周报。对于用户来说这个结果是荒谬的但系统层面所有状态码都是成功的。这个问题暴露之后我才意识到失败恢复策略里最容易被忽视的一点你必须给预期为空和非预期为空设置明确的判定标准。现在我的技能模板里强制加入了一个empty_output_policy字段写明哪些输出字段允许为空、哪些必须非空以及为空时要执行什么动作——是跳过、填充默认值还是整体中断并通知用户。周报生成技能的配置就写了log_items 为空时报错并在回复里提示用户未找到任何日志记录请检查时间范围或数据源。这个字段不会进入选择描述只在执行阶段被读取但它保证了链路不会在用户不知情的情况下产出垃圾结果。我建议所有从外部数据源读取数据后再做加工的技能都必须配置这个策略宁可失败得大声也不要错误得安静。5. 从零搭建最小可用技能系统的完整方案5.1 最小可用技能集怎么定先走通端到端再横向扩展搭建 agent-skills 的第一个项目最容易犯的错误是贪多。我见过一个团队第一天就定义了十六个技能结果一周过去没有一个跑通了端到端流程。我自己的经验是初始技能集不要超过三个而且这三个必须能串成一个完整的业务闭环。举例来说如果你想要一个自动生成周报的 Agent最小技能集就是三个项目日志读取、工时统计/汇总、报告渲染。这三个技能一条链路走通你才算真正掌握了技能系统的注册、选择、编排、恢复整套机制之后再加技能都是顺水推舟的事。技能目录和代码骨架我建议用下面这个最小结构起步agent_project/ skills/ project_log_reader/ SKILL.md main.py summary_calculator/ SKILL.md main.py report_renderer/ SKILL.md main.py registry.py orchestrator.py main.pymain.py 里就是最精简的 Agent 主循环接收请求 - 召回技能 - 模型做选择 - 按工作流执行技能 - 返回结果。把这条主链跑通之后再考虑加缓存、加审计日志、加技能热更新这些外围能力。不要本末倒置——技能系统最核心的价值是结构的确定性这个确定性在你只有三个技能时就能充分体现。5.2 测试与评估怎么知道一套技能真的可用很多人对技能系统的测试止步于每个技能单独跑一次看看能不能返回结果。这远远不够。技能系统真正的风险在组合不在单体所以评估的重心要放在链路上。我常用的方法是建一组端到端的黄金用例集每个用例包含一段用户请求、期望调用的技能序列、期望的输出结构。每次改动技能或配置后跑一遍黄金用例集统计三个指标选择准确率模型选对了技能吗、执行成功率技能跑通了吗、结构符合率输出 schema 和期望的对得上吗。这三个指标里我要特别提醒结构符合率的重要性。技能系统的输出如果每次都长不一样下游的对接成本会持续高涨。我在自己的项目里把输出比作快递单无论搬运的包裹内容怎么变单子上的收件人、地址、电话字段必须永远不变。所以每个技能的核心输出都用 Pydantic 模型或 dataclass 定义死并且单独写 schema 测试任何字段变更都必须显式改版本号不允许无声无息地改结构。另外要给技能系统加日志可观测性。每个技能执行时要把选择了哪个技能、输入了什么、输出了什么、耗时多少、有没有走 fallback都记录下来存成结构化日志。这不是可有可无的运维功能而是技能调优的数据基础。我最初发现模型总选错技能就是靠日志发现某些请求普遍倾向于命中同一个技能再结合具体输入分析才定位到是描述边界不清。没有日志这类问题只能靠用户投诉才知道代价差太多了。最后聊一个容易被忽视的性价比问题技能描述质量的提升对选择准确率的影响远大于换一个更大的模型。我在同一套技能系统上做过对比用原来的小参数模型配合优化后的技能描述和三层决策链路任务成功率比裸用大参数模型还高出一截。所以投入精力的优先级应该是先固化技能描述规范再做召回优化最后才是升级模型。这个顺序反了你会花大价钱买来更聪明的模型却依然喂给它一堆模糊不清的技能清单结果只是把错误犯得更快。
