# Skill Test Workflow

> ---

- Skill: `xiao0916/skill-test-workflow` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add xiao0916/skill-test-workflow`
- Raw SKILL.md: https://api.skillmd.com/api/skills/xiao0916/skill-test-workflow/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: xiao0916 (https://skillmd.com/u/xiao0916)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/xiao0916/skill-test-workflow

---

---
name: skill-test-workflow
description: "测试、评估或对比 AI agent 技能时必须使用本技能。它规范被测试技能的准备、运行、记录、A/B 对比和产物保存位置，尤其要求测试记录写入 test-results/<技能名>/，技能生成的文件、截图、导出物或临时演示项目写入 outputs/<技能名>/，避免把测试产物混入 skills/ 源码目录。适用于用户要求测试某个技能、跑 eval、验证技能表现、比较使用技能与不使用技能的输出、记录测试观察，或基于测试反馈改进技能。"
---

# Skill Test Workflow

用于规范测试其他技能时的工作方式、记录格式和产物位置。本技能的目标是让测试过程可复盘，同时保持 `skills/` 目录只保存可复用的技能源码。

## 核心原则

- `skills/` 是技能源码目录。测试时不要把运行产物、截图、临时 demo、评测报告或观察笔记写入被测技能目录，除非是在更新该技能自身的 `SKILL.md`、`USAGE.md`、`evals/` 或辅助资源。
- 测试记录默认保存到 `test-results/<被测技能名>/`。
- 被测技能运行时生成的文件、截图、导出物或临时演示项目默认保存到 `outputs/<被测技能名>/`。
- 如果被测技能的核心行为会生成文件、目录、截图、导出物、代码或临时 demo，测试时必须在 `outputs/<被测技能名>/<本次测试>/` 下生成一个最小真实运行样例。静态规则检查只能作为补充，不能替代运行产物测试。
- 如果测试结论只能描述一次性表现，写入测试记录；只有当结论能改进通用行为时，才写回被测技能的 `SKILL.md` 或 eval 文件。

## 触发后先做

1. 确认被测技能名。如果用户只描述能力，先在 `skills/` 中查找最匹配的技能。
2. 读取 `skills/<被测技能名>/SKILL.md`。如果用户询问使用方式且 `USAGE.md` 存在，也读取 `skills/<被测技能名>/USAGE.md`。
3. 如果存在 `skills/<被测技能名>/evals/`，优先使用其中的测试 prompt 或评估说明。
4. 创建或复用本次测试目录：

```text
test-results/<被测技能名>/<YYYY-MM-DD>-<短描述>-<NNN>.md
outputs/<被测技能名>/<YYYY-MM-DD>-<短描述>-<NNN>/
```

短描述使用小写英文、数字和连字符，例如 `basic`, `ab-comparison`, `output-paths`。

`<NNN>` 是固定 3 位零填充的序号，从 `001` 起，每次都带（包括首次）。它的作用是避免同一天用同一短描述多次测试时文件名互相覆盖。序号生成规则见下文「序号生成规则」。

## 推荐目录结构

单轮测试：

```text
test-results/<技能名>/
  2026-06-29-basic-001.md
outputs/<技能名>/
  2026-06-29-basic-001/
    generated-files/
    screenshots/
    exports/
    demo/
```

A/B 对比测试：

```text
test-results/<技能名>/
  2026-06-29-ab-comparison-001.md
outputs/<技能名>/
  2026-06-29-ab-comparison-001/
    with-skill/
      outputs/
      notes.md
    without-skill/
      outputs/
      notes.md
```

多轮迭代测试：短描述统一用 `iteration`，由序号承担轮次区分，避免出现 `iteration-1-001` 这种重复编号。

```text
test-results/<技能名>/
  2026-06-29-iteration-001.md
  2026-06-29-iteration-002.md
outputs/<技能名>/
  2026-06-29-iteration-001/
  2026-06-29-iteration-002/
```

## 序号生成规则

序号针对「同一天 + 同一短描述」独立递增，不同日期或不同短描述互不干扰。`test-results` 的 `.md` 与 `outputs` 的同名目录共享同一序号，保持配对。

生成步骤：

1. 创建前，列出 `test-results/<技能名>/` 中匹配 `<当天日期>-<本次短描述>-NNN` 的文件，以及 `outputs/<技能名>/` 中匹配同名模式的目录。两侧都看，取最大序号。
2. 取到的最大序号 +1，零填充到 3 位；两侧都无匹配则用 `001`。
3. 用算出的序号同时生成 `.md` 和同名 `outputs` 目录，保证配对一致。

示例：已存在 `2026-06-29-basic-001.md`，本次短描述也是 `basic` → 新建 `2026-06-29-basic-002.md` 及配对 `outputs/<技能名>/2026-06-29-basic-002/`。同一天另起一次 `ab-comparison` 测试则从 `001` 开始，不受 `basic` 序号影响。

## 测试流程

### 1. 准备测试

- 记录使用的 agent、当前日期、被测技能路径和测试目的。
- 列出测试 prompt。条件允许时，用同一个 prompt 分别测试“使用技能”和“不使用技能”的表现。
- 如果用户指定输出位置，遵守用户指定；否则使用本技能的默认目录。

### 2. 运行测试

- 使用技能测试时，明确加载并遵守 `skills/<技能名>/SKILL.md`。
- 不使用技能测试时，用相同 prompt 执行基线测试，不读取被测技能的指令。
- 将所有生成文件放到 `outputs/<技能名>/<本次测试>/` 下，按 `with-skill/`、`without-skill/` 或产物类型分组。
- 不要把被测技能生成的临时项目放进 `skills/<技能名>/`。

### 2.1 运行产物验证

测试生成型技能时，先判断被测技能的核心承诺是什么：

- 如果它承诺创建文档、目录、项目骨架、代码文件、截图、导出物或预览 demo，必须运行一个最小样例，让这些产物实际出现在 `outputs/<技能名>/<本次测试>/` 中。
- 如果技能有确认门禁、外部依赖或安全限制，不能完整跑完流程，也要生成真实停点产物，并在测试记录中说明停止原因。例如分阶段工作流技能应至少生成初始状态文件和第一阶段文档，然后停在“等待确认”的状态。
- 如果为了说明后续阶段结构而创建夹具或模拟产物，必须清楚标注为 fixture、mock 或 assumed-confirmation，不能把它写成真实自动运行结果。
- 静态断言、规则覆盖、文件存在性检查只能用来补充判断。除非被测技能本身不产生任何文件或外部产物，否则不要把静态测试作为唯一测试结果。
- 如果本轮确实没有生成运行产物，必须在测试记录和最终回复中明确写出“本轮未验证运行产物”，并解释原因。

### 3. 记录结果

测试记录写入 `test-results/<技能名>/<YYYY-MM-DD>-<短描述>-<NNN>.md`，建议使用以下结构：

```markdown
# <技能名> 测试记录

## 基本信息
- 日期：
- Agent：
- 被测技能：
- 测试目的：
- 相关 eval：

## 测试 Prompt

## 输出位置
- 测试记录：
- 运行产物：
- 最小真实样例：
- 静态检查结果：

## 观察结果

## 与预期行为对比

## 结论

## 是否需要写回技能
```

### 4. 对比和判断

- 将实际输出与 `evals/`、测试笔记或用户描述的预期行为对比。
- 记录使用技能与不使用技能的关键差异，包括输出质量、步骤完整性、目录规范、是否误改源码、是否遗漏验证。
- 如果结论依赖人工判断，明确标注为观察结论，不要伪装成量化结果。

### 5. 写回规则

只有满足以下条件之一，才修改被测技能：

- 多次测试暴露同一种通用失败模式。
- 当前 `SKILL.md` 缺少会稳定影响未来行为的约束。
- eval prompt 无法覆盖关键使用场景，需要新增或更新。
- 用户明确要求根据测试结果改进技能。

写回时遵守仓库约定：

- 保留技能目录名和 frontmatter 中的 `name` 字段，除非用户明确要求重命名。
- `SKILL.md` 只记录可复用的 agent 行为，不记录一次性的测试经历。
- 大型参考资料、模板、脚本或示例放入辅助文件，不要塞进 `SKILL.md`。

## 输出位置决策

使用以下规则判断文件应该放在哪里：

| 内容 | 默认位置 |
|---|---|
| 测试观察、结论、人工反馈 | `test-results/<技能名>/` |
| 被测技能生成的文档、图片、截图、导出物 | `outputs/<技能名>/` |
| 临时 demo 项目、预览 HTML、运行中间文件 | `outputs/<技能名>/` |
| 测试 prompt 和可复用 eval 定义 | `skills/<技能名>/evals/` |
| 对技能通用行为的改进 | `skills/<技能名>/SKILL.md` 或辅助文件 |
| 面向人的技能使用说明 | `skills/<技能名>/USAGE.md` |

如果不确定，把一次性内容放进 `test-results/` 或 `outputs/`，不要放进 `skills/`。

## 完成前检查

结束测试前确认：

- 已读取被测技能的 `SKILL.md`。
- 如果存在 `evals/`，已优先参考。
- 测试记录位于 `test-results/<技能名>/`。
- 技能生成产物位于 `outputs/<技能名>/`。
- 如果被测技能会生成文件或目录，`outputs/<技能名>/<本次测试>/` 下存在最小真实运行样例，而不只是断言摘要。
- 如果流程因确认门禁或依赖限制停下，测试记录说明了真实停点和原因。
- 如果包含模拟后续阶段的产物，已明确标注为 fixture 或 mock。
- 没有把运行产物写入 `skills/<技能名>/`。
- 已说明是否需要把测试结论写回技能。