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. 创建或复用本次测试目录：

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

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

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

推荐目录结构

单轮测试：

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

A/B 对比测试：

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 这种重复编号。

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，建议使用以下结构：

# <技能名> 测试记录

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

## 测试 Prompt

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

## 观察结果

## 与预期行为对比

## 结论

## 是否需要写回技能

4. 对比和判断

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

5. 写回规则

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

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

写回时遵守仓库约定：

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

输出位置决策

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

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

完成前检查

结束测试前确认：

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