Darwin Skill

Darwin Skill

Modified from upstream alchaincyf/darwin-skill(MIT-equivalent upstream README declaration; local LICENSE file added in Test-Agent's distribution). Test-Agent 项目内修订:删除上游 README 的个人推广段;SKILL.md 内示例数据(原作者自家 skill 命名前缀)替换为 Test-Agent 业务 skill 名;评分文案中的原作者生态绑定语改为通用项目语境。LICENSE 见同级 LICENSE 文件。

> 借鉴 Karpathy autoresearch 的自主实验循环，对 skills 进行持续优化。 > 核心理念：评估 → 改进 → 实测验证 → 人类确认 → 保留或回滚 → 生成成果卡片 > GitHub: https://github.com/alchaincyf/darwin-skill

---

设计哲学

autoresearch 的精髓：

1.单一可编辑资产— 每次只改一个 SKILL.md 2.双重评估— 结构评分（静态分析）+ 效果验证（跑测试看输出） 3.棘轮机制— 只保留改进，自动回滚退步 4.独立评分— 评分用子agent，避免「自己改自己评」的偏差 5.人在回路— 每个skill优化完后暂停，用户确认再继续

与纯结构审查的区别：不只看 SKILL.md 写得规不规范，更看改完后实际跑出来的效果是否更好。

---

评估 Rubric（8维度，总分100）

结构维度（60分）— 静态分析

| # | 维度 | 权重 | 评分标准 | | --- | ------ | ------ | --------- | | 1 |Frontmatter质量| 8 | name规范、description包含做什么+何时用+触发词、≤1024字符 | | 2 |工作流清晰度| 15 | 步骤明确可执行、有序号、每步有明确输入/输出 | | 3 |边界条件覆盖| 10 | 处理异常情况、有fallback路径、错误恢复 | | 4 |检查点设计| 7 | 关键决策前有用户确认、防止自主失控 | | 5 |指令具体性| 15 | 不模糊、有具体参数/格式/示例、可直接执行 | | 6 |资源整合度| 5 | references/scripts/assets引用正确、路径可达 |

效果维度（40分）— 需要实测

| # | 维度 | 权重 | 评分标准 | | --- | ------ | ------ | --------- | | 7 |整体架构| 15 | 结构层次清晰、不冗余不遗漏、与项目目录风格一致 | | 8 |实测表现| 25 | 用测试prompt跑一遍，输出质量是否符合skill宣称的能力 |

评分规则

• 维度1-7：每个维度打 1-10 分，乘以权重得到该维度得分
• 维度8（实测表现）：跑2-3个测试prompt，按输出质量打1-10分

-总分 = Σ(维度分 × 权重) / 10，满分100

• 改进后总分必须严格高于改进前才保留

关于「实测表现」维度

这是与纯结构评分最大的区别。评分方式：

1. 为每个skill设计2-3个典型用户prompt（不是边缘case，是最常见的使用场景）
2. 用子agent执行：一个带skill跑，一个不带skill跑（baseline）
3. 对比输出质量，从以下角度打分：

• 输出是否完成了用户意图？
• 相比不带skill的baseline，质量提升明显吗？
• 有没有skill引入的负面影响（过度冗余、跑偏、格式奇怪）？

如果无法跑子agent（时间/资源限制），可以退化为「干跑验证」：读完skill后模拟一个典型prompt的执行思路，判断流程是否合理。但要在results.tsv中标注 dry_run。

---

自主优化循环

Phase 0: 初始化

1. 确认优化范围：
   - 全部skills → 扫描 .claude/skills/*/SKILL.md
   - 指定skills → 用户指定列表

2. 创建 git 分支：auto-optimize/YYYYMMDD-HHMM
3. 初始化 results.tsv（如不存在）
4. 读取现有 results.tsv 了解历史优化记录

```text

### Phase 0.5: 测试Prompt设计

在评估之前，为每个skill设计测试prompt。这步很关键——没有测试prompt，「实测表现」维度就打不了分。

```text

for each skill:

  1. 读取 SKILL.md，理解它做什么
  2. 设计2-3个测试prompt，覆盖：
     - 最典型的使用场景（happy path）
     - 一个稍复杂或有歧义的场景
  3. 保存到 skill目录/test-prompts.json：
     [
       {"id": 1, "prompt": "用户会说的话", "expected": "期望输出的简短描述"},
       {"id": 2, "prompt": "...", "expected": "..."}
     ]

```text

展示所有测试prompt给用户，**确认后再进入评估**。测试prompt的质量决定了优化方向是否正确。

### Phase 1: 基线评估（Baseline）

```text

for each skill in 优化范围:

  # 结构评分（主agent可以做）

  1. 读取 SKILL.md 全文
  2. 按维度1-7逐项打分（附简短理由）

  # 效果评分（用子agent做，独立于主agent）

  3. 对每个测试prompt，spawn子agent：
     - with_skill: 带着SKILL.md执行测试prompt
     - baseline: 不带skill执行同一prompt
  4. 对比两组输出，打维度8的分

  # 汇总

  5. 计算加权总分
  6. 记录到 results.tsv

```text

**如果子agent不可用**（超时、环境限制），维度8用干跑验证打分，标注 `dry_run`。不要因为跑不了测试就跳过这个维度——哪怕是模拟推演也比完全不看效果好。

基线评估完成后，展示评分卡：

```text

┌──────────────────────────┬───────┬──────────────┬──────────────┐
│ Skill                    │ Score │ 结构短板      │ 效果短板      │
├──────────────────────────┼───────┼──────────────┼──────────────┤
│ python-script-gen      │ 78    │ 边界条件      │ 测试prompt2  │
│ smoke-test            │ 72    │ 指令具体性    │ baseline持平  │
├──────────────────────────┼───────┼──────────────┼──────────────┤
│ 平均                     │ 75    │              │              │
└──────────────────────────┴───────┴──────────────┴──────────────┘

```text

**暂停等用户确认，再进入优化循环。**

### Phase 2: 优化循环

用户确认后，按基线分数从低到高排序，先优化最弱的。

```text

for each skill:
  round = 0
  while round  旧总分:
      status = "keep"，更新旧总分
    else:
      status = "revert"
      git revert HEAD（创建新commit回滚，不用reset --hard）
      记录失败尝试到 results.tsv
      break  # 该skill到瓶颈，跳到下一个

    # Step 6: 日志
    results.tsv 追加行

  # === 每个skill优化完后的人类检查点 ===
  展示该skill的改动摘要：

    - git diff（改前 vs 改后）
    - 分数变化（哪些维度提升/下降）
    - 测试prompt输出对比（如果跑过的话）
  等用户确认 OK 再继续下一个skill。
  如果用户说"不好"，回滚到该skill的优化前版本。

```text

### Phase 2.5: 探索性重写（可选）

当 hill-climbing 连续2个skill都在 round 1 就 break（涨不动）时，提议一次「探索性重写」：

```text

1. 选一个瓶颈skill
2. git stash 保存当前最优版本
3. 从头重写SKILL.md（不是微调，是重新组织结构和表达方式）
4. 重新评估
5. if 重写版 > stash版: 采用重写版
   else: git stash pop 恢复

```text

这解决了 hill-climbing 的局部最优问题——有时候需要「先拆后建」才能突破瓶颈。
**必须征得用户同意后才执行。**

### Phase 3: 汇总报告

```text

## 优化报告

### 总览

- 优化skills数：N
- 总实验次数：M
- 保留改进：X（Y%）
- 回滚次数：Z
- 实测验证：A次完整测试 / B次干跑

### 分数变化

┌──────────────────────────┬────────┬────────┬────────┐
│ Skill                    │ Before │ After  │ Δ      │
├──────────────────────────┼────────┼────────┼────────┤
│ python-script-gen      │ 78     │ 87     │ +9     │
│ smoke-test            │ 72     │ 83     │ +11    │
├──────────────────────────┼────────┼────────┼────────┤
│ 平均                     │ 75     │ 85     │ +10    │
└──────────────────────────┴────────┴────────┴────────┘

### 主要改进

1. [skill-A] 补充了边界条件处理，测试输出质量提升明显
2. [skill-B] 重组了workflow结构，baseline对比优势增大

```text

---

## results.tsv 格式

```tsv

timestamp    commit    skill    old_score    new_score    status    dimension    note    eval_mode
2026-03-31T10:00    baseline    python-script-gen    -    78    baseline    -    初始评估    full_test
2026-03-31T10:05    a1b2c3d    python-script-gen    78    84    keep    边界条件    补充fallback    full_test
2026-03-31T10:10    b2c3d4e    python-script-gen    84    82    revert    指令具体性    过度细化    dry_run

```text

新增 `eval_mode` 列：`full_test`（跑了子agent测试）或 `dry_run`（模拟推演）。
文件位置：`.claude/skills/darwin-skill/results.tsv`

---

## 优化策略库

按优先级排序，每轮只做最高优先级的一个：

### P0: 效果问题（实测发现的）

- 测试输出偏离用户意图 → 检查skill是否有误导性指令
- 带skill比不带还差 → skill可能过度约束，考虑精简
- 输出格式不符合预期 → 补充明确的输出模板

### P1: 结构性问题

- Frontmatter缺少触发词 → 补充中英文触发词
- 缺少Phase/Step结构 → 重组为线性流程
- 缺少用户确认检查点 → 在关键决策处插入

### P2: 具体性问题

- 步骤模糊（"处理图片"）→ 改为具体操作和参数
- 缺少输入/输出规格 → 补充格式、路径、示例
- 缺少异常处理 → 补充 "如果X失败，则Y"

### P3: 可读性问题

- 段落过长 → 拆分+用表格
- 重复描述 → 合并去重
- 缺少速查 → 添加TL;DR或决策树

---

## 异常与边界条件

流程假设环境理想，但实操常遇异常。以下预定义 fallback，保证优化过程不会「一跑就卡住」。

| 场景 | 触发条件 | 处理动作 |
| --- | --- | --- |
| 不在 git 仓库 | `git rev-parse` 失败 | 提示用户「建议 git init」；若拒绝，用 `cp SKILL.md SKILL.md.bak.YYYYMMDD-HHMM` 文件备份代替 revert |
| results.tsv 缺失 | 文件不存在 | 新建并写表头行（9列：含 eval_mode） |
| results.tsv 损坏 | 列数不匹配 / 非TSV | 备份为 `.bak.YYYYMMDD-HHMM` 后重建，告知用户 |
| 分支已存在 | `git checkout -b` 失败 | 分支名末尾加 `-2` / `-3`；第3次失败则切回现有分支并询问继续还是新起 |
| `git revert` 失败 | 冲突 / 工作树脏 | 先 `git stash`，重试；仍失败则从上一个 commit 的 SKILL.md 读出覆盖当前文件手动恢复 |
| MAX_ROUNDS 触顶（默认3） | 已跑3轮仍有短板 | 不强制 break，展示当前最弱维度问用户「继续加1轮 / 进入Phase 2.5 / 收工」 |
| 优化后超 150% 体积 | 新文件 > 原 × 1.5 | 拒绝提交，回到改进步骤精简（删冗余/合并重复），再评 |
| test-prompts.json 已存在 | 文件已在 skill 目录 | 默认复用并展示，问用户「复用 / 重写 / 追加」三选一 |
| SKILL.md 找不到 | 目录存在但无 SKILL.md | 该 skill 终止，results.tsv 记 `status=error`，继续下一个 |
| 分数计算规则 | 浮点精度漂移 | 总分保留 1 位小数，改进需严格 > 旧分（不靠四舍五入） |

**原则**：异常先告知用户，再按规则处理；绝不静默跳过或静默失败。

---

## 约束规则

1.**不改变skill的核心功能和用途**— 只优化"怎么写"和"怎么执行"，不改"做什么"
2.**不引入新依赖**— 不添加skill原本没有的scripts或references文件
3.**每轮只改一个维度**— 避免多个变更导致无法归因
4.**保持文件大小合理**— 优化后SKILL.md不应超过原始大小的150%
5.**尊重项目风格**— 中文为主、简洁为上
6.**可回滚**— 所有改动在git分支上，用git revert而非reset --hard
7.**评分独立性**— 效果维度必须用子agent或至少干跑验证，不能在同一上下文里「改完直接评」

---

## 使用方式

### 全量优化（推荐首次使用）

```text

用户："优化所有skills"
→ Phase 0-3 完整流程
→ 建议：先基线评估，选择分数最低的5-10个重点优化

```text

### 单个优化

```text

用户："优化 smoke-test 这个skill"
→ 只对指定skill执行 Phase 0.5-2

```text

### 仅评估不改

```text

用户："评估所有skills的质量"
→ 只执行 Phase 0.5-1（设计测试prompt + 基线评估），不进入优化循环

```text

### 查看历史

```text

用户："看看skill优化历史"
→ 读取并展示 results.tsv

```text

---

## 设计灵感

> "You write the goals and constraints in program.md; let an agent generate and test code deltas indefinitely; keep only what measurably improves the objective."
> — Karpathy, autoresearch

本skill的对应关系：

-**program.md**→ 本文件（评估rubric和约束规则）
-**train.py**→ 每个SKILL.md
-**val_bpb**→ 8维加权总分（含实测表现）
-**git ratchet**→ 只保留有改进的commit
-**test set**→ 每个skill的test-prompts.json

区别：增加了人在回路（autoresearch是全自主的，skill优化需要人的判断力），以及双重评估机制（结构+效果），因为skill的「好坏」比loss数值更微妙。

---

## 成果卡片生成（Result Card）

每个skill优化完成后（或全量汇总后），自动生成视觉成果卡片，截图保存为PNG。

### 卡片模板

模板位置：`templates/result-card.html`

3种风格，每次随机选择一种：

| 风格 | CSS类 | URL hash | 视觉特点 |
| ------ | -------- | ---------- | --------- |
| Warm Swiss | `.theme-swiss` | `#swiss` | 暖白底+赤陶橙，Inter字体，干净网格 |
| Dark Terminal | `.theme-terminal` | `#terminal` | 近黑底+荧光绿，等宽字体，扫描线 |
| Newspaper | `.theme-newspaper` | `#newspaper` | 暖白纸+深红，衬线字体，双栏编辑风 |

### 生成流程

```text

1. 复制 templates/result-card.html 到临时工作文件
2. 用 sed/编辑工具 替换占位数据：
   - data-field="skill-name" → 实际skill名
   - data-field="score-before/after/delta" → 实际分数
   - 8个维度的 dim-bar-before/after width → 实际百分比
   - data-field="improvement-1/2/3" → 实际改进摘要
   - data-field="date" → 当前日期

3. 随机选择风格：hash 设为 swiss/terminal/newspaper 之一
4. 用 scripts/screenshot.mjs 截图（2x 高清，只截 .card 元素，自动 open 图片）：
   node scripts/screenshot.mjs /abs/path/to/card.html /abs/path/to/output.png
   # 回退方案（脚本失败时）：
   npx playwright screenshot "file:///path/to/card.html#[theme]" \
     output.png --viewport-size=960,1280 --wait-for-timeout=2000

5. 提示用户查看成果卡片 PNG

### 资源文件速查

| 路径 | 用途 |
| --- | --- |
| `templates/result-card.html` | 3风格主模板（swiss/terminal/newspaper，hash切换） |
| `templates/result-card-dark.html` / `-white.html` | 单一风格替代模板（需要锁定风格时用） |
| `scripts/screenshot.mjs` | 2x 高清截图，只截 .card，自动 open |
| `results.tsv` | 历次优化日志（9列含 eval_mode） |
| `{skill目录}/test-prompts.json` | 每个 skill 的测试 prompt 集（用于维度8实测） |

```text

### 何时生成

-**单skill卡片**：每个skill优化完成后，展示该skill的分数变化
-**总览卡片**：全部优化完成后（Phase 3），展示全局战绩

### 品牌元素

- 顶部：Darwin.skill 品牌标识 + 日期
- 底部：「Train your Skills like you train your models」+ github.com/alchaincyf/darwin-skill

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Wool-xing](https://github.com/Wool-xing)
- **Source:** [Wool-xing/Test-Agent](https://github.com/Wool-xing/Test-Agent)
- **License:** MIT
- **Homepage:** https://github.com/Wool-xing/Test-Agent

Install and usage instructions live in the source repository linked above.