当初把Agent从demo推到生产环境，我卡在第一个绕不过去的问题上：模型很聪明，但手脚很笨。让它写一段文案、做一次翻译，效果惊艳；让它去查一张报表、发一封邮件、操作一套内部系统，就开始满嘴跑火车。你问它“刚才那步执行成功了吗”，它能给你编一个像模像样的成功结果。后来我才想明白，缺的不是更强的模型，而是那层叫agent-skills的东西——把一条条具体能力封装成模型可理解、可调用、可反馈的“技能”。
这个项目要解决的，就是给Agent装上真正能干活的手脚。它适合两类人：一类是正在做Agent应用但被工具调用折磨得焦头烂额的开发者，另一类是准备从“聊天机器人”往“数字员工”方向转型的团队负责人。下面这些内容是我从实际落地过程中扒出来的经验，包括技能注册表怎么设计、编排层怎么搭、以及为什么我强烈建议你把每个技能都做成“有状态”的。
1. 从“会聊天”到“能干活的Agent”，还差一个技能层
先说我踩过最疼的一个坑。早期我做了一个所谓的Agent，模型用的是当时能力最强的那一档，Prompt写得自认为天衣无缝，工具函数也挂上了七八个。结果在内部试用的时候，运营同事丢给它一句“帮我看看上周华东区的投放数据，顺便把异常波动的日期标出来”，它折腾了五分钟，最后给出一个表格——数据全是编的，波动日期是模型猜的，因为它根本没找到真实数据的入口，但又不想承认自己做不到。
这个问题的根源在于：模型天然是一个“文本生成器”，不是一个“任务执行器”。它擅长的是把输入映射到输出，而不是操控真实世界里的资源。想让模型稳定地操控外部工具，必须有中间那一层——技能层。这层要做三件事：第一，把外部能力抽象成模型能理解的“技能卡片”；第二，把执行结果变成模型能接收的“反馈信号”；第三，把多个技能串成一条可追踪的“任务链路”。
1.1 别急着写代码，先把Agent的“能力边界”画出来
很多团队一上来就急着写注册函数，我觉得这是本末倒置。你首先要想清楚一个哲学问题：你的Agent到底应该拥有哪些能力？是只做信息查询，还是也要做状态变更？是只读数据，还是要写回数据？每多一个技能，模型的选择空间就大一分，出现幻觉和误调用的概率也涨一分。
我建议先用一张白纸把技能边界画出来。我的画法分三列：
- 必须有的技能：跟业务核心强相关，Agent没有它就像人没有手。比如数据分析Agent必须能连数仓、能跑SQL、能渲染图表。
- 锦上添花的技能：属于增强体验，在核心链路之外。比如自动生成周报摘要、把结论推送到钉钉群。这类技能初期可以只做一两个。
- 坚决不要的技能：涉及高风险操作、权限边界不清晰、或者模型当前能力很难稳定驾驭的动作。比如直接删除生产数据、修改线上配置。优先级宁可后面再加，也不要一上来全给。
这个边界画完了，你才知道后面要写的技能注册表该长什么样。我见过太多团队把Agent做成一个塞了二十多个工具的“瑞士军刀”，结果模型在选择工具时反而像个选择困难症患者，每调用一次就要纠结半天，还经常选错。
1.2 技能列表最终长什么样
在agent-skills项目里，我最终把技能定义成了一种高度结构化的描述语言。一个完整的技能，至少要包含以下字段：
{ "skill_name": "query_sales_data", "description": "查询指定时间范围和区域的销售数据，返回聚合后的统计结果，适用于周报、月报、异常分析等场景", "input_schema": { "start_date": "string, 格式YYYY-MM-DD", "end_date": "string, 格式YYYY-MM-DD", "region": "string, 可选值[华东, 华南, 华北, 西南]" }, "output_schema": { "total_revenue": "number", "order_count": "number", "daily_breakdown": "array" }, "side_effects": "read_only", "timeout_ms": 10000 }这个定义很关键。description不是给人看的，是给模型的。模型通过这个描述来判断“当前这个任务该不该调用你”，所以描述里必须写清楚这个技能“能干什么、在什么场景下用、有什么限制”。side_effects字段尤其重要，它告诉模型这个技能是只读的还是会改数据的，这直接决定了模型在面对复杂任务时是敢直接执行还是要先跟用户确认。
2. skill注册表：把工具调用从“临时拼凑”变成“工程化基座”
有了概念设计，接下来就是代码层面的落地。agent-skills项目的核心模块是一个技能注册表，它承担两件事：一是所有技能的注册和管理，二是给模型提供一个统一的查询入口。我把它比喻成“工具箱上的标签贴”——标签写得清清楚楚，模型才知道去哪个抽屉拿什么工具。
2.1 用装饰器和元数据构建统一入口
Python语言下，我用装饰器来实现技能注册，代码极简，效果却非常好：
from agent_skills import register, SkillContext @register( name="query_sales_data", description="查询指定时间范围和区域的销售数据，返回聚合统计结果", input_schema={...}, output_schema={...}, side_effects="read_only", timeout_ms=10000, ) def query_sales_data(ctx: SkillContext, start_date: str, end_date: str, region: str = "全国"): # ctx 里封装了调用方信息、链路追踪ID、鉴权token等 data = ctx.db.query(...) result = aggregate(data) return result这里有一个设计细节值得多说两句：所有技能函数的第一个参数都是SkillContext。这意味着技能不只是一个孤立的函数，它跟调用链、上游状态、鉴权信息是绑在一起的。没有这个context，技能就只能做无状态的计算，一旦要牵扯到用户身份、请求追踪、数据源切换，代码就会变得到处都是隐式参数，非常难维护。
2.2 模型是怎么“看懂”技能列表的
注册表的核心逻辑，是把上面那一堆技能定义转换成模型能看懂的格式。我现在用的方案是，在每次请求进入编排层时，动态组装一个“技能说明全集”，放进system prompt里，同时配合一个tool_choice参数约束模型行为。
这个全集不能太长。模型对 prompt 的注意力是有限的，你把所有技能不分青红皂白全塞进去，效果反而差。我做了个两步筛选策略：
- 粗筛：根据用户输入的关键词，把候选技能从全量列表中过滤到5~8个以内。比如用户问“上周华东区投放怎么样”，
query_sales_data、query_ad_metrics、send_report_to_group会被筛出来，而restart_server这种完全不相关的会被干掉。 - 精排：根据技能描述与用户输入的语义相似度再排一遍，把最相关的放在最前面。模型在选择时，通常更倾向于排在靠前的技能，这个跟大模型的注意力机制有关系。
这个两层筛选的效率提升非常明显。之前直接把20个技能全量塞进prompt，模型工具选择的准确率大概在82%左右，偶发乱选。改成筛选+精排之后，准确率稳定在了96%以上，调用耗时才多了不到30ms。如果你也在做类似的工具路由，强烈不建议直接一股脑全塞。
3. 决定成败的不是单个技能，而是组合编排
单个技能写得再好，只能证明“工具能用”；真正让Agent显得“聪明”的，是把多个技能按正确的顺序串起来，形成一条完整的工作流。agent-skills项目把我逼到最痛苦的地方，也恰恰是这里——组合编排。
以最典型的“数据分析+报告输出”场景为例，一次完整的任务大概需要这样一串动作：
- 解析用户意图，确认数据范围和时间粒度；
- 调用查询技能，获取原始数据；
- 调用异常检测技能，标记异常波动点；
- 调用报告生成技能，把结果整理成结构化文本；
- 调用消息推送技能，把报告发送到指定群。
如果你让模型自由发挥去调这些步骤，它大概率会在第2步和第3步之间天马行空，比如突然去调一个毫不相干的“客户信息查询技能”。所以我在编排层引入了一个轻量级的“计划器”，它不直接调用工具，而是先输出一个执行计划（plan），将任务拆解成有序的子步骤，每一步都指定应该用哪个技能。
def execute_plan(plan, ctx): results = [] for step in plan.steps: skill = registry.get(step.skill_name) if not skill: ctx.log.warning(f"跳过未注册技能: {step.skill_name}") continue result = skill.execute(ctx, **step.arguments) results.append(result) # 关键：把上一步的结果作为上下文传给下一步 ctx.update_context(step.skill_name, result) return results这个循环看起来简单，真正起作用的是update_context这一步。它保证了后面的技能能看到前面技能的输出，模型不会“失忆”。我在实际使用中发现，如果不做这个上下文传递，模型经常会把前面已经查出来的结果忘了，然后重新查一遍，或者拿中间过程的假设数据去做后续计算，错误率直接翻倍。
3.1 分支与回退：Agent面对错误时的优雅姿势
编排层还有一个绕不开的话题：技能执行失败了怎么办。很多Agent应用一遇到工具报错就直接把错误信息抛给模型，让模型“看着办”。这是个坏做法——模型看到错误后往往会产生幻觉，编一个根本不存在的结果出来。
我的做法是在编排层加分支策略。具体来说，当某个技能执行失败时，按照优先级依次处理：
- 重试一次：如果错误是超时或临时网络抖动，重试往往有效；
- 降级到替代技能：比如主力查询技能挂了，自动切换到备份查询接口，或者用离线缓存的近似数据；
- 显式返回“无法完成”：如果降级也不行，就如实告诉用户“这个任务目前无法完成，原因是xxx”，而不是让模型编一个假结果。
这套分支逻辑让Agent在非理想情况下也能保持诚实。工程上，“能力不行但诚实”比“能力不行但爱编”要好一万倍——至少用户信任你不会被消耗殆尽。
3.2 并行技能的可行性与收益边界
一个自然浮现的优化点是：当多个技能彼此之间没有依赖关系时，能不能并行执行来缩短总耗时？比如同时查销售数据和查广告数据，完全可以各自跑各自的。
技术上没有问题，但有个收益边界需要心里有数。我实测下来，当并行技能不超过5个时，收益明显；超过5个以后，收益会被线程切换、资源竞争、以及下游汇总逻辑的复杂度给吃掉。而且，并行还会带来一个副作用：多个技能同时返回后，模型需要对结果做汇总，这时候上下文会变得很拥挤，反而更容易出错。
所以我的建议是：先串行跑通，再考虑并行。并行是优化手段，不是默认选项。
4. 让Agent在实战中“长出”新技能：组织级的技能演化机制
agent-skills这个名字里有个“skills”是复数，它天然暗示了一件事：技能集合不是静态的，它会随着业务发展不断生长。一个合格的项目，必须为“新技能如何被发现、被沉淀、被复用”提供一套机制，否则每个业务线都在各自造轮子，Agent的能力池就是一盘散沙。
4.1 从一次手动操作中发现新技能
我们的做法是给Agent加了一个“技能沉淀”循环。过程是这样的：
- 当模型在计划中生成了一步操作，但注册表里找不到匹配技能时，把这步操作记录到“未覆盖需求池”；
- 运营或研发定期review需求池，把那些高频出现、重复发生的操作提炼成一个新的技能；
- 新技能写完之后，走一次评测流程，拿历史数据验证准确率，达标后再注册进正式技能表。
这套循环跑起来之后，最明显的变化是技能数量的增长不再靠拍脑袋，而是跟着真实用户需求走。之前我们是“有什么工具就给Agent配什么技能”，现在变成了“用户需要什么动作，我们就去开发什么技能”。方向完全反过来了，但效果天差地别。
4.2 技能质量怎么评估：别只看调用成功率
我给技能质量建了一套评估维度，想分享给大家参考。传统的工具调用测试只关注“它成功返回了没有”，这远远不够。我的评估框架有四个维度：
| 维度 | 衡量内容 | 我的达标线 |
|---|---|---|
| 调用成功率 | 技能执行过程中没有报错 | ≥98% |
| 结果准确率 | 返回数据和真实值一致，不编造 | ≥95% |
| 语义匹配率 | 模型是否在正确的场景下调用此技能 | ≥96% |
| 端到端贡献 | 该技能是否真正帮助用户完成了任务 | 定性评估+用户反馈 |
这里特别说一下语义匹配率。技能注册表里如果描述写得模糊，模型就会在错误的场景下调它，比如“查询订单”和“查询物流”描述里都写了“查订单”，模型就分不清了。后来我把两个技能的description分别细化成“订单金额、商品明细、支付状态”和“物流轨迹、配送节点、预计到达时间”，语义冲突立刻缓解了。这个细节可以直接抄。
5. 落地过程中的几个反直觉经验
项目做到后期，我踩了一些听起来反直觉但实际非常深刻的坑。最后把这些经验整理出来，希望能帮后来人少走弯路。
5.1 技能越“薄”越好，不要把业务逻辑写进技能里
这是我吃过亏之后得出的结论。早期我把一个“生成周报”的技能做得非常厚，里面塞了取数逻辑、计算逻辑、排版逻辑、文案逻辑，结果每次业务规则一变，这个技能就要大改，而且单个技能过大，模型的调用和调试都非常困难。
后来我把它拆成了“查数据”“做分析”“写摘要”“组装文档”四个薄技能，由编排层把它们串起来。每个技能只干一件事，干得干净利落。这样拆完之后，单个技能的复用度大幅提升，“查数据”被其他好几个场景复用上了。技能设计的原则应该是“职责单一”，跟微服务拆分的道理一模一样。
5.2 必须给技能加“状态”，否则Agent是个失忆症患者
这个观点我在前面反复提过，但值得单独再说一次。无状态的技能函数就像不带钱包出门的人，每次都要重新回家拿钱。技能的调用必须能感知当前会话、当前任务、当前上下文。
我用了一个简单的全局上下文对象来维护状态，它至少包含：
session_id：当前会话的ID，用于追踪整个对话历史；task_stack：当前任务拆解成的子步骤栈；memory：一个轻量的KV存储，记录已获取的信息；permissions：当前调用者的权限集，技能执行前做鉴权。
有了状态，技能才能在不同的调用间共享信息，Agent才谈得上“连续性”。没有状态，每个技能调用都是一座孤岛，模型永远在做重复建设。
5.3 Prompt里全塞技能描述不如结构化定义
最后一个经验，别把技能描述当成某种“Prompt工程技巧”去随便写。技能描述的结构化程度直接决定了模型对技能的利用率。我发现下面这种写法比一长串自然语言描述更稳：
- 开头一句话说明技能职责；
- 中间列出关键参数和行为约束；
- 结尾明确侧效应（副作用）；
- 参数用JSON Schema表达，而不是口语化说明。
比如input_schema写清楚了参数类型和格式，模型就会规规矩矩传2025-01-01，而不是传January 1st给它，然后返回一个校验失败。这类格式化的定义虽然写的时候麻烦点，但对模型是实打实的友好。
5.4 涉及敏感动作的技能，一定要走“人工确认”环节
这也是我在实际业务里被逼出来的设计。某些技能虽然看起来人畜无害，比如“发送邮件到客户”“修改订单状态”“执行生产环境脚本”，一旦模型误判调用了，后果不堪设想。所以我给这类技能加了一个requires_confirmation=True的标记。
执行流程变成：编排层发现技能需要确认，先把动作描述和目标数据返回给用户，等用户确认后再真正执行。这个“问一句”的动作，在很多时候就把事故化解在萌芽状态了。对应到代码实现，其实就是在执行循环里加一个分支判断，遇到需要确认的技能就挂起等待，信号量置位后再放行。
6. 从项目里趟出来的几条硬指标
做agent-skills这个项目，我最大的感受是：Agent应用开发跟传统后端开发最不一样的地方在于，你面对的是一个概率系统，不是确定性系统。模型每次调用同一段Prompt，结果都可能不一样。这个底层逻辑决定了我们做技能层时，永远要考虑“如果模型选错工具怎么办”“如果技能返回异常怎么办”“如果用户输入有歧义怎么办”。
也因此，我给自己的技能层设了两条硬指标，建议每个做Agent的团队也抄一下：
- 任何技能都不能静默失败：要么返回正确结果，要么返回明确错误，禁止吞异常、禁止返回空壳数据。
- 任何技能调用必须可追踪：从模型决定调哪个技能，到技能执行的入参、出参、耗时、错误信息，全链路日志一条不能少。出了线上问题，你能五分钟之内定位到是哪一步、哪个参数、哪个分支导致的。
这两条当时帮我节约了无数的Debug时间。模型的行为不可控，但日志可以做得足够细，细到你从日志里就能还原出模型当时的“思考轨迹”。这个对线上Agent尤其重要——它不是给你一个人用的demo，是几十上百个人每天都在用的生产系统。
如果让我重新做一遍，我可能不会再从“选个大模型”开始，而是从“梳理清楚我的Agent需要哪些技能”开始。模型型号差一点可以在调度层弥补，技能层设计得一塌糊涂，再强大的模型也救不回来。
