autoresearch

用于技能的自动研究

大多数技能在大约 70% 的情况下都能正常工作。剩下 30% 的时候，输出就会一团糟。解决办法不是从头重写技能，而是让 Agent 运行几十次，对每次输出评分，并不断完善提示词，直到消除这 30% 的问题。

这项技能将 Andrej Karpathy 的自动研究方法（自主实验循环）应用于 Claude Code 技能。我们优化的不是机器学习训练代码，而是技能提示词。

---

核心任务

选取任意现有技能，定义“良好输出”的标准，并将其拆解为是／否二元检查项，然后运行自主循环：

1. 使用测试输入生成技能输出
2. 根据评估标准为每次输出评分
3. 修改技能提示词以修复失败之处
4. 保留能提高分数的修改，舍弃其余修改
5. 重复以上步骤，直到达到分数上限或用户停止

**输出：**改进后的 SKILL.md + results.tsv 日志 + 记录每次尝试修改的 changelog.md + 可在浏览器中查看的实时 HTML 仪表板。

---

开始前：收集上下文

停止。确认用户提供以下所有信息之前，不要运行任何实验。缺少信息时，先向用户询问。

1. 目标技能 — 你想优化哪项技能？（需要 SKILL.md 的确切路径）
2. 测试输入 — 我们应该用哪些 3–5 种不同的提示词／场景来测试这项技能？（多样性很重要——选择能覆盖不同用例的输入，避免只针对单一场景过拟合）
3. 评估标准 — 哪些 3–6 项是／否二元检查可以定义良好输出？（这些就是你的“测试问题”——有关如何编写优质评估项，请参阅 eval-guide.md）
4. 每次实验的运行次数 — 每项修改应运行多少次技能？默认值：5。（运行次数越多，评分越可靠，但速度越慢、成本越高。对大多数技能来说，5 次最合适。）
5. 运行间隔 — 实验应多久循环一次？默认值：每 2 分钟。（间隔越短，迭代越快，但成本越高）
6. 预算上限 — 可选。停止前最多进行多少轮实验。默认值：不限（持续运行，直到你停止）。

---

步骤 1：阅读技能

在做任何更改之前，先完整阅读并理解目标技能。

1. 阅读完整的 SKILL.md 文件
2. 阅读该技能链接到的 references/ 中的所有文件
3. 确定该技能的核心任务、流程步骤和输出格式
4. 记录技能中已有的任何质量检查或反模式

**不要跳过此步骤。**你需要先了解技能的作用，才能对其进行改进。

---

步骤 2：构建评估套件

将用户的评估标准转换为结构化测试。每项检查都必须是二元的——通过或失败，不使用等级。

按以下格式编写每项评估：

EVAL [number]: [Short name]
Question: [Yes/no question about the output]
Pass condition: [What "yes" looks like — be specific]
Fail condition: [What triggers a "no"]

编写优质评估项的规则：

• 仅限二元判断。是或否。不要使用“评分 1–7”这类量表。量表会叠加可变性，导致结果不可靠。
• 具体明确，确保判断一致。“文本是否易读？”太模糊。“是否所有单词都拼写正确，且没有截断的句子？”则可以测试。
• 不要过于狭窄，以免技能钻评估项的空子。“少于 200 个字”会让技能一味追求简短，而忽略其他方面。
• 3–6 项评估最合适。超过这个数量后，技能就会开始照搬评估标准，而不是真正改进。

有关优质与劣质评估项的详细示例，请参阅 eval-guide.md。

最高分计算：

max_score = [number of evals] × [runs per experiment]

示例：4 项评估 × 5 次运行 = 最高 20 分。

---

第 3 步：生成实时仪表板

运行任何实验之前，请先在 autoresearch-[skill-name]/dashboard.html 创建实时 HTML 仪表板，并在浏览器中打开。

仪表板必须：

• 每 10 秒自动刷新（读取 results.tsv）
• 显示分数变化折线图（X 轴为实验编号，Y 轴为通过率 %）
• 为每个实验显示彩色条：绿色 = 保留，红色 = 丢弃，蓝色 = 基线
• 显示包含所有实验的表格，列出：实验编号、分数、通过率、状态、描述
• 显示各项评测的细分结果：所有运行中通过率最高/最低的评测项
• 显示当前状态：“正在运行实验 [N]……”或“空闲”
• 使用简洁的样式和柔和的颜色（白色背景、柔和的点缀色、简洁的无衬线字体）

将仪表板生成为单个独立的 HTML 文件，内含 CSS 和 JavaScript。使用从 CDN 加载的 Chart.js 绘制折线图。JavaScript 应获取 results.json（每次实验后，你都要同时更新该文件和 results.tsv），并重新渲染页面。

创建后立即打开：open dashboard.html（macOS），让用户可以在浏览器中查看。

每次实验后都要更新 results.json，确保仪表板保持最新。JSON 格式：

{
  "skill_name": "[name]",
  "status": "running",
  "current_experiment": 3,
  "baseline_score": 70.0,
  "best_score": 90.0,
  "experiments": [
    {
      "id": 0,
      "score": 14,
      "max_score": 20,
      "pass_rate": 70.0,
      "status": "baseline",
      "description": "original skill — no changes"
    }
  ],
  "eval_breakdown": [
    {"name": "Text legibility", "pass_count": 8, "total": 10},
    {"name": "Pastel colors", "pass_count": 9, "total": 10}
  ]
}

运行结束时（用户停止运行或达到上限时），将 status 更新为 "complete"，让仪表板显示“已完成”状态和最终摘要。

---

第 4 步：建立基线

在更改任何内容之前，按原样运行技能。这是实验 #0。

1. 在技能文件夹内创建工作目录：autoresearch-[skill-name]/
2. 创建包含标题行的 results.tsv
3. 创建 results.json 和 dashboard.html，然后在浏览器中打开仪表板
4. 将原始 SKILL.md 备份为 SKILL.md.baseline
5. 使用测试输入运行技能 [N] 次
6. 针对每项评测为每个输出评分
7. 记录基线分数，并更新 results.tsv 和 results.json

results.tsv 格式（制表符分隔）：

experiment	score	max_score	pass_rate	status	description
0	14	20	70.0%	baseline	original skill — no changes

重要： 建立基线后，继续操作前请向用户确认分数。如果基线已达到 90% 以上，技能可能不需要优化——请询问用户是否要继续。

---

步骤 5：运行实验循环

这是自动研究循环的核心。启动后，自主运行，直到停止。

循环：

1. 分析失败。 查看哪些评估项失败最多。阅读失败输出的实际内容。找出模式——是格式问题？缺少指令？还是指令含糊？

2. 形成假设。 选一项进行更改。不要一次更改 5 项，否则你无法判断哪些更改起了作用。

   有效的修改：

   • 添加一条具体指令，解决最常见的失败
   • 将含糊的指令改写得更明确
   • 针对反复出现的错误添加反面模式（“请勿执行 X”）
   • 将埋得较深的指令移到技能文档更靠前的位置（优先级 = 位置）
   • 添加或改进一个示例，展示正确行为
   • 删除导致技能过度优化某一方面、却牺牲其他方面的指令

   无效的修改：

   • 从头重写整个技能
   • 一次添加 10 条新规则
   • 没有具体理由地增加技能文档的篇幅
   • 添加“做得更好”或“更有创意”之类的含糊指令

3. 进行更改。 在 SKILL.md 中进行一项有针对性的修改。

4. 运行实验。 使用相同的测试输入运行该技能 [N] 次。

5. 评分。 用每项评估检查每个输出。计算总分。

6. 决定保留还是舍弃。

   • 分数提高 → 保留。 记录下来。这就是新的基线。
   • 分数不变 → 舍弃。 将 SKILL.md 还原为之前的版本。这项更改增加了复杂度，却没有带来改进。
   • 分数下降 → 舍弃。 将 SKILL.md 还原为之前的版本。

7. 在 results.tsv 中记录结果。

8. 重复。 回到循环的第 1 步。

绝不停止。 循环启动后，不要暂停下来询问用户是否要继续。他们可能不在电脑旁。持续自主运行，直到：

• 用户手动停止
• 达到预算上限（如果设置了上限）
• 连续 3 次实验的通过率达到 95% 以上（收益递减）

如果想不出新点子： 重新阅读失败输出。尝试组合两个之前差一点成功的修改。针对同一问题尝试完全不同的方法。试试删除内容，而不是添加内容。在维持分数的同时简化内容，也是一种成功。

---

步骤 6：编写变更日志

每次实验后（无论修改是保留还是舍弃），都将以下内容追加到 changelog.md：

## Experiment [N] — [keep/discard]

**Score:** [X]/[max] ([percent]%)
**Change:** [One sentence describing what was changed]
**Reasoning:** [Why this change was expected to help]
**Result:** [What actually happened — which evals improved/declined]
**Failing outputs:** [Brief description of what still fails, if anything]

这份变更日志是最有价值的产物。它是一份研究记录，任何未来的 Agent（或能力更强的未来模型）都可以据此继续工作。

---

步骤 7：交付结果

用户返回或循环停止时，提供：

1. 分数摘要： 基线分数 → 最终分数（提升百分比）
2. 实验总数： 尝试了多少项修改
3. 保留率： 保留与舍弃的修改数量
4. 最有效的 3 项更改（来自变更日志）
5. 剩余的失败模式（技能仍会出错的地方，如有）
6. 改进后的 SKILL.md（已保存到原位置）
7. results.tsv 和 changelog.md 的位置，供参考

---

输出格式

该技能会在 autoresearch-[skill-name]/ 中生成四个文件：

autoresearch-[skill-name]/
├── dashboard.html       # live browser dashboard (auto-refreshes)
├── results.json         # data file powering the dashboard
├── results.tsv          # score log for every experiment
├── changelog.md         # detailed mutation log
└── SKILL.md.baseline    # original skill before optimization

此外，改进后的 SKILL.md 也会保存回其原始位置。

results.tsv 示例：

experiment	score	max_score	pass_rate	status	description
0	14	20	70.0%	baseline	original skill — no changes
1	16	20	80.0%	keep	added explicit instruction to avoid numbering in diagrams
2	16	20	80.0%	discard	tried enforcing left-to-right layout — no improvement
3	18	20	90.0%	keep	added color palette hex codes instead of vague "pastel" description
4	18	20	90.0%	discard	added anti-pattern for neon colors — no improvement
5	19	20	95.0%	keep	added worked example showing correct label formatting

---

示例：优化图表生成器技能

收集的背景信息：

• 目标技能：~/.claude/skills/diagram-generator/SKILL.md
• 测试输入："OAuth flow diagram"、"CI/CD pipeline"、"microservices architecture"、"user onboarding funnel"、"database schema relationships"
• 评估项：(1) 所有文本是否清晰易读且拼写正确？(2) 是否只使用柔和的浅色？(3) 是否采用线性布局——从左到右或从上到下？(4) 是否不含数字、序数和排序？
• 每次实验运行数：10
• 最高分：40

基线运行（实验 0）： 生成了 10 张图表。根据 4 项评估逐一评分。结果：32/40（80%）。 常见问题：3 张图表包含编号步骤，2 张图表包含鲜红色元素，3 张图表中的文字太小，难以辨认。

实验 1 — 保留（35/40，87.5%）： 修改：在反模式部分添加“图表中绝不能包含步骤编号、序数（1st、2nd）或任何数字排序”。 结果：编号问题从 3 个降至 1 个。其他评估项保持不变。

实验 2 — 丢弃（34/40，85%）： 修改：添加“所有文本的字号必须至少为 14px。” 结果：可读性提高了 1 分，但颜色合规性下降了 2 分。已还原。

实验 3 — 保留（37/40，92.5%）： 修改：将含糊的“使用柔和的浅色”指令替换为具体的十六进制颜色代码：#A8D8EA, #AA96DA, #FCBAD3, #FFFFD2, #B5EAD7。 结果：颜色评估从 8/10 提高到 10/10。其他评估项保持不变。

实验 4 — 丢弃（37/40，92.5%）： 修改：添加反模式：“不要使用红色（#FF0000）、橙色（#FF8C00）或荧光绿（#39FF14）。” 结果：没有变化。实验 3 中的十六进制颜色代码已经解决了颜色问题。为保持技能简洁，已还原。

实验 5 — 保留（39/40，97.5%）： 修改：添加一个完整示例，展示格式正确的标签（无数字、使用柔和的浅色填充、从左到右的流程、文字清晰易读）的正确图表。 结果：达到 39/40。剩余的一个问题：一张复杂图表中的标签发生重叠。改进收益递减——停止实验。

最终交付：

• 基线：32/40（80%）→ 最终：39/40（97.5%）
• 5 次实验，保留 3 次，丢弃 2 次
• 主要修改：指定颜色的十六进制代码、明确禁止数字的规则、完整示例
• 剩余问题：非常复杂的图表偶尔会出现标签重叠（失败率为 1/40）

---

与其他技能的关联

哪些内容可以用于 autoresearch：

• 任何需要优化的现有技能
• 用户定义的评估标准（或借助评估指南帮助他们定义评估项）

autoresearch 可以提供哪些内容：

• 改进后的技能会替换原始技能
• 变更日志可以传递给后续模型，以继续优化
• 每次更新技能时，都可以复用评估套件

---

测试

一次成功的 autoresearch 运行应当：

1. 先进行基线测试——测量起始状态前，绝不做任何修改
2. 只使用二元评估项——不使用等级、不凭感觉，也不说“给这个评 1 到 10 分”
3. 一次只改一处——这样才能准确知道哪些改动有效
4. 保留完整日志——记录每次实验，以及保留或丢弃的结果
5. 提高分数——从基线到最终结果实现可衡量的改进
6. 避免过拟合——提升技能的实际工作表现，而不只是让它通过特定测试输入
7. 自主运行——实验之间无需停下来征求许可

如果技能“通过”了所有评估，但实际输出质量并未提高，那问题出在评估项，而不是技能。回到第 2 步，编写更好的评估项。