一、Skill 是什么？
简单来说，Skill 文件就是一份交付给 AI 的“工作说明书”。它的核心目标，是明确告知 AI 在应对具体任务时，应遵循哪些规则、输出什么类型的结果。
不妨设想一下：如果没有这份说明书，AI 每次生成的代码风格、覆盖的测试用例、甚至选择器写法都可能五花八门。但有了 Skill，情况就完全不同了——AI 就像一个被你手把手调教过的测试同事，每次输出都稳稳贴合团队规范，省心又高效。
二、Skill 文件放在哪里？
文件存放的结构其实很直观：文件夹就像封面，.SKILL.md 才是真正的说明书。
项目文件夹
└── xx.SKILL.md ← 这就是说明书文件名可以任意设定，后缀必须为 .SKILL.md。而且说明书不止一本——每个功能模块都可以单独维护一个文件，彼此互不干扰，灵活又清晰。
三、Skill 文件的结构
一个完整的 Skill 文件，其实就由两块组成：
（头部信息：描述这个 Skill 是干什么的）
（正文：告诉 AI 具体怎么做）是不是很简单？
四、头部信息逐行拆解
先看几个核心字段，理解它们的实际用途：
name: Login TestingSkill 的名称，可自由定义，但最好一眼就能让人看懂这个文件是干嘛用的。
description: Step-by-step login test cases covering happy path, error handling, and edge cases一句话描述能力范围。AI 会靠这个字段来判断是否要激活该 Skill，所以写清楚非常关键。
version: 1.0.0版本号，首次编写填 1.0.0 即可。
author: your-team作者，填写你的名字或团队名称。
testingTypes: [functional, e2e]测试类型。常见值有 functional（功能测试）、e2e（端到端）、visual（视觉）、api（接口）。
frameworks: [playwright, selenium, cypress]支持的框架，填写你们团队正在使用的即可。
languages: [typescript, javascript, python]支持的语言，AI 会根据项目自动选择匹配的。
domains: [web]适用场景，web 表示网页测试，还有 mobile、api 等选项。
agents: [claude-code, cursor, github-copilot, windsurf, cline]支持哪些 AI 工具。这本质上是一个意图声明，告诉使用者或系统，这份说明书兼容哪些工具——但注意，并不代表放进去就自动生效，具体还需要看工具的约定。
五、正文怎么写？
正文就是用自然语言给 AI 划规矩，写得越具体，AI 就越听话。
5.1 先告诉 AI 它的角色
You are a senior QA engineer. When the user asks you to write, review,
or improve login test cases, follow these instructions precisely.翻译过来就是：你是一位资深 QA 工程师，用户要求编写或评审登录测试用例时，严格按以下规则操作。
给 AI 一个明确的角色定位，它的输出会更专业、更聚焦。
5.2 告诉 AI 必须做什么
## What You Must Always Do
1. Cover the happy path first.
2. Cover error cases — wrong password, wrong username, empty fields.
3. Use descriptive test names.
4. Each test must be independent.简单说就是：先写正常流程，再写异常流程，测试名要能看懂在测什么，每个用例必须独立。
5.3 给 AI 一个固定的用例结构
Every login test must follow this structure:
GIVEN [the user is on the login page]
WHEN [the user performs an action]
THEN [the expected result happens]经典的 Given-When-Then 格式，测试同学基本都熟悉。告诉 AI 用这个格式，生成的用例逻辑会清晰很多。
5.4 列出必须覆盖的用例
## Required Test Cases
Always generate at least these 6 test cases:
1. Valid credentials → redirect to dashboard
2. Wrong password → show error message
3. Wrong username → show error message
4. Empty username → show inline validation
5. Empty password → show inline validation
6. Both fields empty → show both validation messages明确列出最低要求，否则 AI 可能会偷懒，只写 2-3 条就交差。
5.5 给一个完整的代码示例
这是 Skill 文件里最有价值的部分。给 AI 一个标准答案，它之后生成的代码就会自动对齐这个风格。
## Example Output (Playwright + TypeScript)
When the user asks for Playwright tests, generate code in this exact format:
```typescript
import { test, expect } from '@playwright/test';
const STANDARD_USER = 'standard_user';
const VALID_PASS = 'secret_sauce';
test.describe('Login Page', () => {
test.beforeEach(async ({ page }) => {
await page.goto('https://www.saucedemo.com');
});
test('TC01 - standard_user 正常登录应跳转到商品列表页', async ({ page }) => {
await page.getByPlaceholder('Username').fill(STANDARD_USER);
await page.getByPlaceholder('Password').fill(VALID_PASS);
await page.getByRole('button', { name: 'Login' }).click();
await expect(page).toHaveURL(/inventory.html/);
});
});
```注意这里的设计细节：测试名带编号 TC01 方便追踪，beforeEach 统一处理打开登录页，避免在每个用例里重复写。
5.6 告诉 AI 绝对不能做什么
## What You Must Never Do
- Never use waitForTimeout or sleep.
- Never write a test that depends on another test.
- Never ignore the error message text.禁止清单同样重要。AI 有时候会走捷径，比如用 sleep(3000) 来等待页面加载——明确禁止了，它就不会这么干。
六、怎么用这个 Skill？
其实一句话就能说清楚：把说明书的路径告诉 AI，它就能按规范干活。
用 @ 手动指定文件路径，AI 读到文件内容后，就会照着里面的规范执行，效果完全一样。
不仅如此，你还可以持续追问：
| 你说 | AI 会做 |
|---|---|
| "再加上 problem_user 的测试" | 补充图片异常的断言 |
| "帮我加上 Page Object Model" | 把代码重构成 POM 结构 |
| "改成 Python + pytest 版本" | 换语言重新生成 |
| "这个用例的断言对吗？" | 帮你 review 代码 |
来看一个实际效果的演示（以Claude Code为例）：
接下来是安装依赖的过程，中间遇到问题都由大模型自动解决，最终效果如下：
直接复用即可。
七、不同 AI 工具如何让 Skill 自动生效？
.claude/skills/ 是 Kiro 的专属路径，其他工具有各自约定的规则文件位置。把 Skill 正文内容复制到对应文件里，工具启动时就会自动加载。
| 工具 | 把正文内容放到这个文件 |
|---|---|
| Kiro | .claude/skills/*.SKILL.md |
| Claude Code | CLAUDE.md |
| Cursor | .cursorrules 或 .cursor/rules/*.mdc |
| Windsurf | .windsurfrules |
| Cline | .clinerules 或 .clinerules/*.md |
Skill 正文内容是通用的，换工具只需要换个文件名，内容复制过去即可。
八、写 Skill 的几个原则
| 原则 | 说人话 |
|---|---|
| 角色明确 | 告诉 AI 它是谁 |
| 规则具体 | 越细越好，别指望 AI 猜你的意思 |
| 给示例 | 一个好例子胜过一百句描述 |
| 写禁止清单 | 把你不想看到的东西明确列出来 |
| 用英文写正文 | 大模型对英文指令理解更准确、更稳定 |
九、常见问题
Q：Skill 文件不生效怎么办？
A：检查后缀是否写完整，必须是 .SKILL.md，而不是普通的 .md。
Q：可以有多个 Skill 文件吗？
A：当然可以。每个功能模块一个文件，比如 login-testing.SKILL.md、api-testing.SKILL.md，互不干扰。
Q：Skill 里的代码示例要和项目完全一致吗？
A：不需要完全一致。AI 会根据示例风格来生成代码，细节部分它会自动适配。
Q：正文必须用英文吗？
A：强烈建议使用英文。大模型对英文指令的理解比中文更稳定，出错概率也低得多。
