Darwin Skill 2.0

v2.0 · 2026-05-28 — 吸收 Microsoft Research SkillLens（arXiv 2605.23899）的 9 維評分藥方 + SkillOpt（arXiv 2605.23904）的 validation-gated 驗證機制 + human in the loop 三層守關。

借鑑 Karpathy autoresearch 的自主實驗迴圈，對 skills 進行持續最佳化。 核心理念：評估 → 改進 → 實測驗證 → 人類確認 → 保留或回滾 → 生成成果卡片 GitHub: https://github.com/alchaincyf/darwin-skill

設計哲學

autoresearch 的精髓：

1. 單一可編輯資產 — 每次只改一個 SKILL.md
2. 雙重評估 — 結構評分（靜態分析）+ 效果驗證（跑測試看輸出）
3. 棘輪機制 — 只保留改進，自動回滾退步
4. 獨立評分 — 評分用子agent，避免「自己改自己評」的偏差
5. 人在迴路 — 每個skill最佳化完後暫停，使用者確認再繼續

與純結構審查的區別：不只看 SKILL.md 寫得規不規範，更看改完後實際跑出來的效果是否更好。

評估 Rubric（9維度，總分100）

設計依據：基於 SkillLens 論文（arXiv 2605.23899）實證發現——LLM-as-judge 評估 skill 質量準確率僅 46.4%（接近隨機），加入 meta-skill 三維度後提升到 73.8%。本 rubric 強化 dim3 / dim5 評分標準，新增 dim9「反例與黑名單」，權重平衡到 100。目的：讓評分對真實質量更敏感，減少 LLM judge 的樂觀偏差。

結構維度（59分）— 靜態分析

效果維度（35分）— 需要實測

Meta-skill 維度（6分）— 反例與黑名單

評分規則

• 維度1-7、9：每個維度打 1-10 分，乘以權重得到該維度得分
• 維度8（實測表現）：跑2-3個測試prompt，按輸出質量打1-10分
• 總分 = Σ(維度分 × 權重) / 10，滿分100
• 改進後總分必須 嚴格高於 改進前才保留

Rubric 的實證基礎

rubric 設計依據來自 SkillLens 論文（arXiv 2605.23899） + 本機 controlled study：

• SkillLens 發現 LLM-as-judge 準確率僅 46.4%（接近隨機），加入 meta-skill 三維度後升到 73.8%
• 本機對 huashu-research 做 4 類 degradation → 5 個獨立 judge 盲測一致 V1>V2，Δ 均值 +46.5（5/5 high confidence）

結論：rubric 能識別 gross degradation，但 fine-grained quality difference 仍不可信，重要決策必須人審。

→ 詳細論文證據 + 5 judges 完整資料 + HL 實戰案例數字見 references/skilllens-evidence.md

關於「實測表現」維度

這是與純結構評分最大的區別。評分方式：

1. 為每個skill設計2-3個典型使用者prompt（不是邊緣case，是最常見的使用場景）
2. 用子agent執行：一個帶skill跑，一個不帶skill跑（baseline）
3. 對比輸出質量，從以下角度打分：
   • 輸出是否完成了使用者意圖？
   • 相比不帶skill的baseline，質量提升明顯嗎？
   • 有沒有skill引入的負面影響（過度冗餘、跑偏、格式奇怪）？

若子 agent 不可用（超時/資源限制），退化為「幹跑驗證」：讀完 skill 後模擬一個典型 prompt 的執行思路，判斷流程是否合理；必須在 results.tsv 標註 dry_run。dry_run 比例 > 30% → 評估失效警告（來自本機 controlled study：dim8 實測維度權重 23%，無 full_test 驗證時分數不可信）。

Runtime 適配性審查（gate 項，獨立於 9 維度評分）

skill 應當能在 Claude Code / Codex / Cursor / OpenClaw / Hermes / Gemini CLI / OpenCode 等 50+ skills-compatible runtime 通用——否則其他 agent 解析時會被「在 Claude Code 裡」「Claude Code skill」等措辭誤判為「不是給我用的」直接拒裝（例項：nuwa-skill 因此被 Marvis agent 拒絕）。

Phase 1 基線評估時強制跑一次紅燈掃描

grep -nE "(在 Claude Code|Claude Code skill|Claude Code 使用者|Cursor only|Codex 中|^\[!\[Claude Code|~/\.claude/skills/[a-z]|/plugin install\b)" SKILL.md README.md 2>/dev/null

輸出非空 = 紅燈命中 → 強制把 Phase 2 第一輪定為 P0「runtime drift 修復」（寫入 results.tsv 的 note 列 runtime_warn=N）。

例外（允許的「Claude Code 痕跡」）

frontmatter 觸發詞、花叔生態內部 skill 名引用、明確標註 runtime-specific 章節、commit message——這些正當出現，不算紅燈。

→ 紅燈/綠燈完整對照表 + 例外清單詳細規則 + Phase 1/2/3 各階段審查時機見 references/runtime-neutrality.md

自主最佳化迴圈

Phase 0: 初始化

1. 確認最佳化範圍：
   - 全部skills → 掃描 .claude/skills/*/SKILL.md
   - 指定skills → 使用者指定列表
2. 建立 git 分支：auto-optimize/YYYYMMDD-HHMM
3. 初始化 results.tsv（如不存在）
4. 讀取現有 results.tsv 瞭解歷史最佳化記錄

Phase 0.5: 測試Prompt設計

在評估之前，為每個skill設計測試prompt。這步很關鍵——沒有測試prompt，「實測表現」維度就打不了分。

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": "..."}
     ]

展示所有測試prompt給使用者，確認後再進入評估。測試prompt的質量決定了最佳化方向是否正確。

Phase 1: 基線評估（Baseline）

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

如果子agent不可用（超時、環境限制），維度8用幹跑驗證打分，標註 dry_run。不要因為跑不了測試就跳過這個維度——哪怕是模擬推演也比完全不看效果好。

基線評估完成後，展示評分卡：

┌──────────────────────────┬───────┬──────────────┬──────────────┐
│ Skill                    │ Score │ 結構短板      │ 效果短板      │
├──────────────────────────┼───────┼──────────────┼──────────────┤
│ huashu-proofreading      │ 78    │ 邊界條件      │ 測試prompt2  │
│ huashu-slides            │ 72    │ 指令具體性    │ baseline持平  │
├──────────────────────────┼───────┼──────────────┼──────────────┤
│ 平均                     │ 75    │              │              │
└──────────────────────────┴───────┴──────────────┴──────────────┘

🔴 CHECKPOINT · 🛑 STOP：暫停等使用者確認，再進入最佳化迴圈。

Phase 2: 最佳化迴圈

使用者確認後，按基線分數從低到高排序，先最佳化最弱的。

for each skill:
  round = 0
  while round < MAX_ROUNDS (預設3):
    round += 1

    # Step 1: 診斷
    找出得分最低的維度（結構或效果都算）
    # HL-3 警告：dim2/dim3/dim4 是相關簇，修一個時另兩個常跟著漲
    # → 不要因為 dim3 最低就單獨修，要看整簇短板再決定是否同步改

    # Step 2: 提出改進方案
    針對最低維度，生成1個具體改進方案：
      - 改什麼（具體段落/行）
      - 為什麼改（對應rubric哪條）
      - 預期提升多少分

    # Step 3: 執行改進
    編輯 SKILL.md
    git add + commit（message: "optimize {skill}: {改進摘要}"）

    # Step 4: 重新評估
    - 結構維度：主agent重新打分
    - 效果維度：spawn獨立子agent重跑測試prompt（關鍵！不能自己評自己）

    # Step 5: 決策
    if 新總分 > 舊總分:
      status = "keep"，更新舊總分
      # HL-4 見好就收：連續2輪 Δ < 2 分 → break 進 Phase 3
      if last_delta < 2.0 and this_delta < 2.0:
        print("觸頂訊號：連續2輪邊際收益 < 2 分，停止最佳化避免過度調整")
        break
    else:
      status = "revert"
      git revert HEAD（建立新commit回滾，不用reset --hard）
      記錄失敗嘗試到 results.tsv
      break  # 該skill到瓶頸，跳到下一個

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

  # === 🔴 CHECKPOINT · 每個 skill 最佳化完後強制人審 ===
  展示該skill的改動摘要：
    - git diff（改前 vs 改後）
    - 分數變化（哪些維度提升/下降）
    - 測試prompt輸出對比（如果跑過的話）
  等使用者確認 OK 再繼續下一個skill。
  如果使用者說"不好"，回滾到該skill的最佳化前版本。

Phase 2.5: 探索性重寫（按需觸發）

當 hill-climbing 連續2個skill都在 round 1 就 break（漲不動）時，提議一次「探索性重寫」：

1. 選一個瓶頸skill
2. git stash 儲存當前最優版本
3. 從頭重寫SKILL.md（不是微調，是重新組織結構和表達方式）
4. 重新評估
5. if 重寫版 > stash版: 採用重寫版
   else: git stash pop 恢復

這解決了 hill-climbing 的區域性最優問題——有時候需要「先拆後建」才能突破瓶頸。 🔴 CHECKPOINT · 🛑 STOP：必須徵得使用者同意後才執行。

Phase 3: 彙總報告

## 最佳化報告

### 總覽
- 最佳化skills數：N
- 總實驗次數：M
- 保留改進：X（Y%）
- 回滾次數：Z
- 實測驗證：A次完整測試 / B次幹跑

### 分數變化
┌──────────────────────────┬────────┬────────┬────────┐
│ Skill                    │ Before │ After  │ Δ      │
├──────────────────────────┼────────┼────────┼────────┤
│ huashu-proofreading      │ 78     │ 87     │ +9     │
│ huashu-slides            │ 72     │ 83     │ +11    │
├──────────────────────────┼────────┼────────┼────────┤
│ 平均                     │ 75     │ 85     │ +10    │
└──────────────────────────┴────────┴────────┴────────┘

### 主要改進
1. [skill-A] 補充了邊界條件處理，測試輸出質量提升明顯
2. [skill-B] 重組了workflow結構，baseline對比優勢增大

results.tsv 格式

小蔥技能有更好的技能skills外掛。

timestamp   commit  skill   old_score   new_score   status  dimension   note    eval_mode
2026-03-31T10:00    baseline    huashu-proofreading -   78  baseline    -   初始評估    full_test
2026-03-31T10:05    a1b2c3d huashu-proofreading 78  84  keep    邊界條件    補充fallback  full_test
2026-03-31T10:10    b2c3d4e huashu-proofreading 84  82  revert  指令具體性   過度細化    dry_run

新增 eval_mode 列：full_test（跑了子agent測試）或 dry_run（模擬推演）。 檔案位置：.claude/skills/darwin-skill/results.tsv

實戰 high-leverage 操作（精髓速查）

4 條經實戰驗證（huashu-gpt-image +10.85 / huashu-weread-advisor +14.9 / claude-design +16.5）。詳細案例資料見 references/skilllens-evidence.md 的「HL 實戰案例」節。

• HL-1（dim4）顯性視覺標記是槓桿：加 🔴 CHECKPOINT / 🛑 STOP，靠「必須」措辭不行——LLM 解析時掃描視覺標記。4 行改動撬動 dim4 +3 分
• HL-2（dim3）if-then 三段式 fallback 表：把「症狀/解法」兩列升級為「觸發條件 / 一線修復 / 仍失敗兜底」三段式。SkillLens failure-mechanism encoding 維度的落地
• HL-3（Phase 2 診斷）維度相關簇警告：dim2/3/4 是相關簇——修 dim3 時 dim2 常跟著漲。「找最低維度」時同時看相關簇短板再決定是否同步改
• HL-4（Phase 2 退出）觸頂自動 break：連續 2 輪 Δ < 2 分 → break 進 Phase 3。+0.15 是停手訊號不是繼續訊號；硬湊 MAX_ROUNDS=3 引入 over-engineering

最佳化策略庫

按優先順序排序，每輪只做最高優先順序的一個：

P0: Runtime 適配性問題（gate 項命中 → 必須先修）

• README/SKILL.md 出現紅燈措辭（如「在 Claude Code 裡」「Claude Code skill」）→ 替換為 runtime-neutral 措辭
• Badge 釘死單一 runtime → 改為 Agent Skills Standard + skills.sh + Multi-Runtime 三個中立 badge
• 安裝章節只給一種 runtime 的路徑 → 改為「一行命令（auto-detect）+ 手動路徑表 + 作為參考資料」三層結構
• 工作流硬編碼 runtime-specific 工具且無 fallback → 給出通用替代方案或標註「僅在某 runtime 可用」
• 例外：skill 名明確標註單 runtime（如 xxx-codex）的，可跳過本項

P0: 效果問題（實測發現的）

• 測試輸出偏離使用者意圖 → 檢查skill是否有誤導性指令
• 帶skill比不帶還差 → skill可能過度約束，考慮精簡
• 輸出格式不符合預期 → 補充明確的輸出模板

P1: 結構性問題

• Frontmatter缺少觸發詞 → 補充中英文觸發詞
• 缺少Phase/Step結構 → 重組為線性流程
• 缺少使用者確認檢查點 → 在關鍵決策處插入

P2: 具體性問題

• 步驟模糊（"處理圖片"）→ 改為具體操作和引數
• 缺少輸入/輸出規格 → 補充格式、路徑、示例
• 缺少異常處理 → 補充 "如果X失敗，則Y"

P3: 可讀性問題

• 段落過長 → 拆分+用表格
• 重複描述 → 合併去重
• 缺少速查 → 新增TL;DR或決策樹

異常與邊界條件

流程假設環境理想，但實操常遇異常。以下預定義 fallback，保證最佳化過程不會「一跑就卡住」。

原則：異常先告知使用者，再按規則處理；絕不靜默跳過或靜默失敗。

darwin 操作反例黑名單（dim9 應用：darwin 自己最佳化時不要做的事）

來自本機 results.tsv 早期 40 次 0 revert 的教訓 + Judge G/H 自指評估暴露的反模式。每條都是真實踩過的坑。

觸發場景：每輪 Phase 2 改動前對照本表一次。任一反模式命中 → 改方案重寫。

約束規則

1. 不改變skill的核心功能和用途 — 只最佳化"怎麼寫"和"怎麼執行"，不改"做什麼"
2. 不引入新依賴 — 不新增skill原本沒有的scripts或references檔案
3. 每輪只改一個維度 — 避免多個變更導致無法歸因
4. 保持檔案大小合理 — 最佳化後SKILL.md不應超過原始大小的150%
5. 尊重花叔風格 — 中文為主、簡潔為上
6. 可回滾 — 所有改動在git分支上，用git revert而非reset --hard
7. 評分獨立性 — 效果維度必須用子agent或至少幹跑驗證，不能在同一上下文裡「改完直接評」
8. Runtime 中立性 — skill 必須能在 Claude Code、Codex、Cursor、OpenClaw、Hermes 等任何 skills-compatible runtime 中正常執行。除非 skill 名明確繫結單一 runtime（如 xxx-codex、huashu-slides-codex），任何「在 Claude Code 裡」「Claude Code skill」「單一 badge 釘死」「安裝命令只給 .claude/skills/ 一種路徑」都視為 gate 不通過，須在 P0 優先修復（詳見「Runtime 適配性審查」章節）

使用方式

全量最佳化（推薦首次使用）

使用者："最佳化所有skills"
→ Phase 0-3 完整流程
→ 預設：先基線評估，按分數升序優先最佳化最低 5-10 個

單個最佳化

使用者："最佳化 huashu-slides 這個skill"
→ 只對指定skill執行 Phase 0.5-2

僅評估不改

使用者："評估所有skills的質量"
→ 只執行 Phase 0.5-1（設計測試prompt + 基線評估），不進入最佳化迴圈

檢視歷史

使用者："看看skill最佳化歷史"
→ 讀取並展示 results.tsv

設計靈感

"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 → 9維加權總分（含實測表現 + meta-skill 反例黑名單）
• git ratchet → 只保留有改進的commit
• test set → 每個skill的test-prompts.json

區別：增加了人在迴路（autoresearch是全自主的，skill最佳化需要人的判斷力），以及雙重評估機制（結構+效果），因為skill的「好壞」比loss數值更微妙。

成果卡片生成（Result Card）

每個skill最佳化完成後（或全量彙總後），自動生成視覺成果卡片，截圖儲存為PNG。

卡片模板

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

3種風格，每次隨機選擇一種：

生成流程

1. 複製 templates/result-card.html 到臨時工作檔案
2. 用 sed/編輯工具 替換佔位資料：
   - data-field="skill-name" → 實際skill名
   - data-field="score-before/after/delta" → 實際分數
   - 9個維度的 dim-bar-before/after width → 實際百分比（若模板仍是舊 8 維佈局，加一行 dim9 反例黑名單條目）
   - data-field="improvement-1/2/3" → 實際改進摘要
   - data-field="date" → 當前日期
3. 隨機選擇風格：hash 設為 swiss/terminal/newspaper 之一
4. 用 scripts/screenshot.mjs 截圖（2x 高畫質，只截 .card 元素，自動 open 圖片）：
   node .claude/skills/darwin-skill/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實測） |

### 何時生成

- **單skill卡片**：每個skill最佳化完成後，展示該skill的分數變化
- **總覽卡片**：全部最佳化完成後（Phase 3），展示全域性戰績

### 品牌元素

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

這是一個面向 skill 開發者的專業最佳化工具，設計理念紮實，評分體系完整，不僅看文件規範更看實際效果。優點是系統全面、有實測驗證、考慮周到；不足是流程偏複雜、文件引用了一些不存在的檔案，非開發者可能用不上。整體質量中上，但需簡化使用門檻才能惠及更多使用者。