Agent Skills 实战：手把手做一个接口测试技能包

上个月，团队里一个测试同学来找我，表情有点无奈。

“哥，我用 Claude Code 生成接口测试用例，写了三天 Prompt，生成的脚本还是只能跑正常流程。让它测密码错误，它只断言 HTTP 200，根本没查数据库里的登录状态。”

我问他：“你把测试规则写在哪了？”

他说：“写在对话里啊。每次都要重新说一遍‘先调登录接口拿 token，再调业务接口，断言 code=0，data 不能为空’……”

我说：“那你为什么不用 Skill 把规则固化下来？”

他愣了一下：“接口测试也能做成 Skill？”

能。而且比你想的简单得多。 这篇文章，我把从零构建一个“接口测试技能包”的完整过程拆开讲。看完你就能自己做一个。

一、为什么接口测试需要 Skill？

先说说接口测试的真实痛点。

传统接口测试的“脚本地狱”是这样的：写了几十个用例，每个用例里都嵌着一堆硬编码断言——assert resp.status_code == 200、assert resp.json()["code"] == 0、assert resp.json()["data"]["token"] != ""。

上游字段一改，几十个用例里的断言要一个个重写。AI 来帮你生成？它复制粘贴的速度更快，但产出的东西依然是硬编码断言，该脆弱的还是脆弱。

更隐蔽的问题是“假通过”。 让 AI 生成一个支付回调的测试脚本，Prompt 里写了“校验订单状态变更为已支付”，结果它只断言了 HTTP 200，没有去查数据库里的订单状态。这个用例表面通过了，实际上什么都没验证。

Prompt 能表达“做什么”，但很难稳定地表达“怎么做才算对”。 它可以描述流程，但流程的每个节点需要哪些前置条件、执行时允许调用哪些工具、失败后应该如何回滚——这些确定性的工程细节，靠自然语言描述，总会有遗漏。

Skill 解决的就是这个问题：把“怎么做一个任务”从一次性的对话，变成可复用、可版本控制、可被 Agent 自动调度的能力单元。

二、Skill 和 MCP 的区别：一个给“手”，一个给“菜谱”

聊 Skill 的时候，很多人会问：那 MCP 呢？

这两个东西经常被放在一起比较，但它们解决的问题完全不同。MCP 是连接层，让 Agent 能连上外部工具——数据库、Git 仓库、接口文档、测试平台。它回答的是“能不能做”。Skill 是流程层，告诉 Agent 怎么组合这些工具、按什么顺序、遇到什么情况该怎么处理。它回答的是“怎么做才对”。

打个比方。MCP 是厨房里的刀具和炉灶，Skill 是菜谱。你给一个新手全套厨具，他可能切到手。给他一份菜谱，他至少能做出能吃的菜。

三、手把手：从零搭一个接口测试技能包

第一步：搭目录结构（2分钟）

Skill 必须放在 Agent 能识别的位置。项目级 Skill 放在项目的 .claude/skills/ 目录下。

.claude/skills/api-test-skill/
├── SKILL.md              ← 核心指令（必需）
├── references/            ← 参考文档（可选）
│   ├── http-codes.md
│   └── auth-methods.md
└── scripts/               ← 可执行脚本（可选）
    ├── run-tests.py
    └── validate-schema.py

关键规则：SKILL.md 文件名必须全大写。文件夹命名必须用 kebab-case，比如 api-test-skill，不能写成 API Test Skill。

第二步：写 SKILL.md 的头信息（5分钟）

头信息决定了 Agent 什么时候触发这个 Skill。最重要的字段是 description。

---
name: api-test-skill
description: 面向Python+pytest+requests的接口自动化测试技能。当用户需要新增接口自动化用例、维护已有用例、调试接口测试失败、或提到"接口测试""API测试""pytest用例"时触发。
when_to_use: 用户需要为REST API生成或维护自动化测试用例时使用。适用于新增用例、修复失败用例、接口回归测试等场景。
allowed-tools: Read, Write, Edit, Bash
---

description 是 Skill 的“门牌号”。 Claude 会把所有 Skill 的 description 预加载进上下文，用来判断该不该触发这个 Skill。你写“帮助接口测试”，它永远不知道什么时候该用。你写清楚“新增接口自动化用例、维护已有用例、调试接口测试失败时触发”，它就知道。

第三步：写 SKILL.md 的正文（30分钟）

正文就是操作手册。核心原则是：不要把测试逻辑写死在 Skill 里，而是让 Skill 告诉 Agent“去哪里找规则、按什么流程执行”。

这是我们从社区一个开源接口测试 Skill 里学到的设计思路——它用前置门禁约束修改边界，用渐进式披露降低上下文噪音。

## 任务
为 REST API 生成或维护 pytest + requests 接口自动化测试用例。

## 执行流程

### 步骤1：确认任务信息（前置门禁）
在执行任何操作前，必须向用户确认以下信息：
- 接口方法文件路径：待测接口定义在哪个文件？
- 接口方法位置：具体函数名或类名是什么？
- 用例文件路径：新用例写在哪个文件？
- 用例文件位置：具体写在哪个测试类或函数中？
- 用例命名：新用例叫什么名字？

**如果任何一项缺失，停止执行，向用户提问。**

### 步骤2：选择用例生成路径
根据用户提供的输入，选择对应的路径：

**路径A（有接口文档）** ：读取 OpenAPI/Swagger 文档，提取请求方法、路径、参数、响应结构。
**路径B（有参考用例）** ：找到1-2个功能最相近的已有测试用例文件，阅读其基类、导入、写法、命名风格。新用例的风格必须与已有用例保持一致。
**路径C（有cURL/抓包）** ：解析 cURL 命令或抓包数据，提取请求方法、URL、Headers、Body。
**路径D（有pytest报错）** ：读取报错信息，定位失败原因，修复用例。

### 步骤3：生成测试用例
每条用例必须包含：
- 用例ID：{模块}-{场景}-{序号}
- 前置条件：执行前必须满足的条件
- 请求配置：method, url, headers, body
- 断言：
  - 状态码断言（必须）
  - 业务码断言（必须）
  - 关键字段存在性断言（必须）
  - 字段类型/范围断言（按需）

### 步骤4：pytest闭环验证
用例编写完成后，必须执行目标 pytest 用例。
- 如果通过：输出用例摘要。
- 如果失败：读取报错，修复用例，重新执行，直到通过或明确说明环境问题。

### 步骤5：输出结果
- 新增/修改的用例列表
- pytest 执行结果
- 如果失败，附上失败原因和修复过程

这个流程的核心设计是“前置门禁”。 步骤1强制要求 Agent 确认文件路径和用例位置，避免它不知道写在哪里而大范围改动已有文件。

第四步：用 references 放长文档（10分钟）

references/ 目录放按需加载的长文档。SKILL.md 里只引用文件名，Agent 只在需要时才去读。这样不会把上下文撑爆。

references/test-case-template.md：详细的用例模板和示例。

references/http-codes.md：HTTP 状态码的含义和常见错误场景。

在 SKILL.md 里这样引用：

## 参考资料
- 用例模板和示例，参考 `references/test-case-template.md`
- HTTP 状态码说明，参考 `references/http-codes.md`

第五步：用 scripts 放可执行代码（15分钟）

scripts/ 目录放可执行的代码。Agent 不看代码内容，只看执行结果。

scripts/validate-schema.py：校验响应结构是否匹配 JSON Schema。

#!/usr/bin/env python3
"""校验 API 响应是否符合 JSON Schema"""
import sys
import json
import jsonschema

def validate_response(response_file, schema_file):
    with open(response_file) as f:
        response = json.load(f)
    with open(schema_file) as f:
        schema = json.load(f)
    try:
        jsonschema.validate(response, schema)
        print("PASS: 响应结构符合Schema")
        return 0
    except jsonschema.ValidationError as e:
        print(f"FAIL: {e.message}")
        return 1

if __name__ == "__main__":
    sys.exit(validate_response(sys.argv[1], sys.argv[2]))

在 SKILL.md 里引用：

## 步骤6：Schema校验（可选）
如果提供了 JSON Schema，运行 `python scripts/validate-schema.py response.json schema.json` 校验响应结构。

四、怎么用？三个字：直接调

Skill 写好了，在 Claude Code 里输入：

/api-test-skill 我要为 /api/v1/login 新增接口自动化测试用例

Agent 会自动加载 Skill 的规则，按你定义的流程执行：

1. 先问你接口方法文件、用例文件路径、用例名
2. 读取接口定义，提取请求方法和参数
3. 生成 pytest 用例，包含状态码、业务码、字段存在性断言
4. 执行 pytest，根据报错修复，直到通过

我让那个测试同学试了一下。他输入“新增登录接口的测试用例”，Agent 先问他：“接口方法定义在哪个文件？用例写在哪个文件？用例叫什么名字？”

他填完之后，Agent 在 2 分钟内生成了 8 条用例——正常登录、密码错误、账号不存在、验证码过期、字段缺失、SQL注入、超长字符串、空密码。执行 pytest，8 条全过。

他说：“以前这种程度的用例，我要写一个下午。”

五、进阶：用 Skill 做“模块化校验”

接口测试真正难的不是“写断言”，是“断言写得对且不脆弱”。

社区有一种更进一步的思路：把校验逻辑从一次性脚本中解耦出来，变成可组合、可复用的独立单元。比如：HttpStatusCodeSkill 校验响应状态码，JsonPathExistsSkill 校验 JSON 路径是否存在且非空，JsonSchemaSkill 校验响应结构，BusinessRuleSkill 校验自定义业务规则（如金额计算）。

每个 Skill 都有标准接口：接收一段校验描述，输出一个可执行的校验函数。而 Agent 的工作流，是把接口文档、测试场景和已有的 Skills 清单一起丢给大模型，让它自动规划“用哪些 Skill、按什么顺序、带什么参数”来完成这次校验。核心在于：Agent 不直接生成断言代码，而是生成一份校验计划。这个计划由 Skills 解释执行。

六、避坑指南

坑一：description 写得太空。 “帮助接口测试”——等于没写。要写清楚触发条件：用户说什么话、什么场景下用这个 Skill。

坑二：SKILL.md 写成百科全书。 超过 500 行就开始浪费 Token。把详细内容移到 references/ 目录，SKILL.md 只留核心流程。

坑三：把测试逻辑写死在 Skill 里。 不要在 SKILL.md 里写“断言 token 字段非空”，而是写“找到同目录已有用例，阅读其断言风格，新用例保持一致”。Skill 教的是方法论，不是具体断言。

坑四：忽略 Skill 的回归测试。 模型版本一变，Skill 行为可能漂移。阿里开源的 skill-up 就是干这个的——用声明式 YAML 写评测用例，跨引擎跑评测，发现退化及时修复。

坑五：不做前置门禁。 让 Agent 自己决定用例写在哪里，它可能会大范围改动已有文件。必须强制它先确认文件路径和用例位置。

最后

接口测试的 Skill 化，本质是把“测试工程师的经验”变成“Agent 能执行的流程”。

以前你把测试规则写在对话里，每次都要重新说一遍。现在你把规则写进 SKILL.md，Agent 每次都会按同一套标准执行。

以前 AI 生成的用例只能跑正常流程，因为它不知道“异常场景也要覆盖”。现在 Skill 里写清楚了四条路径、五步流程、六类断言，Agent 知道该怎么做。

你不需要再手写第 N 版 Prompt 了。你只需要把经验封装成一个技能包，让 Agent 照着干。

下次你发现自己在反复描述同一套接口测试规则的时候，停下来，花 30 分钟把它封装成 Skill。

30 分钟的投入，换的是未来每一个接口的测试效率。

本文部分内容参考了霍格沃兹测试开发学社整理的相关技术资料，主要涉及软件测试、自动化测试、测试开发及 AI 测试等内容，侧重测试实践、工具应用与工程经验整理。