Agent Skills 实战：从工具调用到稳定技能编排

我见过太多Agent项目翻车现场了。模型换得再大，Prompt写得再花，一碰到具体业务场景还是抓瞎。原因通常只有一个：Agent手里没有真正趁手的“家伙”。这个“家伙”就是Agent Skills，也就是给Agent注册的、能明确识别并被稳定调用的一组专业能力单元。项目标题“agent-skills”看起来像是一个工程命名，但内核是一个很现实的命题：怎么把Agent从“什么都会一点”变成“关键场景能顶住”。这篇总结我想从设计思路、技能结构、实操落地到问题排查，完整拆一遍我在这套体系上踩过的坑和沉淀下来的做法，适合正在做Agent应用、被工具调用折腾得不轻的工程师，也适合想弄明白Skills到底比普通工具调用强在哪里的产品和技术负责人。

1. Agent Skills到底解决什么问题

1.1 一个触发我关注Skills的现场

前段时间，某位开发者找到我，说他的客服问答Agent有个老毛病：用户问“我这个月的账单怎么比上个月高”，Agent回答得头头是道，但给的数字经常对不上。后来我让他把SQL取数、报表解析、异常波动解释这三件事拆成三个独立的技能模块，分别描述清楚适用场景和入参格式，再让Agent按需调用，准确率很快就上来了。

这个案例很典型。它暴露的本质问题是：之前的Agent像一个只会背口诀的实习生，所有知识都堆在上下文里，遇到问题时靠临场发挥。而引入Skills之后，它变成了一个带工具箱的老师傅，每个工具对应一类明确任务，什么时候用、怎么用、用完怎么收尾，全都有章法。

之所以强调“独立技能模块”，是因为我发现很多项目在早期把所有能力都塞进一个函数列表里，看起来有十几个工具，实际调用时Agent根本分不清哪个负责什么。Skill体系的出现，就是强制你把这些能力做一层更规范、更带“使用说明”的封装。

1.2 Tools、Skills和普通Prompt的本质区别

很多人会问：Agent Skills不就是工具调用（Function Calling/Tools）吗？这句话对了一半。工具调用是底座，Skills是在底座之上加了两个关键层：一个是更严格的技能声明，另一个是技能间的编排和复用。我用一张对比表来说明：

普通Prompt的局限更明显。你把“你会检查账单异常”写在系统提示词里，模型也只是“知道”这件事；但你把“账单异常分析”做成Skill，它就变成一个可执行、可反馈、可回归测试的独立单元。知道一件事和能稳定做成一件事，这是Prompt和Skill的根本区别。

用生活类比的话，Prompt是给员工看岗位职责说明，Tools是给他发一堆没贴标签的工具，Skills则是给每件工具贴上操作手册并告诉他“什么场景拿哪个”。后者看起来繁琐，但真正出活的是它。

1.3 什么阶段需要认真考虑Skill体系

我见过不少团队在一开始就拼命堆技能，结果收益很低。根据我的经验，出现下面三类信号时，才真正值得上Skill体系：

• 同一个能力要在多个Agent或场景里复用，且每次复制粘贴都容易出现行为偏差；
• 工具结果占用的上下文太多，导致Agent经常“忘记”用户真正的问题；
• 线上出现“同一类问题十次回答九次不同”的稳定性问题，尤其是需要精确计算、格式化输出的场景。

如果你只是做一个几天就上线的Demo，用普通函数调用就够了。Skills解决的是规模化、可维护和可度量的问题，不是用来给简单场景增加仪式感的。

2. 技能系统的结构设计与核心细节

2.1 一个技能文件长什么样

业界常见的Skill实现方式，是把每个技能做成一个目录，内含描述文件、实现代码和测试用例。我习惯用一组精简的配置来表示，用一个叫“账单异常分析”的技能举例：

name: bill_anomaly_analyzer description: 分析用户账单金额波动，输出波动原因和置信度。仅在用户对费用金额有疑问时使用。 trigger_conditions: - 用户提到账单金额变化 - 用户对扣费明细有疑问 input_schema: bill_id: type: string description: 账单编号 compare_period: type: string enum: [month_over_month, year_over_year] description: 对比周期类型 output_schema: anomaly_items: type: array items: item_name: string delta: number reason: string summary: type: string max_output_tokens: 300

这个文件的核心并不在参数定义，而在description和trigger_conditions。很多初版Skill失败，都是因为描述写得像API文档，模型根本不知道什么时候该调它。好的技能描述应该包含：任务边界、适用场景、典型入口说法。

2.2 技能元数据的设计原则

技能元数据是给模型看的说明书。我在做了几十个Skill之后，总结出四个必须遵循的原则：

第一，描述要素要包含“任务边界”。所谓边界，就是写明“这个技能负责什么、不负责什么”。不要小看这个细节。模型在判断调用时，如果技能描述里全是能力宣传，它会把什么都往这个技能上靠；反过来，你写清楚了边界，误调用率能降一半以上。

第二，参数必须给“示例值”。很多团队只写参数类型，不写示例。结果模型生成的入参格式经常不对，比如日期写成了“昨天”而不是具体的“2025-06-01”。在参数描述里塞一个example: "2025-06-01"，模型生成合规入参的概率会高很多，这是代价极低、收益极高的优化。

第三，输出约束要写“给Agent看的摘要格式”。不要让技能把原始返回全部丢回给Agent。我通常在output_schema里设定一个summary字段，让技能内部把结果浓缩成几行关键信息。因为上下文是最贵的资源，让Agent读一百行原始数据再让它总结，远不如在技能里做好总结再抛回去。

2.3 为什么技能要“声明式”而不是“命令式”

所谓声明式，就是我只描述“这个技能是什么、接收什么、返回什么”，不描述“你必须在第几步调用它”。命令式的做法是写死流程：先调A再调B再调C。这两种模式应对的场景完全不同。

命令式流程适合稳定不变的内部链路，但Agent面对的往往是变化多端的用户表达。声明式技能的好处是，Agent可以根据当前对话状态动态决定调用顺序，甚至在一次任务中多次调用同一个技能。

我还发现，声明式技能更容易做单元测试。因为每个技能不依赖外部流程状态，你把一个输入丢进去，它就应该给出符合output_schema的输出。这种可测试性，是后面做技能质量管理的基础。

3. 实操：从零注册一个可用的Agent技能

3.1 落地的选型思路

技能体系一般依赖具体的Agent框架或SDK。我的建议是：不要迷信大而全的框架，先画清楚自己的调用场景，再选一个能快速验证的方案。以我的习惯，我会先用一个支持技能注册的轻量SDK跑通端到端，再决定要不要引入更重的编排引擎。

选型时我会重点看三件事：第一，SDK是否支持技能的动态加载，也就是新增技能不用重启整个服务；第二，是否支持技能结果的流式反馈，因为有些技能执行时间很长；第三，是否有现成的调用链日志，这直接决定了线上排查成本。

3.2 把“触发直觉”训练好

技能系统里最玄学也最关键的部分，就是Agent能不能“一眼看出”该调用哪个技能。训练这种触发直觉，靠的是两样东西：技能描述和召回入口。我分享一个自己打磨描述的实操流程：

第一步，先写一个“差生版本”。也就是把想到的能力点全塞进去，不讲究措辞。然后丢几条真实用户问题，观察Agent的调用命中率。

第二步，根据失败case修改描述。如果该调用的没调用，就在trigger_conditions里补上用户可能的口语化表达；如果不该调用的调用了，就在description里补负面样本，比如“不要用它来查询账户余额”。

第三步，反复跑一个固定的回归集。我平时维护着大约50条测试问题，每次改描述都要全部跑一遍，保证修了东墙不塌西墙。

这套方法和训练搜索引擎的意图识别其实是同一个逻辑，只不过对象从搜索词变成了对话上下文。

3.3 技能内部实现的关键代码

技能描述写得再好，最终还是要落地为可靠的执行代码。我习惯用Python来实现技能逻辑，加上类型标注和反馈状态。下面是一个简化但完整的技能实现骨架：

# skills/bill_anomaly_analyzer/skill.py from typing import Any import json class BillAnomalyAnalyzerSkill: def __init__(self, config: dict): self.db_client = config["db_client"] self.metrics_client = config.get("metrics_client", None) def invoke(self, params: dict[str, Any]) -> dict[str, Any]: bill_id = params.get("bill_id") compare_period = params.get("compare_period", "month_over_month") # 1. 参数预校验 if not bill_id: return self._error("缺少bill_id参数") # 2. 查询账单数据（真实项目会加缓存与降级） bill_data = self._query_bill(bill_id) # 3. 核心计算逻辑，异常波动检测 anomalies = self._detect_anomalies(bill_data, compare_period) # 4. 输出压缩，只返回对Agent有用的摘要 return { "status": "success", "summary": self._build_summary(anomalies), "data": anomalies[:5], } def _query_bill(self, bill_id): # 这里走数据访问层，注意超时控制 return self.db_client.query(bill_id=bill_id) def _detect_anomalies(self, bill_data, compare_period): # 波动率计算，用阈值识别异常项 result = [] for item in bill_data["items"]: current = item["current_amount"] previous = item["previous_amount"] if previous <= 0: continue delta_ratio = (current - previous) / previous if abs(delta_ratio) >= 0.2: result.append({ "item_name": item["name"], "delta": round(delta_ratio, 4), "reason": "较上期波动超过20%阈值", }) return result def _build_summary(self, anomalies): if not anomalies: return "未发现超过阈值的异常波动项。" return f"发现{len(anomalies)}项异常变动，其中波动最大的是{anomalies[0]['item_name']}，变化率{anomalies[0]['delta']:.1%}。" def _error(self, message): return {"status": "error", "summary": message}

这个代码里最关键的是第4步，也就是输出摘要。我见过的失败案例里，有相当一部分是技能返回了大量原始数据，把Agent“淹死”了。技能应该像一名汇报工作的下属，只说结论和必要证据，而不是把Excel整个甩给老板。

3.4 注册与验证的完整流程

技能实现完，我不会马上接进Agent正式链路，而是先做三个层面的验证：

第一层，单元验证。直接调用技能的invoke方法，传入畸形的、正常的、缺参数的三类输入，确认返回格式稳定。

第二层，Agent级验证。把技能注册进测试Agent，用一组真实但脱敏的用户问题跑对话。这里重点看“调用时机”和“调用参数”是否合理。

第三层，回归验证。把新技能和原有技能放在一起跑一遍完整回归集。这一步最容易被忽略，但它能发现技能之间的描述冲突。

注册环节的关键操作就是把技能目录挂到SDK的加载路径下，并执行一次技能列表检查。通常我会在启动脚本里加一条如下命令：

agent-skill-cli list

如果输出里能看到新技能的名称、版本、描述摘要，就说明注册成功。记得顺手把技能的版本号打出来，方便后续回溯。

4. 技能运行时的调用机制与上下文管理

4.1 Agent是怎么把任务分配给技能的

写清楚技能只是第一步，运行时的分配机制才是真正的考验。当前主流做法是让Agent先做一次轻量规划，把用户指令拆解成技能调用序列。这个过程的本质是“意图路由”。

意图路由做得好不好，主要看三个环节。一是候选技能数量。我建议单一场景下的候选技能不要超过十个，超过十个之后模型的选择准确率显著下降，需要分级分组。二是技能描述的区分度。两个技能如果描述高度相似，模型经常随机选一个。三是上下文衰减。如果对话轮次过长，模型可能忘记某个技能的存在，所以有些实现会在每轮把技能清单重新注入一次。

这里有一个非常实际的调优手段：在触发条件中加“排除条件”。比如账单分析技能里写明“不要用于余额查询”，这等于提前给意图路由打了补丁，比在代码里硬编码规则更灵活。

4.2 多技能协作与冲突处理

真实项目很少只靠一个技能。多技能协作时，我会遵守一个底线原则：技能之间不要互相依赖。A技能不要代调B技能，所有编排都交给Agent路由层去完成。

为什么这么设计？因为如果技能之间互相调用，调用链就变成一条不可控的网状结构。一旦某个技能出现超时或异常，错误定位会非常困难。相反，所有技能保持扁平和无状态，Agent每次只做一次决策，异常链路就好排查。

多技能冲突处理同样值得提前想清楚。最常见的情况是，用户的一个问题同时命中多个技能。比如用户说“为什么我上个月和这个月费用不一样而且余额也不多”，这时账单分析和余额查询两个技能都在候选列表。我会在技能描述里明确各自的任务边界，并在路由层设置优先级，让“费用波动解释”优先于“余额查询”。这样做不是限制Agent能力，而是保证它先回答用户更关心的核心诉求。

5. 常见问题与排查技巧实录

5.1 高频问题速查表

5.2 我在排查过程中养成的三个习惯

做技能系统以来，我养成了三个能救命的习惯，值得记下来。

第一个习惯是所有技能都要写日志。而且不是简单的成功失败，是记录调用参数、模型决策结果、技能返回摘要三件套。这样每次线上问题，都能回答“模型当时看到了什么”“它决定调用什么”“工具返回了什么”。

第二个习惯是保留技能的“影子模式”。简单说，线上业务继续走旧链路，新技能在旁路模拟运行，只记录结果不下发执行。我用这个方式积累了大量真实case，用来完善技能描述。效果非常明显，改版后的技能上线即稳定。

第三个习惯是定期查看技能命中分布。如果发现某个技能一个月都没被调用一次，我大概率会把它下线或者重组，因为技能数量越少，其余技能的命中准确率越高。这里面有个典型的“数量-质量”权衡：并不是技能越多越好。

5.3 两个印象深刻的翻车案例

第一个案例是关于输出格式的。我们曾经做了一个报表生成技能，模型总是把结果渲染成带“单位”的文本，但下游系统只接受纯数字JSON。排查了整整两天，最后发现是技能output_schema里少写了一个unit字段的枚举约束。从那以后，我给所有输出字段都规定了严格类型，甚至在关键字段上加了正则校验。

第二个案例发生得非常低级但很值得分享。有一个技能，测试环境一切正常，一到线上就偶尔调用失败，而且时间是随机性的。后来看日志才发现，线上服务重启时技能目录权限没有继承，导致间歇性加载失败。那次之后，我把技能加载结果加入服务健康检查，只要技能列表不完整就直接拒绝上线。

6. 进阶：技能编排与质量度量

6.1 把技能当产品来迭代

做完第一个能稳定跑通的技能系统后，我开始把它当产品来经营。每个技能都有版本号、负责人、更新日志和健康度指标。我强烈建议团队在技能数量超过十个时，就引入这套机制，否则很快会因为技能无人维护而腐烂。

一个技能的健康度，我主要看四个指标：

• 调用命中率：该技能被正确调用的次数 / 它出现在候选列表的次数；
• 执行成功率：技能代码正常运行并返回status=success的比例；
• 结果采纳率：Agent在收到技能返回后，最终回答引用该结果的次数占比；
• 回归通过率：固定回归集上的测试通过比例。

这四个指标不需要做得很重，关键是形成固定的观察节奏。我一般是每周跑一次回归集，每月复查一次指标趋势。

6.2 技能编排模式的演进

单技能阶段之后，必然会走到编排阶段。我的建议是从简单的“顺序编排”开始，不要一上来就做复杂的条件分支和循环编排。

先让Agent按顺序调用技能A、B，观察前面的输出如何影响后面的调用。稳定之后，再加入条件判断，比如“如果A返回异常，则转调用C”。再往后，可以尝试并行调用彼此独立的技能，减少整体延迟。

我特别想提醒的是，编排逻辑不要写死在Agent代码里。把这些编排规则下沉为可视化配置，或者在描述文件里以编排指令的形式声明。这样做的好处是，调流程不需要发版本，改配置就能生效。

6.3 给技能加一个“退出机制”

很多团队只关注技能怎么进，不关心技能怎么退。我一直认为，一个健康的技能系统必须包含下线机制。当一个技能的连续回归通过率低于某个阈值时，应当自动标记为非候选状态，不再参与意图路由。

这背后是一个很朴素的想法：技能系统本质上是一个可进化的工具库，它必须有能力丢弃坏工具，保留好工具。如果不加退出机制，技能库会逐渐积累一堆“偶尔能跑通但不可靠”的能力，最终拖垮整个Agent的稳定性。

我在落地时会给每个技能加一个status字段，取值是active、shadow、deprecated三种。转正、影子测试、下线都走标准流程。这套机制看起来多花了一点管理成本，但它避免了线上最可怕的“玄学问题”。

最后分享一个小技巧：技能描述写完后，大声读一遍，如果念起来像人话，说明Agent也更容易理解。我见过太多写满术语的技能描述，模型调用时抽风，人看的时候头疼。把描述当作用户手册来写，往往比堆技术名词更有效。这套“agent-skills”的体系，说到底就是在帮Agent变得更像懂行的协作者，而不是一个碰运气的问答机器。