AI Agent 已经能写代码、查资料、跑测试、生成报告，单看能力很强。但把它真正放进复杂工作流后，经常会出现一种尴尬情况：它不是完全不会做，而是做得不稳定。
它可能能点页面，却漏掉隐藏入口；能生成报告，却只生成最显眼的 HTML 文件；能写脚本，却选择一条在当前 Shell 环境里会失败的命令；能输出结果，却把关键结构悄悄压缩掉。
这类问题的根源不是模型“笨”，而是通用模型默认具备的是通用能力，不是岗位能力。
通用能力解决的是：
- 能理解大概需求；
- 能生成一份像样的结果；
- 能根据上下文临时推理。
岗位能力解决的是：
- 在当前业务里，什么才算真正完成；
- 哪些步骤不能跳；
- 哪些细节过去最容易出错；
- 交付物应该长什么样；
- 失败后如何自检、修正、重跑。
Skill 的价值就在这里：把业务经验、执行步骤、质量标准、失败教训和验收规则，沉淀成 AI Agent 可以重复执行的岗位 SOP（标准作业程序）。
一句话概括：
Skill 不是让模型变聪明，而是让模型在指定业务里变可靠。
Skill 到底是什么
在 AI Agent 工作流里，Skill 可以理解为一组可复用的能力包。它通常不只是几句 Prompt，而是包含主说明、参考模板、检查清单、输出规范和门禁规则的一整套执行约束。
一个比较实用的 Skill 结构可以长这样：
web-testing/
├── SKILL.md
├── references/
│ ├── checklist-template.md
│ ├── report-template.md
│ └── ui-ux-checklist.md
各文件职责如下：
| 文件 | 作用 |
|---|---|
SKILL.md | 主控文件，定义触发条件、执行阶段、必须遵守的规则、失败模式和门禁 |
references/checklist-template.md | 执行过程中的进度控制表，用来防止漏步骤 |
references/report-template.md | 最终报告的结构契约，规定 Markdown 和 HTML 必须包含哪些模块 |
references/ui-ux-checklist.md | UI/UX 审查标准，例如可读性、对齐、表单反馈、状态提示等 |
如果只写一个很长的 Prompt，AI 可能一开始会照做，但任务一复杂、上下文一变长，就会开始丢细节。Skill 的设计重点不是“说清楚一次”，而是把任务拆成可执行、可检查、可阻断的流程。
为什么复杂任务里 AI 会“失忆”
大模型的上下文窗口是有限的。即使窗口很大，也不代表它会稳定记住所有约束。
复杂任务里常见的退化现象有四种：
| 现象 | 表现 | 后果 |
|---|---|---|
| 约束被稀释 | 前面写过的规则，后面执行时不再严格遵守 | 漏步骤、漏文件、漏检查 |
| 细节被压缩 | 输出越来越短，只保留看起来最重要的部分 | 报告结构缩水 |
| 成果优先偏差 | 优先生成最像最终结果的产物 | 只交 HTML，不交 Markdown 或站点地图 |
| 自检缺失 | 认为“看起来完成”就是“完成” | 隐藏问题难以被发现 |
所以，复杂任务不能只靠一句“请认真检查”。更可靠的写法是：
当页面存在 Tab、展开行、子表格、分页、弹窗、蓝色链接或可点击文本时：
1. 必须切换或展开后重新扫描 DOM；
2. 必须枚举所有候选链接；
3. 必须逐个验证是否进入新页面或触发新状态；
4. 如果仍存在未验证入口，禁止结束页面发现阶段。
这种规则由四部分组成：
触发条件 + 必做动作 + 自检方式 + 不通过后果
这才是 Skill 中真正有约束力的 SOP。
一个 web-testing Skill 的目标
以 web-testing 为例，它的目标是：输入任意网站链接，让 AI Agent 自动完成深度探索、测试、报告生成，甚至进一步驱动修复与回归验证。
理想流程如下：
flowchart TD
A[输入网站 URL] --> B[站点探索与页面发现]
B --> C[生成 sitemap]
C --> D[UI/UX 审查]
C --> E[功能测试]
C --> F[CRUD 链路测试]
D --> G[问题归类与严重程度评估]
E --> G
F --> G
G --> H[生成 Markdown 测试报告]
H --> I[生成 HTML 测试报告]
I --> J[人工确认]
J --> K[AI 根据报告修复问题]
K --> L[重新执行测试验证]
L --> G
报告通常需要包含：
- 总评分；
- 站点地图；
- 页面层级；
- 每个页面截图；
- UI/UX 审查结果；
- 功能测试结果；
- CRUD（创建、读取、更新、删除）链路测试；
- Bug 列表；
- 严重程度分级；
- 修复建议；
- Markdown 文件；
- HTML 文件。
这个任务看起来只是“自动测试网站”，实际复杂度很高。因为 AI 不仅要会操作浏览器，还要知道哪些入口必须穷举、哪些结果必须记录、哪些文件必须生成、哪些结构不能省略。
Skill 训练闭环
Skill 不是一次写完的。更可行的方式是让 AI 在真实任务里运行，然后把失败沉淀成新规则。
flowchart LR
A[执行真实任务] --> B[发现失败或遗漏]
B --> C[定位失败类型]
C --> D[分析根因]
D --> E[补充 Skill 规则]
E --> F[加入 Checklist 和门禁]
F --> G[重新执行验证]
G --> A
关键点不在“重新执行”，而在中间的规则沉淀：
- 把错误写成规则；
- 把经验写成 SOP；
- 把 SOP 写成 AI 自己也能检查的门禁。
坑一：AI 不是不会点击，而是不知道哪些入口必须点
Web 自动化测试的第一关是页面发现。页面没发现全，后面的 UI 审查、功能测试、问题归类都不可能完整。
一个常见失败场景是：某个深层页面入口藏在版本详情页的 Tab 里，Tab 内容区又有表格，表格里还有蓝色链接。AI 可能已经看到了 Tab，也看到了链接，但没有把这个链接当成“必须递归验证的新页面入口”。
它的问题不是没有能力点击，而是靠主观判断停下来了。
错误规则通常长这样：
请认真检查页面，不要遗漏入口。
这句话太抽象。AI 很难知道“认真”具体意味着什么。
更好的 Skill 规则应该写成：
页面发现阶段规则：
当页面出现以下任一结构时，必须进入递归扫描：
- Tab；
- 折叠面板；
- 展开行；
- 子表格；
- 分页；
- 弹窗；
- 蓝色链接；
- 带 hover 状态的文本；
- 图标按钮；
- 操作列中的查看、详情、编辑、配置、部署等入口。
执行要求：
1. 页面必须滚动到底部后再结束扫描；
2. 每切换一个 Tab，必须重新枚举 DOM 中的链接和按钮；
3. 每展开一行，必须扫描展开区域里的链接；
4. 每个候选入口都必须实际点击或打开验证；
5. 发现新 URL、新路由、新弹窗或新状态时，必须加入 sitemap；
6. 只要存在未验证候选入口，禁止结束页面发现阶段。
这条规则把“仔细”拆成了可执行动作。
页面发现可以按这样的流程控制：
flowchart TD
A[进入页面] --> B[滚动到底部]
B --> C[扫描 DOM]
C --> D{是否存在 Tab/表格/展开行/弹窗/链接}
D -- 否 --> H[记录页面并结束扫描]
D -- 是 --> E[逐个触发交互]
E --> F{是否产生新 URL/新状态/新弹窗}
F -- 是 --> G[加入待探索队列]
F -- 否 --> C
G --> C
这种规则适合所有需要“穷举”的场景。AI 天然倾向于根据语义判断重要性，但测试任务需要的是系统性穷举，而不是主观取舍。
坑二：AI 会优先生成最像成果的交付物
复杂任务经常有多个交付物。例如测试任务可能要求同时输出：
sitemap.md
test-report.md
test-report.html
AI 很容易只生成 test-report.html，因为 HTML 最像最终成果，也最复杂、最显眼。上下文变长后，模型会优先保住它认为最重要的东西，而忽略朴素但必需的文件。
解决方式不是补一句“记得全部生成”，而是把交付顺序和验收动作写死。
报告生成阶段必须按以下顺序执行：
1. 生成 sitemap.md；
2. 检查 sitemap.md 存在且大小大于 0；
3. 生成 test-report.md；
4. 检查 test-report.md 存在且大小大于 0；
5. 生成 test-report.html；
6. 检查 test-report.html 存在且大小大于 0；
7. 读取文件列表并确认三份文件全部存在；
8. 任一文件缺失或为空，禁止宣布任务完成。
对应的门禁可以写成脚本化检查：
test -s sitemap.md || { echo "sitemap.md missing or empty"; exit 1; }
test -s test-report.md || { echo "test-report.md missing or empty"; exit 1; }
test -s test-report.html || { echo "test-report.html missing or empty"; exit 1; }
复杂任务里，顺序本身就是质量控制。没有顺序，AI 会根据自己的注意力分配做取舍；有了顺序和门禁，它才会按交付契约执行。
坑三：AI 不一定懂当前环境里的工程约束
AI 生成方案时，有时会选择“看起来最省事”的做法。例如为了生成带截图的 HTML 报告，它可能用下面这种方式拼接长脚本：
python3 -c "非常长的一段 Python 代码，里面还包含大量 HTML 和 base64 图片数据"
这类写法有几个问题：
- Shell 命令长度有限；
- 超长字符串难以调试；
- base64 图片会让 HTML 急剧膨胀；
- 失败后很难定位是哪一段内容导致的；
- 同一个命令在不同环境里稳定性不同。
Skill 里必须明确工程边界，而不是默认 AI 会自动选择可维护方案。
工程约束：
禁止：
- 使用 python3 -c 生成长报告；
- 使用超长 echo 写入大文件；
- 在 HTML 中内嵌大量 base64 图片；
- 把多页报告拼进单条 Shell 命令。
必须：
- 将 Python 逻辑写入独立脚本文件后执行；
- HTML 中的截图使用本地相对路径引用；
- 大文件分步骤生成；
- 每一步生成后检查文件存在性和大小；
- 命令失败时保留中间文件，便于定位问题。
更稳定的写法是先生成脚本文件：
cat > generate_report.py <<'PY'
from pathlib import Path
html = """<!doctype html>
<html>
<head>
<meta charset="utf-8">
<title>Web Testing Report</title>
</head>
<body>
<h1>Web Testing Report</h1>
<img src="screenshots/home.png" alt="home page screenshot">
</body>
</html>
"""
Path("test-report.html").write_text(html, encoding="utf-8")
PY
python3 generate_report.py
test -s test-report.html || { echo "HTML report missing or empty"; exit 1; }
Skill 不只是业务手册，也应该是 AI Agent 的工程生存指南。否则业务逻辑可能没问题，最终却死在命令行长度、文件写入、路径引用这类基础工程约束上。
坑四：最危险的不是没生成，而是看起来生成了
报告生成阶段还有一种更隐蔽的问题：文件存在，内容也像报告，但关键结构被压缩掉了。
例如早期报告中每个页面都有独立模块：
- 页面截图；
- UI/UX 审查；
- 功能测试明细；
- 本页问题汇总；
- HTML 中的
page-card结构。
后续迭代中，AI 可能因为上下文消耗过多，在生成最终报告时进入“节约模式”，把逐页面详细模块压缩成一个整体问题列表。表面看报告还在，问题列表也在，但报告已经不满足交付契约。
这种错误最危险，因为它很容易通过粗略验收。
解决方式是给报告结构加门禁：
报告结构完整性 Checklist：
- [ ] sitemap 中的页面数已统计；
- [ ] Markdown 报告中的页面模块数 = sitemap 页面数；
- [ ] HTML 报告中的 page-card 数量 = sitemap 页面数；
- [ ] 每个页面都有截图；
- [ ] 每个页面都有 UI/UX 审查；
- [ ] 每个页面都有功能测试结果表；
- [ ] 每个页面都有本页问题汇总；
- [ ] 总问题汇总表存在；
- [ ] 严重程度分级存在；
- [ ] 修复计划表存在；
- [ ] 数据清理记录存在；
- [ ] 任一检查失败时，禁止宣布报告完成。
也可以让 AI 执行简单的结构校验：
from pathlib import Path
import re
sitemap = Path("sitemap.md").read_text(encoding="utf-8")
report_md = Path("test-report.md").read_text(encoding="utf-8")
report_html = Path("test-report.html").read_text(encoding="utf-8")
# 假设 sitemap 中页面行使用 "- /path" 格式
page_count = len(re.findall(r"^- /", sitemap, flags=re.M))
md_page_modules = len(re.findall(r"^## 页面：", report_md, flags=re.M))
html_page_cards = report_html.count('class="page-card"')
errors = []
if md_page_modules != page_count:
errors.append(f"Markdown 页面模块数不匹配：{md_page_modules} != {page_count}")
if html_page_cards != page_count:
errors.append(f"HTML page-card 数量不匹配：{html_page_cards} != {page_count}")
required_sections = ["问题汇总", "严重程度分级", "修复计划", "数据清理记录"]
for section in required_sections:
if section not in report_md:
errors.append(f"Markdown 缺少章节：{section}")
if errors:
for error in errors:
print(error)
raise SystemExit(1)
print("报告结构检查通过")
复杂任务不能只验收“有没有文件”，还要验收“结构是不是完整”。没有结构门禁，AI 很容易从完整交付滑向表面完成。
把失败写回 Skill：一套可复用方法
训练 Skill 可以按四步走。
1. 先跑真实任务，再写规则
不要一开始就闭门设计一大份 Skill。更有效的方式是让 AI Agent 先跑 3～5 次真实任务，然后观察它怎么失败。
重点记录这些问题：
| 观察点 | 示例 |
|---|---|
| 漏了什么 | 漏掉 Tab 下的深层页面 |
| 跳了哪一步 | 没有生成 sitemap |
| 哪些结果只是看起来完成 | 报告存在，但缺少逐页面模块 |
| 哪些错误重复出现 | 每次都忘记检查文件大小 |
| 哪些方案不适合当前环境 | 使用超长 python3 -c |
没有真实失败，很难写出有用规则。Skill 应该从执行结果里长出来，而不是从想象里写出来。
2. 把要求改写成 SOP
抽象要求对 AI 的约束力很弱。写 Skill 时，要尽量把形容词改成动作。
| 弱规则 | 强规则 |
|---|---|
| 请仔细检查页面 | 页面存在 Tab、展开行、表格、弹窗时，必须逐个触发并重新扫描 DOM |
| 请保证报告完整 | 页面模块数必须等于 sitemap 页面数，HTML 中 page-card 数量也必须等于页面数 |
| 请自查结果 | 每个阶段结束前必须执行 checklist，失败则回到对应阶段修复 |
| 请生成所有文件 | 按固定顺序生成文件，每生成一个就检查存在且大小大于 0 |
强规则的格式建议统一成：
规则名称：
触发条件：
必做动作：
自检方式：
不通过后果：
例如：
规则名称：Tab 内容递归扫描
触发条件：
页面存在 Tab 或类似分栏切换组件。
必做动作：
逐个切换 Tab，并在每次切换后重新扫描 DOM 中的链接、按钮、表格操作列和弹窗入口。
自检方式：
记录已访问 Tab 数量、每个 Tab 中发现的候选入口数量、已验证入口数量。
不通过后果：
如果存在未验证入口，禁止结束页面发现阶段。
3. Checklist 和门禁必须同时存在
Checklist 解决“检查什么”的问题，门禁解决“不检查会怎样”的问题。
只有 Checklist，没有门禁，AI 可能知道要检查，但为了节省上下文直接跳过。
只有门禁，没有 Checklist，AI 不知道具体怎么判断通过或失败。
一个阶段控制模板可以这样写：
# 阶段门禁表
## 阶段 1：页面发现
- [ ] 已访问首页
- [ ] 已滚动到页面底部
- [ ] 已扫描导航菜单
- [ ] 已扫描 Tab
- [ ] 已扫描展开行
- [ ] 已扫描表格操作列
- [ ] 已验证所有候选链接
- [ ] 已生成 sitemap.md
- [ ] sitemap.md 文件存在且大小大于 0
门禁：
任一检查项未完成，禁止进入阶段 2。
阶段之间的关系可以设计成阻断式：
flowchart TD
A[阶段 1：页面发现] --> B{页面发现门禁通过?}
B -- 否 --> A
B -- 是 --> C[阶段 2：UI/UX 审查]
C --> D{UI/UX 门禁通过?}
D -- 否 --> C
D -- 是 --> E[阶段 3：功能与 CRUD 测试]
E --> F{功能测试门禁通过?}
F -- 否 --> E
F -- 是 --> G[阶段 4：报告生成]
G --> H{报告结构门禁通过?}
H -- 否 --> G
H -- 是 --> I[任务完成]
4. 让 AI 参与 Skill 复盘
AI 不应该只是执行者，也可以成为 Skill 的共同维护者。每次执行失败后，可以让它基于结果分析根因，并直接输出应该补充到 Skill 里的规则。
可复用指令如下：
请基于本次执行结果，对当前 Skill 做一次复盘：
1. 哪些输出没有达到预期？
2. 每个问题属于哪一类：
- 页面发现
- 交付完整性
- 工程约束
- 报告结构完整性
- 消费场景适配
3. 根因是什么：
- 规则缺失
- 规则不明确
- 缺少 checklist
- 缺少门禁
- 上下文过长导致细节被压缩
- 当前执行环境约束未声明
4. 请给出应该补充到 Skill 中的具体规则，必须包含：
- 触发条件
- 必做动作
- 自检方式
- 不通过后果
5. 直接输出修改后的 Skill 片段。
6. 说明这次修改预期解决什么问题。
这样可以把一次失败转化成长期规则。Skill 的质量会随着真实执行次数增加而提高。
一个可落地的 SKILL.md 片段
下面是 web-testing Skill 主控文件可以采用的写法示例：
# web-testing Skill
## 触发条件
当用户提供网站 URL，并要求进行页面探索、UI/UX 审查、功能测试、CRUD 测试、测试报告生成或自动化质量审查时，启用本 Skill。
## 总目标
对目标网站进行完整探索和测试，输出：
1. sitemap.md
2. test-report.md
3. test-report.html
4. screenshots/ 目录
5. 问题汇总与修复建议
## 阶段 1：页面发现
### 必做动作
- 访问首页；
- 扫描导航菜单；
- 滚动到页面底部；
- 扫描 Tab、折叠面板、展开行、表格操作列、分页、弹窗；
- 对所有候选入口进行点击或打开验证；
- 发现新 URL、新路由、新弹窗、新状态时，加入 sitemap；
- 递归处理所有新页面，直到不存在未验证入口。
### 门禁
只有满足以下条件，才能进入阶段 2：
- sitemap.md 已生成；
- sitemap.md 文件大小大于 0；
- 不存在未验证候选入口；
- 每个页面都已记录页面类型：
- 只读页面
- 表单页面
- CRUD 页面
- 配置页面
- 详情页面
## 阶段 2：UI/UX 审查
对 sitemap 中每个页面执行 UI/UX 审查，检查：
- 布局一致性；
- 视觉层级；
- 表单可用性；
- 错误提示；
- 空状态；
- 加载状态；
- 响应式表现；
- 可访问性基础问题。
门禁：
每个页面都必须有 UI/UX 审查记录。
## 阶段 3：功能与 CRUD 测试
对可操作页面执行功能测试。
如果页面包含创建、读取、更新、删除能力，必须执行完整 CRUD 链路。
门禁：
每个可操作页面都必须有测试结果表。
如果无法测试，必须说明阻塞原因。
## 阶段 4：报告生成
必须按顺序生成：
1. sitemap.md
2. test-report.md
3. test-report.html
每生成一个文件，必须检查：
- 文件存在；
- 文件大小大于 0；
- 内容包含必需章节。
报告结构门禁：
- Markdown 页面模块数 = sitemap 页面数；
- HTML page-card 数量 = sitemap 页面数；
- 每个页面都有截图、UI/UX 审查、功能测试结果、本页问题汇总；
- 总问题汇总表存在；
- 修复计划存在。
任一检查失败，禁止宣布任务完成。
这种写法比“请完整测试网站并生成报告”更长，但它能显著降低 AI 自由发挥带来的不确定性。
Skill 适合什么场景，不适合什么场景
| 场景 | 是否适合 Skill | 原因 |
|---|---|---|
| 自动化测试 | 适合 | 流程长、交付物多、容易漏步骤，需要门禁 |
| 代码审查 | 适合 | 可以沉淀规则、检查项、严重程度分类 |
| 线上故障排查 | 适合 | 需要固定排查路径、日志采集规则、升级条件 |
| 数据分析报告 | 适合 | 输出结构固定，适合模板化和质量检查 |
| 临时闲聊问答 | 不太适合 | 任务短、复用价值低 |
| 一次性创意发散 | 不太适合 | 过强规则可能限制探索空间 |
| 需求极不稳定的早期探索 | 谨慎使用 | 可以先积累失败案例，再沉淀 Skill |
判断是否值得写 Skill，可以看三个问题：
- 这个任务会不会重复执行？
- 失败是否有规律？
- 交付结果是否需要稳定验收？
如果三个答案都是“是”，就值得把流程沉淀成 Skill。
常见误区
| 误区 | 问题 | 改法 |
|---|---|---|
| 把 Skill 当长 Prompt | 只描述目标，不约束过程 | 写执行阶段、检查项、门禁 |
| 只写正向流程 | 没有覆盖失败模式 | 把真实翻车写成规则 |
| 只让 AI 自觉检查 | 上下文变长后容易跳过 | Checklist 后必须加阻断条件 |
| 不声明工程环境限制 | AI 可能选不稳定方案 | 写清命令长度、文件写入、路径引用等约束 |
| 一次写完后不再维护 | 业务变化后规则过期 | 每次失败后复盘并更新 Skill |
可靠 AI Agent 的核心不是上限，而是下限
业务里最怕的不是 AI 偶尔不够惊艳，而是交付质量不稳定：
- 这次页面发现完整，下次漏掉深层入口；
- 这次三份文件齐全，下次只交一份 HTML；
- 这次报告结构完整，下次悄悄压缩；
- 这次截图路径正确，下次全部失效。
Skill 解决的就是下限问题。它把“靠模型状态发挥”变成“靠机制稳定交付”。
一个成熟的 Skill 至少要具备四类内容：
业务流程：任务分几个阶段，每个阶段做什么
执行动作：遇到具体场景时必须怎么做
质量门禁：做到什么程度才允许进入下一阶段
复盘机制：失败后如何把经验写回 Skill
把 AI Agent 当作一个聪明新人来训练，会更容易理解 Skill 的设计方式。新人不是只听一句“认真点”就能稳定交付，他需要流程、样例、检查表、验收标准和失败反馈。AI Agent 也一样。
Skill 的最终目标不是让 AI 看起来更会说，而是让它在真实业务中做到：
- 知道流程；
- 记住教训；
- 会自检；
- 过门禁；
- 稳定交付。