1. 技能系统要解决的核心问题
我在做智能体相关项目时，最头疼的一件事就是：模型能力明明很强，但落地到具体任务上总感觉"有劲使不上"。你让它写代码，它写得不错；你让它操作软件，它就蒙了；你让它调外部接口，它更是一头雾水。原因很简单——大模型本质上只是一个推理引擎，它不具备直接与外部世界交互的"手和脚"。而"agent-skills"这个项目，恰恰就是要给智能体装上这套"手脚"。
什么是Agent Skill？说白了，就是把智能体需要执行的原子操作封装成标准化的技能模块，让大模型能够在合适的时候发现、调用并正确使用这些技能。你可以把智能体想象成一个人，推理能力是大脑，技能就是肌肉记忆。大脑负责判断"该干什么"，技能负责回答"怎么干"。
这个项目最早的需求来源非常接地气：我给某公司做了一个内部知识库问答机器人，刚开始效果很好，但用户很快不满足了——"能告诉我报销流程吗？""能帮我直接发起一个报销申请吗？"从"回答"到"行动"，这中间隔着一条鸿沟。靠提示词是填不平这条沟的，必须有一套技能系统，把"开口说话"变成"动手做事"。
适合谁来参考？两类人：一是在做智能体应用但卡在"工具调用不可控"这个坑里的开发者；二是准备从demo走向生产环境，想让Agent真正干活的团队。如果你只是想跑通一个简单的ChatGPT式对话，那这套东西对你来说可能偏重；但如果你惦记的是"让Agent帮我干活"，这篇文章值得你读完。
2. 技能系统的整体设计思路
2.1 为什么不直接用函数调用
你可能想问：现在各家大模型平台都支持Function Calling（函数调用），直接在API里声明几个函数不就行了？为什么还要搞一套"技能系统"？
我刚开始也是这么想的。实际写了一段时间后发现，函数调用这件事，在demo里很美好，一上生产环境就露馅：
第一，函数调用通常和具体平台绑定。你在某家平台的写法，换一家平台就要重写。真到了多模型切换的时候，这个成本是实打实的。某次我需要把模型从一家切换到另一家，光改函数调用的适配层就花了两天，这还是函数数量不超过十个的情况。
第二，函数调用本身不带"策略"。模型告诉你"我想调用get_weather"，你就得调用，但如果这个函数需要鉴权、需要参数清洗、需要判空呢？这些逻辑放在哪里？放在提示词里不靠谱，放在函数里又让函数变得臃肿。
第三，也是最关键的：函数调用是"一次性操作"，它没有记忆、没有监控、没有回退机制。Agent真正常态化跑了三个月之后，你会发现你需要的是"技能的运行记录""燃烧预算""失败分析"，这些东西函数调用给不了你。
所以我把思路从"函数调用"升级成了"技能系统"：每个技能不仅是"一个函数"，更是一个自包含的模块——它有自己的schema定义、有调用前校验、有执行逻辑、有结果解析，甚至有失败时的降级策略。这才是生产环境该有的样子。
2.2 技能的四层架构
整个"agent-skills"项目，我最终拆成了四层，每一层只干一件事：
- 技能注册层：负责技能的定义、注册和热更新。技能仓库里有什么技能，这一层说了算。
- 技能路由层：根据用户的请求和上下文，决定要不要调用技能、调用哪个技能、按什么顺序调用。这一层是整个系统的大脑。
- 技能执行层：真正干活的地方。负责处理技能的参数、执行、超时、重试，以及把各种外部返回转换成模型能理解的格式。
- 技能治理层：运行日志、监控指标、成功率统计、评级体系。这层决定了你的技能系统能不能长期跑下去。
这个分层不是拍脑袋想出来的，是踩了坑总结出来的。最早我图省事，把注册和路由揉在一块，结果每次更新技能都要动路由逻辑，一不小心就把全流程搞挂了。后来老老实实分层，才体会到什么叫"功夫在架构里"。
从流行的"技能 + 工具"范式看，很多框架把工具定义为LLM调用的底层能力，而技能则是"工具的组合套装"。这四层架构和那个范式并不冲突——注册层管理工具，路由层负责编排，执行层承担工具调用，治理层做质量监控，"agent-skills"相当于在这套范式基础上，把生产化的坑提前填平了。
2.3 技能描述为什么比实现更重要
这可能是整个项目里最重要的经验：技能系统真正的技术含量，不在实现，而在描述。
大模型不像传统程序那样看函数名就知道是什么意思。它判断"该用哪个技能"，靠的是技能的描述文本。很多人在这一点上吃亏——描述写得太简略，模型判断不出来；描述写得太啰嗦，模型反而被噪声干扰。
我后来定了一个描述模板，每个技能都必须包含六要素：技能名称、适用场景、输入参数说明、输出结构说明、使用限制、典型示例。注意，是模板，不是自由发挥。有了模板之后，模型的选择准确率明显提升。
还有个细节：技能描述里一定要写清楚"什么时候不该用这个技能"。看起来是负向描述，但实测下来对模型判别的帮助特别大。比如技能"查询天气"，描述里加上一句"仅用于查询当前及未来天气，不适用于历史天气回顾"，模型的误调用率会肉眼可见地下降。
3. 核心细节解析与实操要点
3.1 技能定义的数据结构设计
技能定义是整个系统的基础。我最终采用的数据结构大致是这样的：
@dataclass class SkillDefinition: name: str # 技能唯一ID，如 "send_email" display_name: str # 人类可读名称，如 "发送邮件" description: str # 模型可见的描述，遵循六要素模板 parameters: dict # JSON Schema格式的参数定义 required_parameters: list timeout_seconds: int # 超时时间 retry_policy: dict # 重试策略 enable: bool = True # 是否启用参数定义我强烈建议直接用JSON Schema，不要自己发明格式。原因有仨：模型对这些格式的理解是最好的；校验库现成（Python里用jsonschema就够了）；将来接别的系统也好兼容。
一个我自己反复用的技巧：参数定义里尽量给枚举值。比如技能的某个参数是"排序方式"，你写"0或1"，模型可能会困惑；你直接给enum: ["asc", "desc"]，模型基本不会再出错。以模型的"语文理解能力"，你给它选项，它就稳了。
3.2 技能注册与热更新
技能注册这块，我做的比较重，但也正是这个"重"让系统能长期跑下去。每个技能注册时，除了基本信息，还会强制执行一次"自检"：用3-5条模拟输入调用一遍技能，确认输出结构正确，才允许上线。这个自检机制帮我拦截了至少十次"参数类型写错"之类的低级事故。
更新技能有两种方式：全量更新和定向更新。全量更新就是把整个技能仓库的索引重建一遍，适合初始化或者版本大升级；定向更新是只换单个技能的定义或实现，适合线上快速修问题。
这里有个实战建议：技能代码和技能定义最好分开管理。之前我把代码和定义放在同一个文件里，每次改一个描述都要重新部署代码。后来把定义抽成JSON文件，用配置中心做分发，改描述只需要走一个配置变更，几分钟生效，不用重启服务。日常迭代效率提升不是一点半点。
3.3 描述模板的完整示例
我在项目里实际用的模板长这样：
<skill> 名称：terminate_process 适用场景：当用户要求结束某个程序或任务进程，且已知进程名称或PID时使用。 参数： - process_name (string, 可选)：进程名称，如 "chrome" - pid (integer, 可选)：进程ID 使用限制： - 当且仅当当前系统为Windows/Linux/macOS时有效 - 不能操作用户未明确指定的进程 - 禁止以kill -9形式强制结束系统关键进程 典型示例："帮我关掉chrome" → 应调用本技能，参数为 {"process_name": "chrome"} 输出：返回被结束进程的名称、PID及结束结果状态 </skill>我特意用了类似XML的标签包裹，实测下来，这种结构化描述比纯文本更容易被模型解析。还有个心得：描述里用"应调用本技能"这种正向指令，比用"你应该"更直接——模型对祈使句的理解效果更好，这是我做了几组对比实验才确认的细节。
六要素模板保护了描述的基本盘，XML结构让描述更易解析，祈使句进一步降低歧义，这几层叠加后，我这边技能选择准确率从最开始的79%左右提升到了94%以上，涨了十多个百分点，效果非常明显。
4. 实操过程与核心环节实现
4.1 技能路由的两种策略
路由层是整个系统里最有嚼头的部分。我在这个项目里实践了两种路由策略，各有适用的场景。
第一种是"意图直连"。用户请求进来，先做意图分类，每个意图类别绑定一组候选技能，再从候选里挑一个。这种方式优点是快、可控性强；缺点是意图分类本身就可能出错，意图错了，后面全错。我用它做了几个内部工具的自动操作场景，比如"导出报表""发通知"这类请求模式高度固定的场景。
第二种是"上下文语义检索"。不先判断意图，而是把用户的请求向量化，和一个技能描述向量库做相似度检索，取出Top-K相关的技能描述，再连同用户请求一起丢给模型做最终决策。这种方式适合开放式任务，比如知识助手那种用户想问什么你根本猜不到的场景；缺点是引入了向量检索链路，调度延迟会高一截。
实际项目中，我通常把两种策略叠起来用：高层用规则路由缩小范围，底层用语义检索+模型决策做最终选择。举个例子，用户说"帮我查一下昨天的访问日志有没有异常"——规则层判断这属于"运维分析"类别，只把日志分析相关的3-5个技能送进检索层，检索层再结合日志内容做final选择。这样既不怕意图太泛，也压住了检索噪声。
4.2 技能编排：多技能协作的串联逻辑
单个技能调用是基础，真正体现Agent价值的是多技能编排。这个项目里我实现了一个轻量的编排引擎，支持三种基本组合模式：串联、并联和条件分支。
串联好理解，就是"先A后B"，比如先查订单状态，再根据结果发起退款申请。并联是"同时做"，比如一次收集多个渠道的数据。条件分支是"根据前一个技能的输出决定走哪条路"，这是编排里最灵活也最容易出bug的地方。
我踩过一个大坑：条件分支的判断逻辑不能依赖模型。你不能让模型自己判断"刚才是不是执行成功"，因为它的判断不一定符合你的预期。正确做法是让执行层返回一个结构化的状态码，然后用代码来做分支判断。我在系统里定义了标准状态码：SUCCESS、FAILED、PARTIAL_SUCCESS、NEED_USER_CONFIRM，编排引擎只认这些码。
举个实际的例子：用户说"帮我把这周的数据汇总成PPT发到团队群"。这个请求最终被编排成了四步：收集周报数据（并联调用数据源技能）→ 分析异常指标（调用分析技能）→ 生成PPT（调用文档生成技能）→ 发送到群（调用消息技能）。中间任何一步失败，都按预设的降级策略处理——比如PPT生成失败，就退化为"把数据表转发到群里"，保证用户至少拿到原始材料在一次产线演练中，这个"降级"策略直接救了一整个演示。
4.3 技能的嵌入命名与可观测性
技能库里技能一多，命名就成了大事。早期我起名比较随心，比如"查订单"叫get_order，"查用户信息"叫fetch_user，"查询库存"叫check_stock，看起来没问题，但模型在选择时有一个明显的倾向：它更喜欢名字里语义完整的技能。后来我把命名统一改成了"动词_领域_对象"的嵌入式命名，比如query_order_detail、query_user_basic、query_stock_level。改名之后的技能选择准确率又涨了一截，逻辑大概类似"变量名写清楚，代码自己就能读"。
可观测性方面，我给每个技能打了三个埋点：调用时间、输入参数摘要、输出状态。跑了一段时间之后，我发现自己能清楚看到"哪个技能被高频调用、哪个技能老是失败、哪个技能总是等超时"。有一次线上调用成功率突然下降，我没去翻代码，先查了技能监控仪表盘，发现是一个技能最近换了上游接口，把返回值里某个字段名改了，导致解析失败。因为埋了点，五分钟就定位了问题——这类问题如果没有监控，排查可能要花一小时起步。
4.4 执行层的容错设计
执行层要处理的不只是"技能本身报错"，还有外部依赖的种种意外。这个项目里我把容错拆成了三个级别：
第一级是参数校验。入参不合法的一律打回，不让技能进入执行态。这一步帮我挡掉了大量"用户随口一句话导致参数类型不对"的情况。
第二级是超时与重试。每个技能有独立的超时时间，超时后按重试策略决定是否重试。我的经验是：幂等技能可以放心重试，非幂等技能（如发邮件、转账）绝不自动重试。这听起来像是常识，但真出事往往就是忽略了这一点。
第三级是失败兜底。技能失败后，把错误信息转化为用户可理解的提示，或者走降级分支。有些技术同学觉得"失败就失败，把错误抛出去告诉用户不就行了"，但在Agent场景里不行——用户已经习惯了"你说一句话就有人帮你办成事"，你直接甩一个HTTP 500给他，体验直接崩了。
5. 常见问题与排查技巧实录
5.1 模型就是调用不对技能，怎么办
这是问得最多的一个问题：技能明明都定义好了，模型还是会选错或者不选。我遇到的情况大概有这么几种：
- 描述太含糊，模型判断不了。比如"获取信息"这种描述，换个谁都看不出来是干什么的。
- 技能太多，模型看不过来了。上下文窗口有限，你塞100个技能描述进去，模型肯定晕。
- 正向约束太多，负向约束缺失。模型只知道自己"能做什么"，不知道"不该做什么"。
排查思路是这样：先看路由日志里，模型当时"看到"的技能列表是什么样的。如果Top-K太大，就先调小K值；如果描述模糊，就按六要素模板重写。实测下来，80%以上的"不调用"问题，都是这三个原因之一。
5.2 参数乱传，模型给的JSON结构不对
模型输出的JSON格式不符合技能参数的schema，在早期非常频繁。我最初的做法是"报错重试"——让模型自己改正，效果一般。后来改成：先用宽松解析把模型输出变成Python dict，再用jsonschema做严格校验，校验不通过时把具体的错误信息拼到下一步提示里。让模型重生成的时候能看到"哪个字段缺了、哪个字段类型不对"，准确率提升非常明显。
这里还有一个小工具，是我自己写了一个normalize_parameter函数，专门处理"模型把字符串数字传给integer字段"这类小问题。虽然治标不治本，但确实能减少一大半的校验报错。
5.3 技能执行超时怎么处理
超时的根因，一半是外部接口慢，一半是我们自己设计的超时时间不合理。排查时先看监控里耗时分布，如果P99时间远高于P50，说明有长尾延迟，那就在执行层加"快速失败"——超过某个阈值就先返回排队结果，别死等。
技能重试策略我一般这样设置：网络类技能（HTTP调用）允许重试1-2次，使用指数退避；本地操作类技能不重试。重试间隔建议300ms起步，别用固定间隔，不然上游接口一抖，你这边就变成重复点击。
5.4 技能系统的后续扩展方向
项目跑通之后，有几条线我觉得特别值得做，也和正在做这个方向的朋友提一下：
一条是技能的自学习。把用户多次确认的"成功/失败"信息，转换成技能的自动调优信号，定期更新技能描述里模糊的部分。另一条是技能市场化的能力——把内部技能打成标准包，供多个Agent共享复用，避免"每个Agent各搞一套技能"的浪费。
还有一条我个人很感兴趣，就是跨Agent技能协同。现在每个Agent都是单兵作战，未来如果两个Agent需要协作完成任务，技能系统之间如何互相调用、如何做权限控制，这些都是新课题。不过说实话，现阶段能把自己的技能系统打磨到稳定可复用，已经能解决很多实际问题了。
最后分享一个个人习惯：我会定期复盘一周的技能调用日志，专门找那些"被拒绝了两次以上"的请求。这些请求往往就是技能覆盖的盲区，每个盲区补上一个新技能，三个月下来，整个系统的能力边界会明显变大。这个习惯，是我从"agent-skills"项目里得到的最值得的一笔经验。
