从 SKILL.md 到测试工程资产，测试团队真正要补的不是 Prompt
用 Cursor、Claude Code、智能体工具写测试 Skills，很多测试开发同学都会遇到一个很尴尬的问题：
明明配置了 SKILL.md，AI 还是不按预期执行。
让它生成接口测试用例，它只写正常场景。
让它输出 JSON，它夹一堆解释文字。
刚开始还能按流程走，聊几轮之后就开始跑偏。
在项目 A 里还挺好用，换到项目 B 直接失灵。
很多人第一反应是：模型不稳定。
但从测试工程角度看，问题未必都在模型。
AI 测试 Skills 的本质，不是“写一段更长的提示词”，而是把测试团队的经验、约束、流程、输出格式和质量标准，沉淀成 AI 可以反复调用的工作流。
如果这个工作流本身不清楚，AI 自然会自由发挥。
这篇文章不讲概念，直接从测试开发真实使用场景出发，拆一拆 AI 测试 Skills 最容易踩的坑。
一、Skill 根本没有被加载
很多所谓“Skill 不生效”，第一步就错了。
不是 AI 不听话，而是它根本没加载到这个 Skill。
典型现象是：
你让 AI 列出当前可用 Skills，结果列表里没有你写的那个。
这时候继续改描述、改提示词都没意义。
项目级 Skill 通常会放在类似结构下：
your-project/
└── .cursor/
└── skills/
└── api-test-generator/
└── SKILL.md
几个地方最容易错：
.cursor 写成 cursor
skills 写成 skill
SKILL.md 写成 skill.md
技能目录嵌套过深
YAML 头格式不规范
推荐头部写法：
---
name: 接口测试用例生成器
description: 根据接口代码、接口文档或 Swagger 信息生成 pytest 测试用例，覆盖正常场景、异常场景、边界场景和断言逻辑
version: 1.0.0
last_updated: 2026-05-12
---
# 接口测试用例生成器
注意，不要用中文冒号。
错误写法：
name：接口测试用例生成器
正确写法：
name:接口测试用例生成器
这个坑很基础，但非常常见。
测试排查问题时，第一步不是怀疑系统复杂性，而是先确认基础输入有没有进入系统。
写 Skill 也是一样。
二、description 写得太虚，AI 不知道什么时候该用
很多人会这样写：
description: 当用户需要生成测试用例时使用
这句话看起来没问题，但实际触发很不稳定。
因为“生成测试用例”太宽泛了。
用户可能说：
帮我看下这个接口怎么测
也可能说：
这个登录接口异常场景补一下
还可能说：
根据 user_api.py 写 pytest
这些都和测试用例有关，但 AI 未必每次都会判断应该调用这个 Skill。
更稳的写法是：
description: 当用户要求基于接口代码、Swagger/OpenAPI 文档、接口请求示例、响应示例或业务需求描述，生成接口测试点、测试用例、pytest 自动化脚本和断言建议时使用。
这个描述比“生成测试用例”稳定得多。
它说清楚了：
输入是什么
任务是什么
输出是什么
适用边界是什么
description 不是写给人看的宣传语，而是写给模型看的触发条件。
越具体，越稳定。
三、技能名太像，多个 Skill 之间会互相打架
很多团队会同时建几个 Skill：
接口测试生成器
接口用例生成器
接口自动化生成器
API 测试助手
pytest 生成助手
这些名字看起来都合理，但放在一起就容易混淆。
AI 在判断该用哪个 Skill 时，会面临多个相似候选。
结果就是：
你本来想生成 pytest，它调用了测试点分析 Skill。
你本来想输出用例表，它直接生成了自动化代码。
你本来想做接口测试，它跑去套了通用测试报告模板。
建议 Skill 名称要区分任务边界。
比如：
接口测试点分析器
pytest 自动化用例生成器
接口测试报告生成器
缺陷复盘分析器
需求测试点评审器
不要所有 Skill 都叫“测试助手”。
“助手”这个词太泛，泛到最后就没有边界。
团队使用时，也建议显式点名。
例如：
@接口测试点分析器 分析当前接口的测试覆盖点
@pytest 自动化用例生成器 基于上面的测试点生成 pytest 代码
这样比让 AI 自己猜要稳得多。
四、Skill 只写任务，没有写角色边界
很多 Skill 一上来就写：
请根据接口代码生成测试用例。
这太薄了。
AI 不知道自己应该站在哪个角色上完成任务。
是初级测试？
是测试开发？
是自动化工程师？
是测试架构师？
是质量负责人？
不同角色输出的深度完全不同。
不推荐这样写：
你需要生成接口测试用例。
更好的写法是：
你是一名资深测试开发工程师，熟悉接口测试、pytest 自动化、业务规则分析、边界值设计、异常场景覆盖、断言设计和测试风险识别。
你的目标不是简单列出正常用例，而是帮助团队沉淀可执行、可维护、可自动化的接口测试资产。
这段话有两个作用。
第一，限定角色。
第二，限定质量目标。
测试领域里，最怕 AI 只给“看起来像测试”的内容。
真正有价值的测试输出，必须有覆盖面、断言、优先级、风险意识和可执行性。
五、流程没有闭环，执行到一半就停
很多 Skill 会写一串步骤：
1. 分析接口
2. 提取字段
3. 生成测试点
4. 输出测试用例
5. 生成 pytest 代码
但实际执行时，AI 经常做到一半就停下来：
以上是接口分析，请问是否需要我继续生成测试用例？
这对聊天没问题，但对工作流来说就是失败。
因为测试开发要的是完整产物，不是半成品。
这类 Skill 里需要加执行规则：
## 执行规则
- 必须一次性完成所有步骤，中间不得询问用户是否继续。
- 除非缺少关键输入，否则不要中断流程。
- 如果信息不足，应先基于已有信息完成可推断部分，并在最后列出缺失信息。
- 不允许只输出分析，不输出最终用例。
- 不允许只输出测试点，不输出断言建议。
这类规则一定要放在靠前位置。
越靠后的规则，越容易被弱化。
如果一个 Skill 里有十几步：
需求分析
接口分析
数据准备
用例设计
代码生成
脚本执行
结果分析
报告生成
缺陷定位
修复建议
建议拆掉。
拆成：
需求测试点分析 Skill
接口用例生成 Skill
pytest 脚本生成 Skill
测试结果分析 Skill
一个 Skill 干一类事，反而更稳定。
六、项目规则只在聊天里说，几轮后必忘
测试项目里有很多特殊规则。
例如：
业务成功码是 0000
HTTP 200 不代表业务成功
手机号必须走内部测试号段
测试环境不能访问生产域名
订单状态为 PAID 才能退款
pageSize 最大不能超过 100
很多人会在对话里告诉 AI：
我们项目成功码是 0000，你记住。
第一次它可能记住了。
几轮之后，它又开始写：
assert response.status_code == 200
这不是小问题。
因为测试用例的价值，很大程度取决于它是否理解项目规则。
规则必须固化到 Skill 里。
例如：
## 项目特定规则
### 响应判断
- HTTP 状态码 200 仅表示请求成功送达，不代表业务成功。
- 业务成功必须校验：`response.code == "0000"`。
- 业务失败必须校验：`response.code != "0000"`。
- 错误场景必须同时校验错误码和错误提示。
### 环境规则
- 默认测试环境：`https://test-internal.example.com`
- 不允许使用生产环境地址。
- 请求超时时间默认 30 秒，不得低于 10 秒。
### 数据规则
- 手机号、身份证号、银行卡号必须使用测试数据。
- 不允许在示例代码中写真实账号、真实 Token 或生产配置。
一条原则：
凡是每次都要遵守的规则，不要放在聊天里，要放进文件里。
七、只要求“生成用例”，没有定义测试覆盖标准
这是测试 Skills 最核心的坑。
很多 Skill 只写：
请生成完整测试用例。
问题是，什么叫完整？
对 AI 来说，可能包含 5 条用例就算完整。
对测试专家来说，至少要覆盖：
正常路径
异常路径
边界值
权限
状态流转
幂等性
重复提交
并发
数据一致性
错误码
降级逻辑
安全风险
性能风险
如果你不定义覆盖标准，AI 就会默认生成最常见、最省事的用例。
建议在 Skill 中加入测试覆盖矩阵：
## 测试覆盖要求
每个接口至少从以下维度设计用例：
1. 正常场景：合法参数、正常状态、预期成功。
2. 必填校验：必填字段为空、缺失、null。
3. 类型校验：字段类型错误、数组/对象结构错误。
4. 格式校验：手机号、邮箱、日期、枚举值、金额格式。
5. 长度校验：最小长度、最大长度、超长字符串。
6. 边界值：0、1、最大值、最小值、临界值。
7. 权限校验：未登录、Token 过期、角色权限不足。
8. 状态流转：当前状态是否允许执行该操作。
9. 幂等性：重复请求是否产生重复数据。
10. 并发风险：并发提交、并发修改、库存扣减、余额扣减。
11. 数据一致性：数据库状态、缓存状态、消息状态是否一致。
12. 错误处理：错误码、错误提示、异常结构是否符合规范。
这才是测试专家和普通提示词的区别。
不是让 AI “多生成几条”，而是给它一套测试设计标准。
八、输出格式没有 Schema，后续自动化根本接不住
如果你只是让 AI 输出：
请用 JSON 格式输出。
大概率会翻车。
它可能输出 JSON。
也可能输出 Markdown 代码块里的 JSON。
也可能先写一句“下面是结果”。
也可能字段名每次都不一样。
对人阅读影响不大，但对自动化接入是灾难。
比如你想把结果同步到：
TAPD
禅道
飞书表格
测试管理平台
自动化用例仓库
质量平台
格式不稳定，后面的流程就全断了。
推荐写严格 Schema：
## 输出格式要求
你必须严格输出 JSON，不得输出 Markdown、解释文字、代码块标记或额外说明。
输出结构必须符合以下格式：
{
"api_name": "接口名称",
"method": "GET | POST | PUT | DELETE",
"path": "接口路径",
"test_cases": [
{
"id": "TC001",
"title": "用例标题",
"priority": "P0 | P1 | P2",
"case_type": "normal | exception | boundary | permission | concurrency | security",
"precondition": "前置条件",
"request_data": {},
"steps": ["步骤1", "步骤2"],
"expected_result": "预期结果",
"assertions": ["断言1", "断言2"],
"automation_level": "high | medium | low"
}
],
"risks": [
{
"risk": "风险描述",
"suggestion": "建议"
}
]
}
再补失败格式：
如果无法生成，必须输出：
{
"error": "失败原因",
"missing_information": ["缺失信息1", "缺失信息2"]
}
这一步决定了 Skill 是“看着好用”，还是“真的能接入工程流程”。
九、Skill 写死项目结构，换个项目就失灵
很多 Skill 在项目 A 中好用，是因为它偷偷依赖了项目 A 的结构。
例如：
读取 src/api/user.py 文件，分析 UserAPI 类。
到了项目 B，目录可能变成：
backend/modules/user/controller.py
或者：
app/services/user_service.py
Skill 直接失效。
不要写死路径。
不推荐：
读取 api/user.py 文件。
更好的写法：
优先分析当前编辑器打开的文件。
如果当前没有打开文件，请在项目中搜索以下内容：
- Controller
- Router
- Service
- API
- Swagger
- OpenAPI
- request mapping
- route definition
不要假设固定目录结构。
这样 Skill 才能跨项目复用。
也不要写死框架。
不推荐：
根据 Flask 路由生成测试用例。
如果团队里既有 Flask，又有 FastAPI、Spring Boot、Django，这个 Skill 很快就不够用。
更好的写法：
根据当前项目实际使用的接口框架识别路由定义。可能包括但不限于 FastAPI、Flask、Django、Spring Boot、Express、NestJS。
Skill 要有适配能力，而不是只服务某一个项目。
十、没有前置检查，信息不够时 AI 就开始编
这是 AI 生成测试资产时最危险的问题之一。
输入信息不完整时，它不是说明缺什么，而是开始补全。
比如：
你只给了一个接口名，它可能编出 URL。
你只给了请求字段，它可能编出响应结构。
你没给鉴权方式，它可能默认 Bearer Token。
你没给业务规则，它可能按通用逻辑写成功失败。
这些东西看起来很顺，但放到项目里全是错的。
Skill 里必须加入前置检查：
## 前置检查
在生成测试用例前，必须先检查是否具备以下信息：
1. 接口名称；
2. 请求方法；
3. 请求路径；
4. 请求参数；
5. 参数类型；
6. 必填规则；
7. 响应结构；
8. 成功码与失败码；
9. 鉴权方式；
10. 业务状态流转；
11. 数据依赖；
12. 是否存在幂等或并发风险。
如果缺少信息，不得编造。
应在最终输出中列出缺失信息，并给出可继续生成的部分。
注意，不是让 AI 遇到信息不足就停止。
而是：
能推断的先做
不能确定的标出来
禁止编造
这才符合测试工程的工作方式。
十一、没有失败策略，一失败就开始自由解释
很多 Skill 只写成功路径：
输入接口文件 → 生成测试用例
但没有写失败路径。
如果接口文件不存在怎么办？
如果无法识别框架怎么办？
如果 Swagger 不完整怎么办？
如果代码里没有响应定义怎么办？
如果项目没有 pytest 配置怎么办？
没有失败策略，AI 就会自由发挥。
推荐补失败处理规则：
## 失败处理规则
如果无法完成任务，不允许输出模糊解释，必须按以下格式说明：
1. 当前已识别的信息；
2. 当前缺失的信息；
3. 不能继续生成的原因；
4. 用户需要补充的最小信息；
5. 在信息不足情况下，仍然可以提供的参考内容。
不得编造接口路径、字段含义、业务规则或断言逻辑。
测试工作里，失败不可怕。
可怕的是失败后输出一堆看起来正确、实际无法验证的内容。
十二、全局 Skill 太多，上下文被挤爆
有些人喜欢把所有 Skill 都放全局。
结果是：
每个项目都加载
每次对话都带着
技能越多，上下文越重
刚开始还行，时间一长就开始跑偏。
适合放全局的，一般是通用规范：
代码输出风格
测试报告格式
通用安全规范
通用命名规范
通用代码评审标准
不适合放全局的，是项目特定内容：
某项目接口成功码
某项目目录结构
某项目数据库表
某项目测试账号
某项目业务状态机
某项目专属自动化封装
这些应该放项目级 Skill 或项目规则里。
一个简单原则：
跨项目都成立的，放全局。
只对当前项目成立的，放项目。
只对当前任务成立的，放对话。
这句话能解决很多上下文混乱问题。
十三、团队本地版本不一致，每个人生成结果都不一样
个人用 Skill，问题不大。
团队用 Skill，就必须管理版本。
否则会出现：
你生成的用例有异常场景
队友生成的只有正常场景
你这边输出 JSON
队友那边输出 Markdown 表格
你已经更新了成功码规则
队友还在用旧版
最后大家会误以为是 AI 不稳定。
其实是 Skill 版本根本不一致。
项目级 Skill 应该进入版本管理：
.cursor/
└── skills/
└── api-test-generator/
└── SKILL.md
不要让 .cursor/skills/ 被 .gitignore 忽略。
Skill 内写版本信息：
---
name: 接口测试用例生成器
description: 根据接口代码或接口文档生成接口测试用例
version: 2.1.0
last_updated: 2026-05-12
owner: QA Team
---
团队更新 SOP 可以这样定：
1. 修改 SKILL.md
2. 更新 version 和 last_updated
3. 用最小案例验证
4. 提交 Git
5. 在团队群通知 Skill 已更新
6. 其他成员 git pull
7. 重新加载 Skills
8. 验证当前 Skill 版本
Skill 一旦进入团队协作，就不是个人提示词。
它是测试资产。
测试资产就必须版本化。
十四、把 Skill 当 Prompt 用，没有持续迭代
很多人写完 Skill 就不动了。
然后每次输出不好，就在聊天里临时补一句：
注意要覆盖边界值。
记得输出 JSON。
不要只写正常场景。
这其实是在重复修同一个问题。
更好的做法是：
发现一次问题，就更新一次 Skill。
如果发现它漏了空值：
把“必填字段为空、null、缺失”加入测试覆盖要求。
如果发现它漏了超长字符串：
把“字段最大长度、超长字符串、特殊字符”加入边界值设计规则。
如果发现它老是用 HTTP 200 判断成功：
把“HTTP 状态码不代表业务成功，必须校验业务码”加入项目强约束。
如果发现它输出格式乱：
把输出格式改成严格 JSON Schema，不允许额外解释文字。
Skill 的价值不是一次写好。
而是越用越贴合团队。
十五、没有接入真实测试流程，最后变成玩具
这是最容易被忽视的坑。
很多团队做 Skill，只停留在：
让 AI 生成几条测试用例
然后就结束了。
这当然能提升一点效率，但很难形成真正的工程价值。
真正有价值的 Skill 应该接入流程：
需求文档
↓
需求测试点分析 Skill
↓
测试用例生成 Skill
↓
接口自动化脚本生成 Skill
↓
执行结果分析 Skill
↓
缺陷定位与复盘 Skill
↓
测试报告生成 Skill
这时候 Skill 就不是单点工具，而是测试流程的一部分。
可以沉淀的测试资产至少包括：
测试点分析规则
接口用例设计规则
自动化脚本生成规范
断言设计规范
测试数据构造规范
错误码校验规范
缺陷描述规范
测试报告结构
风险识别清单
回归测试选择策略
当这些内容都沉淀下来，AI 才不是一个“会聊天的工具”，而是开始接近测试团队的工程助手。
一个更适合测试团队的 Skill 基础模板
下面这个模板可以作为起点。
不是最终版，但比“帮我生成测试用例”稳定很多。
---
name: 接口测试用例生成器
description: 根据接口代码、Swagger/OpenAPI 文档、接口请求示例、响应示例或业务需求描述，生成接口测试点、测试用例、pytest 自动化示例和断言建议
version: 1.0.0
last_updated: 2026-05-12
owner: QA Team
---
# 接口测试用例生成器
## 角色定位
你是一名资深测试开发工程师，熟悉接口测试、pytest 自动化、边界值分析、异常场景设计、业务规则分析、断言设计和测试风险识别。
你的目标不是简单生成正常用例，而是帮助团队沉淀可执行、可维护、可自动化的接口测试资产。
## 适用场景
当用户提供以下任意内容时，应使用该技能：
- 接口代码；
- Swagger / OpenAPI 文档；
- 接口请求示例；
- 接口响应示例；
- 业务需求描述；
- 当前打开的 Controller / Service / API 文件；
- 需要补充接口测试用例或 pytest 自动化脚本。
## 执行规则
- 必须一次性完成所有步骤，中间不得询问用户是否继续。
- 不得编造不存在的接口、字段、路径、类名、依赖或业务规则。
- 如果信息不足，应基于已有信息完成可推断部分，并在最后列出缺失信息。
- 必须覆盖正常场景、异常场景、边界场景、权限场景、状态流转场景和数据一致性场景。
- 不允许只输出正常用例。
- 不允许只输出测试点，不输出断言建议。
- 输出 pytest 示例时，应优先复用项目已有封装；无法识别时，再给出通用示例。
## 前置检查
生成用例前，请先检查是否具备以下信息：
1. 接口名称；
2. 请求方法；
3. 请求路径；
4. 请求参数；
5. 参数类型；
6. 必填规则；
7. 响应结构；
8. 成功码与失败码；
9. 鉴权方式；
10. 业务状态流转；
11. 数据依赖；
12. 幂等性或并发风险。
如果缺少信息，不得编造，应在最后列出缺失项。
## 项目规则
- HTTP 200 仅表示请求成功送达，不代表业务成功。
- 业务成功必须校验响应体中的业务码。
- 默认业务成功码为：`0000`。
- 错误场景必须校验错误码和错误提示。
- 不允许使用生产环境地址。
- Token、账号、手机号、身份证号等敏感数据必须使用测试数据或脱敏数据。
## 测试覆盖要求
每个接口至少从以下维度设计测试用例：
1. 正常场景；
2. 必填字段为空；
3. 字段缺失；
4. 字段为 null；
5. 字段类型错误；
6. 字段格式错误；
7. 字段超长；
8. 字段边界值；
9. 枚举值非法；
10. 权限不足；
11. Token 为空；
12. Token 过期；
13. 当前状态不允许操作；
14. 重复提交；
15. 并发请求；
16. 数据不存在；
17. 数据已存在；
18. 错误码与错误信息校验；
19. 数据库或缓存状态校验；
20. 下游服务异常或超时。
## 输出结构
请按以下结构输出：
### 1. 接口理解
说明接口用途、请求方式、核心参数、响应结构和业务规则。
### 2. 测试点分析
按以下分类输出：
- 正常场景；
- 异常场景；
- 边界场景；
- 权限场景；
- 状态流转场景；
- 幂等与并发场景；
- 数据一致性场景。
### 3. 测试用例表
| 用例编号 | 用例标题 | 优先级 | 场景类型 | 前置条件 | 请求数据 | 操作步骤 | 预期结果 | 断言点 |
|---|---|---|---|---|---|---|---|---|
### 4. pytest 示例代码
生成可参考的 pytest 测试代码。
### 5. 断言建议
说明需要校验的内容，包括：
- HTTP 状态码；
- 业务状态码；
- 响应字段；
- 错误提示；
- 数据库状态；
- 缓存状态；
- 消息队列或异步任务结果；
- 关键副作用。
### 6. 风险提醒
指出当前接口可能遗漏的测试风险。
### 7. 缺失信息
如果输入信息不足，请列出需要用户补充的最小信息。
再往前一步：测试团队可以沉淀一组 Skills
如果只做一个“接口测试生成器”，价值有限。
更推荐测试团队按流程拆成一组 Skills。
1. 需求测试点分析 Skill
输入 PRD、需求描述、用户故事。
输出：
业务流程
测试范围
主路径
异常路径
边界条件
状态流转
风险点
需要澄清的问题
2. 接口测试用例生成 Skill
输入接口文档、Swagger、代码、请求响应示例。
输出：
接口测试点
用例表
断言建议
自动化优先级
测试数据建议
3. pytest 自动化生成 Skill
输入测试用例和项目封装。
输出：
pytest 代码
fixture 设计
参数化用例
断言封装
数据准备与清理
4. UI 自动化脚本生成 Skill
输入页面结构、业务流程、元素信息。
输出：
页面对象模型
操作步骤
定位策略
断言点
失败截图建议
5. 缺陷分析 Skill
输入失败日志、接口响应、截图、错误堆栈。
输出：
问题现象
影响范围
可能原因
复现路径
定位建议
缺陷描述
优先级建议
6. 测试报告生成 Skill
输入测试结果、失败用例、风险列表。
输出：
测试结论
覆盖范围
通过率
失败分析
遗留风险
上线建议
这才是比较完整的 AI 测试 Skills 体系。
单个 Skill 是工具。
一组 Skills 才是流程。
最后：AI 测试 Skills 真正考验的不是提示词
很多人以为，写不好 Skill 是因为不会写 Prompt。
但测试专家看这个问题，会有一个更直接的判断：
不是 Prompt 不够华丽。
是测试方法本身没有结构化。
如果团队平时就没有统一的测试覆盖标准，没有清晰的断言规范，没有稳定的测试数据策略，没有用例优先级定义，没有缺陷复盘机制，那写出来的 Skill 也只会是松散的。
AI 不会凭空帮团队建立测试体系。
它只能放大已有体系。
你的测试流程清楚，AI 就能帮你提效。
你的测试规则混乱，AI 只会把混乱变得更快。
所以，AI 测试 Skills 最值得做的事情，不是让 AI 随便生成几条用例，而是把团队的测试经验沉淀下来：
哪些场景必须测
哪些断言不能漏
哪些字段要重点关注
哪些风险需要提前识别
哪些输出必须结构化
哪些流程可以自动化衔接
当这些东西进入 SKILL.md，它就不再是一段提示词。
它变成了测试团队的工程资产。
未来测试开发的差距，可能不只是谁更会用 AI。
而是谁能把测试经验沉淀成可复用、可版本化、可协作、可接入流程的 Skills 体系。
霍格沃兹测试开发学社，是一个专注软件测试、自动化测试、人工智能测试与测试开发的技术交流社区
