autoresearch

面向 Skills 的自主研究

大多数 skill 约有 70% 的时间能正常工作，另外 30% 的时候，输出一塌糊涂。解决办法不是从头重写 skill，而是让 Agent 运行几十次，为每次输出评分，并不断改进提示词，直到那 30% 的问题消失。

此 skill 将 Andrej Karpathy 的自主研究方法（自主实验循环）应用于 Claude Code skills。我们优化的不是 ML 训练代码，而是 skill 提示词。

---

核心任务

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

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

**输出：**改进后的 SKILL.md、results.tsv 日志、记录所有尝试过的修改的 changelog.md，以及一个可在浏览器中查看的实时 HTML 仪表板。

---

开始之前：收集上下文

停止。在用户确认以下所有字段之前，不要运行任何实验。询问用户提供缺失的信息。

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

---

步骤 1：阅读 skill

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

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

不要跳过此步骤。你需要先了解 skill 的作用，才能改进它。

---

步骤 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”之类的等级。等级会叠加变数，导致结果不可靠。
• 要足够具体，确保判断一致。“文本是否易读？”太含糊。“所有单词是否拼写正确，且没有被截断的句子？”就可以测试。
• 也不要过于狭窄，以免 skill 钻评估标准的空子。“少于 200 个词”会让 skill 以牺牲其他所有方面为代价来追求简短。
• 3-6 项评估最为合适。超过这个数量，skill 就会开始复述评估标准，而不是真正改进。

详细的良好与不良评估项示例，请参阅 references/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 步，编写更好的评估项。