新手小白也能写出好用Skill：保姆级教程与分享

一、Skill 是什么？

简单来说，Skill 文件就是一份给 AI 的“工作说明书”。它的核心目的，就是告诉 AI 面对具体任务时，应该遵循什么规则、输出什么样的结果。

不妨设想一下：如果没有这份说明书，AI 每次生成的代码风格、覆盖的测试用例、甚至选择器写法都可能五花八门。但有了 Skill，情况就完全不同了——AI 就像一个被你手把手调教过的测试同事，每次输出都稳稳贴合团队规范，省心又高效。

二、Skill 文件放在哪里？

文件存放的结构其实很直观：文件夹就像封面，.SKILL.md 才是真正的说明书。

项目文件夹
└── xx.SKILL.md ← 这就是说明书

文件名可以任意起，后缀必须是 .SKILL.md。而且说明书不止一本——每个功能模块都可以单独维护一个文件，彼此互不干扰，灵活又清晰。

三、Skill 文件的结构

一个完整的 Skill 文件，其实就由两块组成：

（头部信息：描述这个 Skill 是干什么的）
（正文：告诉 AI 具体怎么做）

是不是很简单？

四、头部信息逐行拆解

先看几个核心字段，理解它们的实际用途：

name: Login Testing

Skill 的名字，随便起，但最好一眼就能让人看懂这个文件是干嘛用的。

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：强烈建议使用英文。大模型对英文指令的理解比中文更稳定，出错概率也低得多。