1. 为什么“技能”成了智能体落地最难收拾的部分上个月我把一个内部检索问答智能体从Demo推到线上最耗时间的环节不是模型选型也不是Prompt调优而是那一堆越写越乱的技能文件。当时项目名叫agent-skills本意是给智能体配一套可复用、可扩展的技能库结果前两周我面对的问题全是技能本身的组织问题技能描述写法不统一、参数Schema深浅不一、多个技能之间职责重叠、模型选错工具导致回答质量忽高忽低。说实话跑通一个带工具调用的Agent在2025年已经不难了真正难的是当技能数超过20个以后这套体系还能不能保持清晰、稳定、可维护。如果你也在做类似的智能体项目大概率会遇到同样的瓶颈单技能Demo跑得飞起技能一多就乱成一锅粥。这篇文章把我搭建agent-skills过程中的拆解思路、文件组织方式、调度策略和踩坑记录完整写出来希望能给正在做Agent技能编排的工程师一点可参考的实操经验。1.1 项目背景从“会调用工具”到“有技能体系”最初我的需求很简单让Agent能查内部知识库、能跑SQL、能调告警接口。直接在每个节点写死工具调用也能跑但很快发现三个问题一是同一个操作在多处重复实现改一处漏一处二是Agent需要知道什么时候该用什么工具可工具本身没有“自我描述”的能力三是新增一个数据源就要改业务流程扩展性极差。于是我把思路从“工具”升级成“技能”。工具是单纯的函数或API技能则是“触发场景 使用说明 参数契约 执行逻辑”的完整封装。Agent面对用户请求时不再是从一堆函数里碰运气而是从一份有语义、有边界、有样例的技能清单里选最匹配的一项。这个转变看起来只是概念上的实际落地后整个系统的可维护性和成功率都明显上升。1.2 核心设计一份“带说明书的工具箱”我把agent-skills设计成三层结构技能描述层给大模型看的“说明书”包括技能名称、适用场景、参数说明、使用样例。技能执行层给代码跑的逻辑可能是Python函数、Shell脚本也可能是一次HTTP调用。技能管理层负责技能注册、检索、路由、版本更新的胶水层是技能体系的心脏。打个比方传统工具调用就像你把一堆零件扔给Agent告诉它“你自己看着装”而技能体系是每一个零件都贴好了标签、写好了安装手册Agent只需要判断当前该用哪个盒子。对于依赖大模型做决策的系统后者明显更可靠因为模型的判断空间被大幅收敛了。这个项目中我选型了一套偏轻量的组合Python FastAPI做技能服务技能描述用YAML文件维护执行函数用Python实现技能的注册信息统一汇总到一个索引文件里。选这套组合的原因很简单团队里Python基础最好调试Agent链路时单文件技能最容易复现问题不需要引入额外的微服务框架。2. 技能目录的拆解与粒度控制技能体系最容易翻车的地方不是技术实现而是最开始的“拆解”。拆得太大技能内部逻辑臃肿、复用率低拆得太碎技能数量爆炸、调度困难。我前后重构了两轮最终沉淀出一套还算稳定的方法论。2.1 从任务到技能的两级拆解法我不建议直接对着“用户可能会问什么”列技能那样列出来的都是需求清单不是技能。我采用的是“任务类型 → 操作动作”两级拆解第一级圈定Agent的核心任务域。比如我的项目涉及的域是“知识问答”“数据分析”“系统运维”“信息同步”。每个域对应一个技能分组。第二级在每个域里列出原子操作。以“数据分析”域为例原子操作包括执行SQL查询、获取表结构、生成统计摘要、导出结果为CSV、对比两个查询结果。每一个原子操作就是一个候选技能。这个拆法有一个明显好处任务域是稳定的域里的原子操作会随着业务发展增加但域的边界不容易漂移。技能体系的结构自然稳定新增技能时只需要判断“它属于哪个域”不用反复调整顶层设计。2.2 技能粒度的两条判断标准拆完以后技能粒度是否合适我会用两条标准验证标准一能否用一句话说清触发场景。如果描述这个技能需要超过两句话说明粒度太大要继续拆。比如“执行SQL查询并从结果中生成报告”就是两个动作要拆成“执行SQL查询”和“生成分析报告”。标准二一个技能在一次会话中是否会被重复调用多次。如果一个技能每次执行都绑定其他技能优先考虑合并或调整边界。比如“获取表结构”几乎总是被“执行SQL查询”前置调用我就把两者做成独立的技能但在“执行SQL查询”的描述里明确提示“当用户未指定表名时可先调用获取表结构技能”这比强行合并成一个技能更灵活。按这个标准我最终沉淀出32个技能分布在4个域里。这个数量对调度来说是一个比较舒服的量级——模型的候选集足够大但又不至于因为选项过多而频繁选错工具。2.3 命名规范与描述编写模型视角的“第一印象”技能命名直接影响模型的选择准确率。我实践下来有一条铁律技能名用“动词 业务对象”的结构禁止用缩写、代号和过于抽象的词汇。对比一下execute_sql_query—— 清晰模型一眼就能判断什么时候用。data_fetcher—— 模糊太像组件名不像技能名。get_table_schema—— 清晰。schema_provider—— 抽象模型很难在“查表结构”这个意图下联想到它。技能描述同样有讲究。我见过很多人把描述写成“该技能用于执行SQL查询”这个写法信息量太低。更好的写法是包含适用场景、前置条件、使用限制、示例问题。比如name: execute_sql_query description: | 当用户需要查询数据库中的数据、统计数量、分析指标趋势时使用。 支持标准的SELECT查询不适用于INSERT/UPDATE/DELETE操作。 若用户未指定具体表名建议先调用 get_table_schema 获取可用表。 example: 查询最近7天订单总量这样写模型在意图匹配阶段就能避开一大批误用场景。有一说一我见过不少团队把时间花在调模型上其实技能描述写好了选错率能直接下降一大截。3. 注册表、Schema与调度策略技能怎么被Agent找到技能文件本身只是“零件”让Agent在合适的时机找到合适的技能靠的是注册表和调度逻辑。这一层决定了整套技能体系的智能程度。3.1 技能描述是“招牌”而非“说明书”我强调一个容易被忽略的点在把技能列表交给Agent时绝大多数框架会把description当作唯一的判断依据。这意味着超长描述不一定更好——太长的描述会稀释关键词密度模型反而不容易抓住重点。我自己在agent-skills里做了一层“双描述”机制short_description30字以内用于意图粗筛突出触发场景的关键词。description用于模型确认阶段包含更详细的场景、限制和示例。粗筛阶段用短描述候选技能收窄到3到5个以后再让模型读长描述做最终决策。不要小看这个分层设计实测在35个技能规模下选错率下降约15%。这不是什么高深算法就是信息架构的合理性对模型决策质量的影响。3.2 参数Schema暴露最少的量提供最大的容错技能调用失败通常不是因为执行逻辑有Bug而是模型生成的参数不合法。大部分原因是参数Schema设计得太复杂。我在项目里有一个明确的倾向能少暴露参数就少暴露能自动推断就不要让模型猜。以execute_sql_query为例第一版我设计了6个参数table_name、fields、conditions、group_by、order_by、limit。看起来很灵活实际上模型经常生成结构化错误的conditions或者把表名写成带引号的字符串。第二版我重构为两个参数{ type: object, properties: { sql: {type: string, description: 完整的只读SQL查询语句}, params: {type: object, description: 查询参数可选} }, required: [sql] }让模型直接输出完整SQL看似把更多复杂度留给了模型实际反而更稳——因为模型对SQL语法的理解比对结构化条件对象的理解强得多。这个改造的收益非常大技能调用的参数解析失败率从7%降到不到1%。这里我总结出一个通律凡是能用一个字符串表达清楚的内容就不要设计成嵌套对象。模型生成字符串的能力远强于生成严格嵌套结构的能力这不是玄学是语言模型本身的特点。3.3 调度策略分组索引优先于全量匹配当技能数量达到30以上时每次请求都把全部技能描述发给模型Token消耗和选择错误率都会上升。我做了两层优化一层是按域分组索引。我根据历史会话数据训练了一个简单的意图分类器先判断请求属于哪个任务域再只把该域下的技能列表发给模型。这个分类器甚至不需要很准准确率80%就够了——因为即使误判也只是多了一次候选集切换的代价。另一层是优先级标记。有些技能是高频技能比如“执行SQL查询”“获取当前时间”而有些是低频技能比如“导出CSV报表”。我给每个技能打上了priority字段高频技能始终出现在候选列表中低频技能只有在描述匹配度足够高时才加入候选。这能有效防止模型被低频但描述抢眼的技能带偏。调度策略的取舍本质上是对“模型决策自由度”的管理自由度越大灵活度越高但稳定性越差。技能体系的目的不是让Agent“为所欲为”而是在可控范围内做最优选择。4. 技能文件组织、本地依赖与版本演进如果说调度是运行时的事文件组织就是开发期的事。项目团队越多人参与技能开发文件组织的重要性越高。这一节内容是纯经验沉淀网上很少看到有人系统写这块。4.1 目录结构一技能一文件夹依赖显式声明我的技能目录结构长这样skills/ ├── registry.yaml ├── knowledge_query/ │ ├── skill.yaml │ ├── run.py │ └── tests/ │ └── test_basic_query.py ├── data_analysis/ │ ├── execute_sql_query/ │ │ ├── skill.yaml │ │ ├── run.py │ │ └── tests/ │ ├── get_table_schema/ │ │ ├── skill.yaml │ │ ├── run.py │ │ └── tests/ │ └── export_csv/ │ ├── skill.yaml │ ├── run.py │ └── tests/ └── ops_toolkit/ ├── check_service_health/ │ ├── skill.yaml │ ├── run.py │ └── tests/ └── restart_service/ ├── skill.yaml ├── run.py └── tests/核心原则一个技能一个文件夹内部包含描述文件、执行脚本、测试用例。run.py暴露统一入口例如def run(context: SkillContext) - SkillResult这样注册和调用时不需要关心每个技能内部实现。registry.yaml是全量注册表通过脚本自动扫描目录生成避免手动维护错漏。跨技能依赖必须在skill.yaml里显式声明depends_on禁止在执行函数里直接导入其他技能的模块。我吃过暗亏早期没有显式依赖声明一个技能偷偷导了另一个技能的内部函数后来被引用的技能重构了参数直接带崩了上游技能。显式声明依赖以后这种隐式耦合基本杜绝了。4.2 技能升级时的兼容性红线技能不是一次写完就不动的。数据源变了、接口变了、业务口径改了都得升级技能。我给这个项目定了几条兼容性红线变更类型是否允许处理方式修改技能描述文案允许无需发版但需重跑冒烟测试新增参数必填不允许必须新技能或开新版本新增参数可选允许老请求不受影响删除参数不允许必须新技能或开新版本改变返回结构不允许必须增加技能版本号修改执行逻辑但返回不变允许需走回归测试为什么“删除参数”和“改变返回结构”不允许因为Agent可能会在多轮对话中记住之前的调用方式一旦技能格式变化它还会按老格式生成调用请求产生运行时错误。我的解决办法是引入版本化技能包技能名加_v2后缀新老技能并存一个周期等线上请求日志证明老版本不再被调用后再下架。4.3 测试与验证给每个技能配“冒烟用例”技能测试和普通单元测试最大的区别在于执行逻辑正确不等于Agent会正确调用。所以我在每个技能的tests/目录下放两类测试一类是执行测试。给定参数验证run.py返回结果正确这主要是保证执行层不坏。另一类是意图测试。构造用户请求样例验证模型能否正确选择该技能。例如对execute_sql_query我会跑一组请求“上个月各区域的销量是多少”“帮我查一下库存表里数量大于100的商品”确认Agent选择了这个技能而不是get_table_schema。回归技能时第二类测试才是真正的护城河。很多技能执行逻辑没变只是描述文件被顺手改了几个字结果模型就不认识了。用自动化脚本跑一遍意图测试能快速发现这类回归省去了大量手动调试时间。5. 从0到1搭建agent-skills时踩过的坑最后用一节内容写写我踩过的坑都是真实项目中花过时间才填平的问题。5.1 技能描述互相打架模型在相近技能间随机选择第一个坑来自两个相似技能get_table_schema和get_table_statistics。在早期版本里前者写“获取表结构”后者写“获取表数据统计信息”看起来很清楚但模型遇到“这张表都有哪些字段”时两个技能的置信度都接近。我在日志里看到的真实情况是同一个问题有时选A有时选B毫无规律。后来我把get_table_schema的示例问题明确改为“用户想知道表里有几列、每一列叫什么名字、什么类型”并在get_table_statistics的描述开头加了一句“仅当用户询问数据分布、行数、去重数量等统计指标时使用”。两个技能仍然相似但边界判据清晰了模型就不纠结了。所以我现在的习惯是写描述时假设看到的是一个完全不了解业务的人把“什么时候不该用”也写进去。很多技能误用不是模型笨是描述里没有负向边界。5.2 参数Schema过深导致模型胡编参数前面提到我把execute_sql_query的参数简化成两个这里展开说说当时的具体现象。第一版结构化参数里有个conditions要求是数组每个元素包含field、operator、value三个字段。模型生成这个结构时经常出现{field: order_date, operator: , value: 2025-01-01, logic: and}多了一个Schema里没定义的logic字段。模型擅长“自由发挥”一旦约束结构复杂它就容易按照自己对JSON的理解补齐一些不存在的字段。这个问题排查起来非常难因为错误不是必现的而是偶发的且每次出错都不一样。简化参数后几乎所有这类问题都消失了。我现在定了一个参数设计原则Schema的嵌套层级不超过两层必须参数不超过三个。超过这个复杂度优先考虑把参数合并为字符串或对象。5.3 技能太多引发的“调度风暴”项目中期技能数一度达到60多个我发现模型频繁在无关技能之间犹豫甚至导致超时。典型场景用户说“今天系统有没有告警”模型先选了check_service_health又改成query_alerts最后还调用了一次get_current_time才给出一个简单答案。这不是模型能力退化而是候选技能太多干扰太大。我的解决办法有三个前面提到的分组索引大部分请求先走域分类器。高频技能固定加入候选低频技能走阈值匹配。在技能描述里统一强调“不要在没有明确依据时为了调用技能而调用”。第三点看起来像是废话但写进系统提示词后无意义调用率确实降了。原因是模型本身有一种“工具倾向”——面对可以调工具也可以直接回答的选择时它更倾向于调工具来显得“勤快”。明确告诉它“某些问题可以直接回答”能有效抑制这种倾向。5.4 冷启动没有样本第一批技能怎么定义说实话agent-skills的冷启动阶段是最迷茫的。没有历史调用日志没有用户反馈数据怎么定义第一批技能我当时的做法是直接翻过去一个月的客服对话记录和内部工单把高频请求拉出来人工归类。工单里出现频率最高的操作就是第一批技能的种子。对系统日志类场景我则用了另一招把过去一周的误操作和重复操作提取出来反向倒推“如果当时有一个技能用户是不是就不需要人工介入”。汇总后第一批技能就自然浮现了。冷启动阶段切忌一步到位。我先做了8个技能保障核心闭环跑通以后持续观察日志每周补充2到3个一个月后才扩充到20个以上。早早地堆技能数量没有任何好处只会让调度变得更难。6. 最后分享一点实际经验写完这套agent-skills我最深的感受是技能体系本质上不是一个技术问题而是一个信息架构问题。你定义技能的边界、写描述的方式、组织文件的方式最终都会变成模型决策质量的一部分。与其花大量时间调模型参数不如把这些信息层面的基本功做扎实。如果你的项目还处于前期我建议先做一件最简单的事把目前Agent需要做的任务列成清单试着给每一个任务写出一句“什么时候用”和“什么时候不用”的描述。如果写不出来说明你对这个任务的边界还没想清楚这时候先别急着写代码。想清楚了代码只是最后一步。对我个人而言这套技能体系最大的意外收获是它让团队里非算法同学也能参与到Agent的优化中来——只要会写清晰的描述文档就能直接改善Agent的行为。这一点比任何一个模型调参技巧都来得实在。