你有没有过这种时刻给一个大模型 Agent 丢过去一句话“帮我把这几个接口用例写一下”它倒是答应得很爽快交回来的却是八页通用模板没有一个用例能对应上我们项目的字段。后来我花了一个下午把需求背景、接口定义、历史踩坑点全部写进一份 Markdown 文件再让 Agent 干活效果完全不一样。这份 Markdown 文件就是标题里说的 SKILL.md。作为一个测了几年接口和 Web 的测试工程师我最开始对这个东西是持怀疑态度的Agent 连一句话需求都经常理解跑偏凭什么一份文档就能让它老老实实干活但后来两周内我连续做了两三个实验彻底改观了。这篇文章我打算完全用测试人的视角来讲不聊玄乎的概念只聊一件事为什么一份 SKILL.md 能让 Agent 从“话痨”变成“能干活的人”以及测试人应该怎么上手写出第一份属于自己的技能文件。1. 给 Agent 一句话和给它一份说明结果像两个物种先说一个让我印象很深的对比实验。当时团队里有个刚毕业的同事 A天天被重复的回归用例折磨。他想用某个大模型自带的功能面板去生成测试脚本于是直接在对话框里输入“帮我给订单查询接口写测试用例要覆盖参数异常的情况。”Agent 输出的内容乍一看没问题有 mock 数据、有断言、有边界值分析。但一细看就露馅了——它把接口从 GET 写成了 POST断言里用了一个我们后端根本不存在的状态码还把必填字段漏了两个。这不是它态度不认真而是我那个同事根本没有告诉它这个接口的请求格式是什么样的、后端的状态码约定是什么、被测系统的历史边界缺陷集中在哪。同样的问题当我尝试把背景信息整理成一份说明文件再喂给它时输出的内容首次达到了“能直接进用例评审会”的水平。1.1 三个典型翻车场景我猜你也遇到过我做过的类似测试失败的形态基本可以归纳成三类。第一类叫“格式对内容空”。比如让它整理缺陷报告模板它确实给出了一个很像样的 Markdown 模板但里面所有的字段含义都是它自己猜的跟我们团队的 bug 管理规范对不上。第二类叫“步骤多顺序错”。让它做冒烟测试步骤规划它列了十步结果第三步就依赖到第五步生成的数据逻辑上根本跑不通。第三类更常见叫“不查资料直接脑补”。让它定位某个登录超时问题它煞有介事地给出了四五个排查方向却完全忽略了我们最近一次发布的配置变更。这三类翻车有一个共同点不是 Agent 不够聪明而是我们给它的输入没有边界。一句话提示只能表达“我想要什么”表达不了“在什么约束条件下、按什么顺序、以什么标准算完成”。1.2 缺的不是模型能力是“操作说明书”如果你把 Agent 想象成一个刚入职的实习生事情就很好理解了。你不可能只跟实习生说一句“去把订单模块测一下”就期待他产出符合规范的结果。你得告诉他被测系统怎么访问、测试数据从哪来、哪些字段是已知的高风险点、报告按什么格式写、什么情况下算阻塞。这份口头交接内容落到文档层面就是 SKILL.md。我后来在团队里做过一个小实验把同一套回归任务分别用“一句话提示词”和“一份 SKILL.md”去触发前者产出的用例通过率大概只有三成后者能到八成以上。差距不在于模型本身而在于我们有没有给它一份可以反复查阅的上下文。这就像老测试带新人嘴上讲百遍不如丢一份条目清晰的检查清单。2. SKILL.md 的本质一份会被 Agent 主动读取和执行的 Markdown说了这么多现象该回到正题SKILL.md 到底是什么。从文件格式上看它就是一个纯文本 Markdown 文件文件名通常是SKILL.md。从作用上看它是一份“能力说明书”加“执行手册”的结合体。目前比较流行的一种约定是把一个技能放到一个独立的目录下例如skills/order-query-check/SKILL.mdAgent 在启动或者需要匹配技能时会去扫描这些目录并读取里面的描述信息。这个机制跟人和人之间传阅工作手册没有本质差别Agent 先通过文件名和文件头部的描述判断这份技能适不适合当前任务如果适合就把正文加载进上下文然后按照正文里的步骤执行。你可能会问为什么偏偏是 Markdown而不是 JSON、YAML 或者 Python 脚本我个人的理解是Markdown 对人类足够友好测试人员不需要会编程就能写同时对大模型又足够结构化标题、列表、代码块都能被清晰地解析。换句话说它是人和 Agent 之间成本最低的“共同语言”。2.1 最小可用的 SKILL.md 长什么样一份最小可用的 SKILL.md通常由两部分组成文件头部的一段 YAML 元信息以及正文里的操作步骤。元信息一般包含name和description。name是技能的名字方便 Agent 识别description则非常重要它是 Agent 决定“要不要调用这个技能”的依据。比如你希望用户在提到“接口回归”时触发这个技能description 里就要写明触发词和适用场景。正文部分则可以按照测试人员的习惯排列目标、前置条件、执行步骤、通过标准、示例。下面我放一份简化过的模板大家可以感受一下--- name: order_query_regression description: 用于订单查询接口的回归检查。当用户提到订单查询、接口回归、参数校验时可用。 --- # 目标 对订单查询接口 /v1/order/query 执行回归验证 确认核心字段和异常场景均符合项目约定。 # 前置条件 1. 已获取测试环境地址和目标 Token。 2. 已知至少两条不同状态的订单数据。 # 执行步骤 1. 准备请求参数模板。 2. 按“必填字段全填”“缺省字段”“非法枚举”三类生成用例。 3. 对每个用例发送请求记录返回码和响应体。 4. 对照接口定义文档核对断言不要臆造状态码。 # 通过标准 - 全部用例通过。 - 若有失败输出“阻塞或非阻塞”的判断并补充日志截图。 # 示例 输入订单号 xxx 期望HTTP 200订单状态字段为合法枚举值。这份文件看着简单却把最关键的信息都约束住了做什么、不做什么、做到什么程度算完。2.2 Agent 为什么能按 Markdown 干活加载与注入机制理解这个机制对测试人员写好 SKILL.md 特别有帮助。我尽量用通俗的语言拆一下。Agent 在接收用户任务时通常不会把整个文件系统都读一遍那样成本太高。它更常见的做法是先扫描约定目录下的技能文件读取每个文件头部 description 字段形成一个“技能索引”。当用户说的话和某个 description 匹配它才会把对应的整个文件正文填充到对话上下文中。这就是为什么description写得越准确技能被正确调用的概率越高。同时也解释了一个现象同一个技能文件在不同 Agent 框架里的生效方式可能略有不同但底层逻辑都离不开“读取描述-匹配任务-注入正文”这三步。注入之后Agent 大模型会根据 Markdown 的层级结构把“标题”理解为阶段目标把“列表”理解为执行清单把“代码块”理解为必须遵守的格式样例。我之前一度以为这需要什么高深的插件系统看清楚了才发现本质上是利用了大模型对文字结构的理解力。这也意味着一份写得乱七八糟的 SKILL.md和一份条理清晰的 SKILL.md效果会天差地别。2.3 顺带澄清一个误解Skill 不是脚本有的测试同事看到“技能”两个字下意识以为要写代码、要部署服务。其实 Skill 不是可执行脚本它更像一份“提示词模板 流程标准”的文档化产物。真正的执行动作比如发 HTTP 请求、解析响应是在 Agent 调用工具或生成测试代码之后发生的SKILL.md 本身负责的是指挥链路不是具体运算。我在实际使用中更喜欢把 SKILL.md 类比为“测试计划文档”的浓缩版。测试计划里写了范围、策略、准入准出标准、风险点SKILL.md 同样可以包含这些要素只是它被压缩成了一份大模型能直接消费的格式。理解了这一点你就不会纠结于“我是不是得会写代码才能做这件事”了。3. 测试人上手用订单查询接口回归跑通一份可复用技能接下来是实操环节。我们直接挑一个测试人员最熟悉的场景——接口回归来完整走一遍流程。3.1 先想清楚这个技能到底要约束什么动手写文件之前我强烈建议你先花十分钟想清楚三件事调用时机、输入前提、验收标准。调用时机决定了 description 怎么写输入前提决定了正文要嘱咐 Agent 准备哪些数据验收标准决定了最后一步“判断是否通过”的逻辑。比如我们想把“订单查询接口回归”做成技能那就要先问自己Agent 是在什么情况下被触发是用户说“帮我做订单查询回归”的时候还是只要提到“订单查询”就得触发我通常建议把 description 写得窄一点宁可漏触发也不要乱触发。输入前提也很关键。订单查询接口至少需要 token、订单号或时间范围。如果这些前提没交代清楚Agent 就会自己瞎编数据生成的用例全都是在“无米之炊”。最后是验收标准。你要告诉 Agent用例全部通过算完成还是允许特定比例失败失败之后要输出什么没有这个标准Agent 很容易找一堆“看起来合理”的理由草草收场。3.2 手把手写一份回归检查 SKILL.md基于上面的思考我来完整展示一份我在模拟项目里反复调过很多次的 SKILL.md。它比我之前给的最小模板多了不少细节但每一条都有实际用途。--- name: order_query_regression description: 订单查询接口回归检查。当用户提到“订单查询”“query接口回归”“参数异常测试”时使用。 --- # 技能目标 对内部订单服务 /v1/order/query 执行回归检查 覆盖正常查询、参数缺失、非法枚举值和鉴权失败四类场景。 # 被测接口信息 - 环境地址由用户提供不自行猜测 - 请求方法GET - 必需字段orderId、userId - 可选字段status、pageSize - 状态码约定200 成功400 参数错误401 鉴权失败500 服务异常 # 执行步骤 1. 请用户确认测试环境地址和 Token。 2. 从订单池中选择至少一个存在状态和不存在状态的数据。 3. 按以下用例矩阵发起请求 | 场景 | 参数组合 | 期望结果 | |------|---------|---------| | 正常查询 | 全部必填 | 200 且订单字段完整 | | 缺 orderId | 仅 userId | 400 且提示缺参 | | 非法 status | statusabc | 400 且提示枚举非法 | | Token 错误 | 正常参数 错误 Token | 401 | 4. 对每个用例记录实际返回码、响应体、耗时。 5. 对比期望结果标记 PASS/FAIL并给出失败理由。 6. 如遇 FAIL输出请求报文复现步骤禁止直接修改参数重试掩盖问题。 # 完成标准 - 用例矩阵中全部场景均已执行。 - 至少有一个正常用例通过否则判定为环境阻塞不继续执行。 - 产出表格化报告。 # 注意事项 - 不要臆造订单号或 Token缺失信息必须询问用户。 - 不要扩大范围去测创建订单、支付等接口本次只聚焦查询链路。这份文件最大的特点是把测试人员日常最啰嗦的口头要求全部固化了。Agent 看到它就像新手拿到一份带避坑指南的测试用例集执行起来会靠谱很多。3.3 第一次运行之后怎么改第一次跑完几乎一定会遇到不完美的地方这不奇怪。我的经验是分两步修。第一步是看“触发准不准”。如果你明明提到了订单查询Agent 却没调用这个技能那就要检查 description 里的触发词是否写得太生僻或者被其他技能抢了先。可能是“查询”这个词太通用被别的技能先匹配了那就把 description 收窄加上“/v1/order/query”这种唯一标识。第二步是看“执行稳不稳”。如果 Agent 执行到一半开始自由发挥比如自己造了一个不存在的字段那就是正文里的约束还不够硬。我一般会在“注意事项”里加类似“任何请求参数必须来自接口定义文档如文档不存在则停止执行并询问”这种硬条款。不要指望第一版就完美。写 SKILL.md 和写测试用例一样是要靠迭代去逼近覆盖率的。我的建议是每个技能至少跑三次真实场景每跑一次改一次描述或正文直到确认它在不同输入下都能稳定输出。4. 真正好用的 SKILL.md 是从坑里长出来的现在聊一点更进阶的内容。我见过很多测试同学照着模板写出了 SKILL.md但实际使用效果平平问题大多出在四个典型坑上。这节我把坑和对应的写法讲透。4.1 四个典型坑和对应写法第一个坑description写得太宽。有人为了确保技能能被命中把 description 写成“处理所有测试相关问题”结果 Agent 每次都想用这个技能导致正文里的约束把很多不该约束的场景也约束了。正确的写法是主动收缩触发面比如“仅当用户提到订单查询接口时使用”。第二个坑正文内容膨胀。一份 SKILL.md 不是文档库最好不要超过 200 行。内容太长会占用上下文窗口反而削弱模型对关键步骤的注意力。我的习惯是把最核心的步骤控制在 10 到 15 条详细背景信息如果需要可以拆进单独的参考文件再在正文里引用。第三个坑只有步骤没有“禁止项”。测试人员都知道用例设计里除了“有效等价类”还要有“无效等价类”。SKILL.md 也是一样光告诉 Agent 要做什么不够还要告诉它不能做什么。比如“不要臆造订单号”“不要更改被测数据”这类禁止语句往往比十步正常指令更管用。第四个坑缺少示例。大模型特别吃“少样本示例”这一套。如果你在正文里给一个输入输出的真实对照它的输出风格和判断标准会向这个示例靠拢。我自己在写技能时只要可能一定会加一节“示例”哪怕只有一条。4.2 把“测试检查清单”嵌进技能里测试人最擅长的就是检查清单这件事要迁移到 SKILL.md 里。所谓检查清单就是在技能正文里加一段“执行前确认”或者“输出前自检”的步骤让 Agent 在提交结果之前先自问几个问题。我在订单查询回归的技能里就加了一行“输出前自查是否所有请求均由用户提供或接口定义文档中获取有无自行编造”。这招看起来简单实际效果很好。因为大模型在生成长文本时往往会顺着惯性一路写下去一旦你给了它一个“最终自检”的停顿点它能自己揪出不少错误。另一个好用的小技巧是把“失败处理”写进技能。很多 Agent 执行任务遇到错误时第一反应是换个参数重试直到测出通过这在测试领域是很危险的因为它掩盖了真实缺陷。所以我会明确写“如遇失败输出复现步骤禁止修改参数重试”。这条约束直接扭转了 Agent 的行为模式。4.3 像管理用例一样管理 SKILL.mdSkill 文件一旦多起来也要进入配置管理流程。我现在的习惯是把技能文件统一放到一个独立目录纳入版本管理和测试用例库同步更新。每次接口定义变更我都会检查相关 SKILL.md 是否需要同步修订就像线上接口变更后要更新用例一样。版本管理这块我吃过一次亏。有一次接口新增了一个字段我只更新了接口文档忘了更新 SKILL.md 里的用例矩阵结果 Agent 生成的用例里还在用旧字段导致一轮回归白跑。从那以后我在技能文件里加了一行“关联接口文档版本号”从源头提醒自己。另外不要一个文件包打天下。我建议按业务模块拆分一个模块一个技能最多在总索引里做一个汇总文件。这样既方便维护也更容易让 Agent 精准匹配。5. 测试人还能拿它做哪些事场景对照与新人路径说到这你大概已经清楚 SKILL.md 和 Agent 之间的关系了。最后这节我想把它放到更大的测试工作场景里看看除了接口回归它还能在哪些地方发光以及新入门的测试人应该按什么路径去练。5.1 一张场景对照表我根据自己的实践把测试工作里常见的几类任务跟 SKILL.md 适配程度做了一张对照表。注意这个结论是基于我手头几个大模型的表现得出的不构成绝对结论但至少能帮大家建立预期。测试场景SKILL.md 能发挥的价值适配程度备注接口回归规范用例矩阵、断言逻辑、报告格式适合上手最快收益最明显缺陷单整理统一字段口径、模板填充、严重级别判断适合需要历史缺陷样例做参考日志初步定位给出排查顺序、筛选关键词、明确边界勉强适合需要把环境差异写清性能数据汇总按固定维度统计、生成对比表格适合原始数据必须由工具产出覆盖率评估统计分析类工作不太适合缺少可执行载体技能容易空转这个表的核心信息是SKILL.md 最适合那些“有明确流程、有固定输入输出、重复率高”的工作。越是依赖个人经验和临场感觉的事越不适合硬塞给技能这也是测试人员的判断力无法被取代的地方。5.2 三步上手建议与我的真实体会如果你看完这篇还是不知道从哪里开始我的建议很简单第一步挑一件有重复劳动的事别贪大。比如就选“整理某接口的字段检查清单”先写一份 30 行的 SKILL.md跑通一次再说。第二步参考正文里的结构给你的文件加上元信息、执行步骤、完成标准。不用一开始就写得很完美先把循环 skeleton 跑起来。第三步连续做三次真实任务每次只改一个点直到输出稳定。做完这三步你对“一个 SKILL.md 就能让 Agent 干活”的判断基本就会从怀疑变成理解。最后说点我个人的真实体会。这个东西之所以对测试人友好最大的原因是它能把我们脑子里那套“经验文档化”已有方法论无缝迁移过来测试计划怎么写的SKILL.md 就怎么写检查清单怎么列的技能正文就怎么列用例评审怎么评审的就怎么去 review 一份技能文件。哪怕你只完成了最基础的一步——把平时口头交代的需求写成了一份结构清晰的 Markdown——Agent 的出活质量都已经和“一句话需求”不是一个档次了。这也是我最近半年特别沉迷于改各种 SKILL.md 的根本原因它没有让 Agent 取代测试工作反而让我们更值钱了。