上个月我去看一个内部 Agent 项目的时候发现系统 prompt 已经膨胀到了六千多 token里面塞了十几个工具说明、使用范例、边界提醒、输出格式要求看起来“很全面”实际效果却越来越不稳定——模型经常在相似工具之间反复横跳有时干脆自己编字段名。后来我把这套逻辑整个拆掉换成了可插拔的“技能”目录也就是标题里写的 agent-skills。这套架构的核心是把 Agent 的能力从一段拥挤的文本变成一组独立注册、独立测试、独立升级的模块。这篇文章不会给你讲概念课而是完整复盘我在这个项目里干过的活儿技能注册表怎么设计、一个真实技能怎么写、评测集怎么搭、上线后踩过哪些坑以及最后怎么把技能当代码库维护。适合正在被长 Prompt 和工具调用折磨的 Agent 开发者也适合准备把 Demo 推向生产环境的人。1. 为什么要为 Agent 单独引入“技能层”而不继续堆 Prompt1.1 长 Prompt 失控的三个典型症状我接手这个项目的时候最直观的异常是请求延迟一直在涨。看调用链发现每次对话都要把六千多 token 的 system prompt 完整送进模型加上用户消息和中间结果一次请求的输入经常过万 token成本是小事响应慢才是用户能感知到的问题。但真正麻烦的不是 token 数量而是质量在下降。我把线上日志拉出来人工抽了两百条失败样本发现三类问题特别集中。第一类两个功能描述相近的工具被搞混比如“读取数据库表结构”和“读取数据库表数据”模型经常在应该调后者的场景里调了前者报错之后才开始自我纠正。第二类工具参数开始“幻觉”模型会传一个 schema 里根本不存在的字段名或者把日期格式从YYYY-MM-DD自由发挥成YYYY/MM/DD脚本端只能报 ValueError。第三类同一个能力在不同场景下的表现不稳定有时候模型记得要先做权限校验有时候又跳过。这三类问题的根子是同一个信息都堆在一段文本里模型处理长文本时注意力必然会被稀释。越靠后的工具说明被“想起”的概率越低而 prompt 每增长一千 token这种稀释就越严重。我当时的结论是继续往 system prompt 里加规则已经是一条死路信息需要结构化的载体。1.2 技能化拆分的核心思想把能力装进带说明的独立黑盒agent-skills 的做法是给 Agent 提供一层“能力目录”。每一项能力不是一个孤立的函数而是一个完整的技能包包含四样东西一段给模型看的触发说明、一份输入输出的结构化约束、一段可执行脚本、一批评测用例。Agent 收到用户请求时会先根据技能描述做意图匹配选出最合适的一个或几个技能再按技能内部的步骤去执行。整个过程对 Agent 来说像是一个实习生拿到了一本操作手册先翻目录找“什么事该找谁”再翻到具体章节看“需要准备什么材料”。而不是像之前那样把所有操作规范全塞进一句话里让人背。这样做的好处第一是隔离。技能 A 的脚本出了问题不会影响技能 B 的声明和调用。第二是复用。同一个技能可以被不同 Agent 挂载不用每个项目都重写一段 prompt。第三是可测试。每个技能有独立评测集改完能立刻知道是变好了还是变坏了。这一点在后面的实践中被反复证明是所有收益里最值钱的一个。1.3 和 function calling 不是一回事别搞混很多朋友会问这不就是 function calling 吗我用了一段时间之后可以明确说这两者是包含关系不是替代关系。function calling 解决的是“模型如何把语义映射到一次函数调用”的问题它本质上还是一个原子函数的透传层描述、参数、返回都写在函数定义里模型只能看到名字和注释缺少系统性的边界管理。而 agent-skills 是在 function calling 上面加了一层编排与治理。一个技能内部可以有多个执行步骤也可以组合多个底层函数还能定义自己的输入输出协议。可以用一张表说明区别维度堆 Prompt 方案function callingagent-skills信息载体长文本函数定义块技能包描述脚本评测能力粒度模糊的混合体单一原子函数一组相关能力与流程测试方式人工看对话效果单测函数逻辑意图命中参数执行输出全链路评测升级影响改一处可能全崩影响全局声明只影响挂载该技能的场景跨项目复用基本不可复用复用难度高目录级复制即可我现在的习惯是底层还是用 function calling 来绑定原子操作但上层所有和“场景”相关的逻辑全部抽象成技能。这样分工之后调试的定位就变得很清楚意图错了去看技能描述脚本错了去看技能实现都不需要再去翻一大段 prompt 碰运气。1.4 什么场景才值得做成技能什么场景不值得技能化也不是银弹项目中我逐渐总结出值得做和不必做的边界。值得做成技能的能力通常具备三个特征任务边界清晰比如“生成月末报表”和“回答开放问题”的边界完全不同重复频次高至少一周会被触发多次输入输出可结构化能定义出明确的参数和返回格式。数据查询类、报告生成类、通知推送类、文档格式转换类都是天然适合技能化的场景。反过来那些高度开放、探索性很强、过程不可控的任务就不适合硬塞进技能体系。比如让 Agent 帮用户做头脑风暴、写散文、分析一个不熟悉的业务问题这种场景核心价值在推理链上强行套结构反而会限制模型发挥。我给团队定的原则是技能服务于确定性prompt 服务于开放性两者各管一摊谁也别想越界。2. 技能注册表怎么设计让“描述”本身成为可评测的资产2.1 先写一份能落地的 SKILL.md 清单我见过不少人做技能化第一步就写执行脚本结果最后挂在“模型根本不知道该什么时候用这个技能”上。这个顺序是反的。正确顺序是先写技能的描述清单再写脚本因为描述决定了技能能不能被准确命中脚本只是命中之后的事。我的技能包固定包含一个SKILL.md文件核心字段如下name: monthly_report_aggregator description: 汇总指定月份的销售数据计算环比与同比生成月度报告文件。 当用户提到“月报”“月度汇总”“上个月业绩怎么样”时使用。 when_not_to_use: 如果用户只是询问单日销量或希望实时查询最新数据不要使用本技能。 本技能面向已归档月份的统计汇总不处理实时数据。 input_schema: type: object required: [month] properties: month: type: string description: 目标月份格式为 YYYY-MM例如 2025-02 compare_with_prev: type: boolean description: 是否计算环比默认 true compare_with_last_year: type: boolean description: 是否计算同比默认 false output_schema: type: object required: [summary_text, report_path] properties: summary_text: type: string description: 一段可以直接展示给用户的汇总摘要 report_path: type: string description: 生成的报告文件路径 steps: - 解析并校验参数中的 month - 从销售数据库读取该月全量订单数据 - 计算总销售额、订单量、客单价 - 拉取对比月份数据计算环比与同比 - 渲染月度报告 Markdown 文件并保存 - 返回摘要文本与文件路径when_not_to_use这个字段我特别想强调一下。绝大多数人写描述只写正向触发条件但实际项目里两个技能打架往往不是因为正向外表太弱而是因为负向边界没划清。给模型明确规定“什么时候不要用”比反复强调“什么时候应该用”更能降低误命中。2.2 description 是给模型读的别只给人看写技能描述要时刻提醒自己读者不是开发者而是语言模型。人看描述会关注“这个功能怎么实现的”模型只关心“用户说的哪句话和这段描述匹配”。所以描述里应该尽量包含真实的用户表达。比如想表达“汇总月度销售数据”不要只写“对销售数据进行月度聚合”而要写“当用户提到‘月报’‘月度汇总’‘上个月业绩怎么样’‘这个月卖了多少钱’时使用”。这里有一个非常实用的技巧把种子评测集里的标注 query 直接融进描述里。我每次写完一组评测用例都会回看一眼 SKILL.md发现哪些表达经常出现而描述里没有就补进去。几轮迭代下来技能命中率提升非常明显而且描述会越来越贴近用户的自然语言而不是停留在工程师的书面语里。2.3 schema 要“紧”到什么程度参数才不会乱飞参数 schema 的正确设计原则是能枚举就不开放能给默认值就不让模型自由发挥每个字段必须有雏形语义说明和示例值。以month字段来说如果只在 JSON Schema 里写type: string模型有可能输出成2025-2、2025年2月、February 2025等花式变体。我的做法是加两层防护。第一层在 schema 的description里写死格式示例比如例如 2025-02第二层在脚本入口做严格校验不符合YYYY-MM就直接抛错并返回可读的错误信息。这等于给 Agent 配了一个敢说话的搭档错了就明确告诉我错哪了而不是默默返回空数据。更“紧”的做法是对于一些固定选项直接使用枚举类型。比如报告类型只有summary、detail两种就写成枚举。这样模型压根没有自由发挥的空间。我现在的经验是参数 schema 宁可设计得繁琐一点也不想上线之后天天去日志里捞参数解析异常。2.4 技能编排组合多个技能时要画清依赖关系单技能只能覆盖一个原子场景真实业务里更多是组合场景。比如“把上周的数据汇总发到群里”就涉及两个技能数据汇总技能和消息推送技能。如果不做编排设计Agent 可能执行完汇总就停下或者自己绕弯子。我的做法是在技能包里增加一个可选的dependencies字段声明执行前需要先完成的技能并在运行时用 DAG有向无环图来管理顺序。这个结构不一定需要复杂的引擎简单的拓扑排序就够了。关键是让技能之间具备可组合性这样每新增一个技能不是从零开始而是复用已有积木。也要小心不要让依赖链闭环比如技能 A 依赖 BB 又依赖 A这种循环依赖要在注册时直接拒绝。3. 从零写一个能上线的技能月度数据汇总的完整实现3.1 技能目录结构怎么摆下面我把刚才那个monthly_report_aggregator展开成实际可跑的工程结构目录如下skills/ monthly_report_aggregator/ SKILL.md run.py requirements.txt eval/ cases.jsonlSKILL.md负责给模型看的描述和约束run.py负责真正干活requirements.txt声明依赖eval/cases.jsonl放评测集。我坚持把技能做成一个独立的文件夹原因很简单后续复制到其他 Agent 项目时只拷贝目录即可所有相关信息都收拢在一起不会散落在多个配置里。3.2 先把 SKILL.md 写稳定再碰代码SKILL.md 前面已经给过完整样例这里补充几个实践中总结的细节。描述中的steps字段要给模型一个执行顺序的暗示但它不是无脑照做的脚本而是帮助模型理解技能内部流程的指南。尤其当技能内部脚本会自动完成多步任务时描述里写清“脚本会自动完成从统计到渲染的整个过程”反而能防止模型在返回结果后又画蛇添足去多调一次脚本。另外SKILL.md开头我都会加一个last_updated字段。不要小看这一行它在我们排查问题的时候帮了大忙。线上模型缓存了旧描述而技能已经升级很多奇怪的“技能不起作用”最后都指向版本不一致。有last_updated一眼就能看出是不是缓存的问题。3.3 执行脚本把参数校验和结果结构放在第一位下面是run.py的骨架代码刻意把逻辑简化重点展示结构月度销售数据汇总技能执行脚本. import argparse import json from datetime import datetime VALID_MONTH_RE r^\d{4}-(0[1-9]|1[0-2])$ def validate_params(params: dict) - None: month params.get(month) if not month or not __import__(re).match(VALID_MONTH_RE, month): raise ValueError(fmonth 参数格式错误应为 YYYY-MM实际收到: {month}) if compare_with_last_year in params and not isinstance(params[compare_with_last_year], bool): raise ValueError(compare_with_last_year 必须是布尔值) def load_sales_data(month: str) - list: # 这里简化成假数据实际项目中会去查数据库 return [ {order_id: A1001, amount: 1200.5, created_at: 2025-02-01}, {order_id: A1002, amount: 860.0, created_at: 2025-02-03}, ] def compute_metrics(month: str) - dict: orders load_sales_data(month) total_amount round(sum(o[amount] for o in orders), 2) order_count len(orders) avg_amount round(total_amount / order_count, 2) if order_count else 0 return {total_amount: total_amount, order_count: order_count, avg_amount: avg_amount} def run(params: dict) - dict: validate_params(params) month params[month] metrics compute_metrics(month) report_path f/tmp/monthly_report_{month}.md with open(report_path, w, encodingutf-8) as f: f.write(f# {month} 月度报告\n\n总销售额: {metrics[total_amount]}\n订单数: {metrics[order_count]}\n) return {summary_text: f{month} 总销售额 {metrics[total_amount]}订单 {metrics[order_count]} 笔, report_path: report_path} if __name__ __main__: parser argparse.ArgumentParser() parser.add_argument(--params, typejson.loads, requiredTrue) args parser.parse_args() print(json.dumps(run(args.params), ensure_asciiFalse))我把validate_params单独拆出来的原因就是要让 Agent 的错误可闻可见。这套架构下Agent 调用技能失败后会自动读取错误信息并尝试自我纠错。如果错误信息是笼统的program errorAgent 根本没有线索去修但如果它看到month 参数格式错误应为 YYYY-MM就能自己把参数改对重试。这个循环在线上帮我兜住了很多参数幻觉问题。3.4 让 Agent 在运行时自动“发现”技能技能目录建好后需要一个注册机制把它们加载进 Agent 的运行环境。我目前用的是一个非常轻量的做法运行时扫描skills/下所有包含SKILL.md的目录解析 YAML 后构建一份技能清单再对描述做 embedding 索引这样用户请求进来时先做向量检索再用模型对 Top-K 候选技能进行精确选择。这一步有一个关键经验不要只靠向量相似度做硬切选择。向量检索召回 Top-K让模型根据完整描述再选一次准确率高一大截。因为向量相似度擅长抓语义近邻但对于when_not_to_use这类负向排除逻辑还是模型直接读描述更可靠。检索加分窄模型做最终裁决这样的分工实测最稳。3.5 用一组种子评测用例倒推技能质量eval/cases.jsonl建议从第一天就开始写哪怕只有五条。每条用例包含用户 query、期望命中的技能名、期望参数、期望输出模式的描述。以月度汇总技能为例{query: 帮我汇总一下2025年2月的业绩, expected_skill: monthly_report_aggregator, expect_args: {month: 2025-02}, expect_output: [summary_text, report_path]} {query: 上个月卖了多少钱, expected_skill: monthly_report_aggregator, expect_args: {month: 当前月份的上个月}, expect_output: [summary_text]} {query: 今天实时销量是多少, expected_skill: do_not_use_monthly_report_aggregator, expect_args: {}, expect_output: []}第三条例我标成了do_not_use这是一个容易被忽略但极其重要的评测类型负向用例。技能体系不仅要测对的时候能命中还要测不该出手的时候稳住手。很多线上误调用问题都是因为负向用例覆盖不够模型在边界场景里“乱帮忙”。种子评测集搭好后后续每个 PR 跑一遍就是技能质量的地基。4. 评测集是技能体系的地基离线回归与线上分流4.1 没有评测集技能改起来心里永远没底技能体系里最容易出现的一种情况是改技能 A 的描述结果技能 B 的命中率掉了。这是因为模型在多个技能之间做选择时所有描述都在同一个上下文中互相竞争。如果技能 A 的描述变得过于宽泛它就开始吞掉属于 B 的场景。这种连锁反应靠肉眼根本发现不了只有评测集能化解。所以我的原则是技能和评测集是一体的没有评测的技能不允许注册。哪怕初期只有五条用例也要把评测跑起来。评测集不是一次性工作它是一个持续积累的资产。每一次线上发现问题都把出问题的对话加入评测集这叫“把 bug 变成回归用例”。我大概花了三周时间评测集从五条涨到两百多条技能的整体通过率从最初的六成多爬到了九成以上。4.2 评测集的结构不只测结果还要测中间过程评测集不是简单的问答对我把它设计成四层断言。第一层是意图命中给定 query期望激活哪个技能如果激活了别的技能就是失败。第二层是参数正确性期望传给执行脚本的参数长什么样重点看字段名、格式、枚举值。第三层是执行成功率脚本到底有没有报错。第四层是输出结构合规性返回值是否满足output_schema该有的字段有没有缺。这四层分开统计有个大好处发现问题时可以快速分层定位。比如意图命中率高但执行成功率低那问题大概率出在脚本侧如果意图命中率本身就低那不用查脚本回去改描述才对。以前我遇到问题总是先怀疑代码逻辑自打分拆后排查顺序变得非常明确浪费在错误方向的精力和以前相比少了很多。4.3 离线跑分的实际效果一张表格看清全局我习惯用一个 CI Job 每晚跑全量评测输出类似下面这张表技能名用例数意图命中率参数准确率执行成功率输出合规率monthly_report_aggregator3694.4%91.7%97.2%100%email_sender2889.3%85.7%92.9%89.3%db_schema_inspector2286.4%81.8%95.5%90.9%global_average8690.7%86.0%95.3%93.0%看到这张表就能明白为什么说评测集是地基。某天晚上我改了一下db_schema_inspector的描述加了一句“可以查看表注释”结果它的意图命中率升了但monthly_report_aggregator的参数准确率掉了两个百分点。仔细一查才发现模型把“查一下销售明细表结构”这个请求误派给了汇总技能。这个教训让我养成了习惯任何技能描述变更都要观察全量评测分数而不是只看被改的那个技能。4.4 线上分流离线全绿不等于线上安全离线评测通过率达标后我仍然不敢立刻全量上线。实际操作中采用灰度策略新技能或者大改的技能先切 5% 的线上流量观察人工反馈、超时率、重试率至少要跑 24 小时。如果这些指标和基线持平再逐步放大到 30%、100%。表面上看这个流程慢了但实际它帮我避开了好几次尴尬的线上事故。比如某个技能离线评测全绿但上线后才发现它返回的报告文件路径权限不对半数用户打不开文件。这种问题离线环境根本模拟不出来只有真实流量能暴露。灰度不是形式主义它是评测集之外的第二道防线我建议想认真搞 agent-skills 的团队步子慢一点后面才快得起来。5. 上线后我踩过的四个坑以及完整的排查过程5.1 参数幻觉模型编了一个不存在的字段名现象是线上日志突然出现一批TypeError: run() got an unexpected keyword argument report_date_range。看报错时我很奇怪schema 里根本没有这个字段。查一下对话上下文发现模型在执行技能前自己从用户话里“推导”出了report_date_range这个参数理由是用户说“给我拉一下这个时间段的数据”。整个排查链路是这样的先看技能注册时用的 schema确认没有report_date_range再看用户的原始 query发现“时间段”这个词触发了模型按字面生成参数最后看 schema 里month字段的 description发现它只写了“目标月份”没有明确写“不要使用日期区间表达式”。修复方案做了两处。第一schema 中给每个字段补了一句“本字段只接受指定格式不接受其他等价表达”并在month的 description 里加示例和反例。第二在validate_params里加了一个“未知字段名”检测任何 schema 之外的参数都直接报错并列出合法字段列表。校验逻辑充当了最后一道防线同时也把错误信息变得可读模型知道自己错在哪重试时就会规规矩矩按 schema 来。上线后参数类报错率降了七成。5.2 两个技能描述打架Agent 选错技能现象是“月度汇总”技能和“季报生成”技能开始互相抢活。用户说“帮我看看这个季度的表现”汇总技能被激活结果脚本用月份参数去查数据查出来一个空集因为季度和月份的数据口径完全不同。排查时我先看评测记录里的混淆矩阵发现这两个技能的正向用例交叉命中的比例接近三成。再对比两份 SKILL.md发现二者描述里都出现了“业绩数据”“统计”“汇总”这些词边界完全重叠。修复不是优化某一份描述而是同时改两份。月度汇总技能在when_not_to_use里明确加了一句“如果用户指定了季度或自然季度范围使用季报生成技能”季报生成技能也加了反向声明。然后我在评测集里补了十条跨界 query专门测试边界场景。改完跑了三遍全量回归交叉误命中率从百分之二十多降到了百分之三以下。这个坑警示我技能之间不是孤立存在的任何一份描述的修改都必须带着全量评测的意识去评估。5.3 技能执行时间太长用户等不及就重试“月度报告生成”技能在某天某个数据量很大的月份上跑了将近 50 秒。用户以为卡死了连续点了几次重发结果服务端同时起了三个相同任务把数据库实例的 CPU 打满反过来拖慢了所有技能的执行。排查的第一步是看监控确认技能 P95 延迟从 8 秒飙升到 40 多秒并且重试次数和延迟上涨几乎同步。再追日志发现重试并非来自用户手动刷新而是 Agent 端超时后自动重新触发。这暴露了两个问题任务缺少幂等机制超时设置过短。修复分两步。第一步给技能增加异步执行模式任务提交后立即返回task_id完成后通过事件回调把结果推给用户界面。这样用户立刻就能看到“任务已进入队列”而不是干等一个看起来没有响应的窗口。第二步在技能注册表里增加max_execution_time字段并在 Agent 端配置“相同参数任务进行中时不允许重复触发”。改完之后同样的超时场景下用户收到的是进度提示而不是无声重试数据库压力也恢复正常。5.4 技能内部中间日志全塞回上下文token 爆炸这个坑藏得比较深查了很久才发现。现象是某些请求的 token 消耗突然暴涨几十倍单次对话的输入上下文达到了十几万 token账单令人肉痛。追查浪费时间最后顺着链路去看技能返回值才发现run.py里为了排查方便把每一步中间结果都放进调试字段里返回了比如从数据库读出来的原始订单行、渲染前的模板片段全被 Agent 写进了上下文作为“中间状态”。这其实是技能封装边界不清的问题。技能返回给 Agent 的应该只是最终的、精简过的结构化结果中间过程属于实现细节不应该让模型看见。修复方法是把run()的返回值改成白名单字段只允许summary_text和report_path等协议内声明的字段透出。中间日志全部写到独立日志文件仅在排查时人工查看不再混入模型上下文。改完后这一类的 token 消耗直接回到正常水平。我后来把这条总结成了一条硬规矩技能的输出是给模型看的“结论”不是给工程师看的“过程”什么字段能出现在返回值里以output_schema为准谁都不许私藏调试字段。6. 把 agent-skills 当代码库维护版本、审查与团队分工6.1 技能目录进 GitSKILL.md 变更必须走代码审查技能发展到几十个之后不能再靠个人在开发环境里随便改了。我把整个skills/目录放进 Git 仓库所有变更走 Merge Request 流程至少另一个同学 review 过才能合入。这个审查不是为了走形式而是因为技能描述是直接影响生产模型行为的信息它对线上效果的影响和代码完全等价。review 时我会重点看三样东西第一description 是否和现有其他技能描述有语义重叠如果拿不准就在测试环境跑一遍全量评测对比第二args 变化是否向后兼容新增字段必须是可选参数否则所有老对话记录在回放时都会校验失败第三有没有带评测用例凡是新增场景没有同步加 eval 的 MR我一般直接打回。6.2 评测集与技能同仓库维护命中率波动要能在 MR 里看出来为了把变更影响降到最低我在 CI 里加了一步“技能评测对比”。MR 运行时除了跑全量评测还会对每个技能的通过率变化做 diff任何同比下跌超过 5 个百分点的技能都会被高亮标出。人工审查时可以顺着这个信号快速定位。有一段时间团队里两位同事同时改了两个描述有交集的技能两边评测单独看都是绿的合到一起才发现整体命中率掉了 12%。后来我们约定凡是触碰技能描述或 schema 的 MR在合并前必须和主干上的全套技能一起跑一次“组合评测”。虽然多了几分钟时间但换来了对线上行为相当高的把握。这个习惯坚持下来之后的线上事故明显少了很多。6.3 技能语义化版本大版本用于破坏性变更小版本用于渐进优化每个技能的目录内部除了SKILL.md我还会放一个VERSION文件记录语义化版本号。规则不复杂描述或 schema 出现了不向后兼容的改动版本号升大版本只是补充描述示例、优化提示词表达、新增可选参数升小版本完全不动配置只修脚本可以只升补丁号。版本号还有一个实用的地方是排查线上问题。某一次用户反馈“技能不生效”排查后发现是某个节点上的技能包一直停留在旧版本没有重新部署。日志里打上版本号之后这类问题一眼就可以定位。也能配合灰度做精细化路由比如给某部分白名单用户使用新大版本其他人继续走旧的稳定版等新人效果验证通过再全量切换。6.4 团队协作与命名空间多人同时维护一套技能库时的秩序感当团队超过三个人同时往技能仓库里提交时最麻烦的一件事就是撞名。曾经出现过一个send_email技能被两拨人各自建了一份一处只支持单收件人一处支持群发结果 Agent 有时命中这个有时命中那个行为完全不可预期。后来我们引入了命名空间规范技能完整名称必须用类别前缀比如report.monthly_aggregator、message.email_sender、data.db_schema_inspector同类别前缀归属同一个负责人。新技能注册前要在 MR 描述里写清楚前缀归属避免同名目录冲突。还约定所有技能目录必须放在同一个根路径下由性能团队统一负责服务的加载与发布而业务同学只需要维护各自命名空间下的技能内容。这个分工让多人协作时的摩擦几乎降到了零也让我们可以把更多精力放在技能本身的打磨上。我个人的体会是agent-skills 的精髓不在于代码多复杂而在于它逼着团队把 Agent 的能力变成一套有秩序、可测试、能长期演进的资产。现在我再接到“给 Agent 加个能力”的需求第一反应已经不是往 system prompt 里再塞一段话而是先问三个问题这个能力边界在哪里谁还会复用评测用例打算怎么覆盖偶尔有人觉得这套流程有点重但几次迭代下来团队的共识是它节省的时间远比消耗的多。还有一个固定动作想分享给打算动手的人每个 SKILL.md 里都加上一个fallback_message字段当技能执行失败时用它拼出一句给用户的兜底提示比如“当前数据暂时无法汇总请尝试换个月份或稍后再试”。就这么一个小字段线上“Agent 不知所措”的对话少了很多。如果你也要搞 agent-skills我的建议是先别急着写执行脚本把第一个技能的 SKILL.md 认真写出来拿给身边人看一遍能看明白再继续。这一步挡掉的后续改描述之苦比你想象中要多得多。
