新手小白写出好用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 读到文件内容后，就会照着里面的规范执行，效果完全一样。

不仅如此，你还可以持续追问：

来看一个实际效果的演示（以Claude Code为例）：

接下来是安装依赖的过程，中间遇到问题都由大模型自动解决，最终效果如下：

直接复用即可。

七、不同 AI 工具如何让 Skill 自动生效？

.claude/skills/ 是 Kiro 的专属路径，其他工具有各自约定的规则文件位置。把 Skill 正文内容复制到对应文件里，工具启动时就会自动加载。

Skill 正文内容是通用的，换工具只需要换个文件名，内容复制过去即可。

八、写 Skill 的几个原则

九、常见问题

Q：Skill 文件不生效怎么办？
A：检查后缀是否写完整，必须是 .SKILL.md，而不是普通的 .md。

Q：可以有多个 Skill 文件吗？
A：当然可以。每个功能模块一个文件，比如 login-testing.SKILL.md、api-testing.SKILL.md，互不干扰。

Q：Skill 里的代码示例要和项目完全一致吗？
A：不需要完全一致。AI 会根据示例风格来生成代码，细节部分它会自动适配。

Q：正文必须用英文吗？
A：强烈建议使用英文。大模型对英文指令的理解比中文更稳定，出错概率也低得多。