darwin-skill

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 的自主實驗循環，對 skill 進行持續優化。
核心理念：評估 → 改進 → 實測驗證 → 人類確認 → 保留或回滾 → 生成成果卡片
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 分）— 靜態分析

#	維度	權重	評分標準
1	Frontmatter品質	7	name規範、description包含做什麼+何時用+觸發詞、≤1024字元、禁結尾加「靈活應用/根據情況判斷」等空話尾巴
2	工作流程清晰度	12	步驟明確可執行、有編號、每步有明確輸入/輸出
3	失敗模式編碼	12	必須顯式編碼失敗模式（寫出「如果 X 失敗 → Y」的明確分支）；有 fallback 路徑、錯誤復原；只寫正向流程而不寫失敗分支扣 ≥3 分（SkillLens meta-skill 維度）
4	檢查點設計	6	關鍵決策前有使用者確認、防止自主失控；檢查點必須顯性標記（🔴/STOP/CHECKPOINT），僅靠「如果...建議...」措辭不算
5	可執行具體性	17	不模糊、有具體參數/格式/範例、可直接執行；禁止「建議/可以考慮/根據情況/靈活把握/視情況而定」等軟化措辭——出現 ≥3 處扣 ≥3 分（SkillLens actionable specificity 維度）
6	資源整合度	4	references/scripts/assets 引用正確、路徑可達

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

#	維度	權重	評分標準
7	整體架構	12	結構層次清晰、不冗餘不遺漏、與花叔生態一致；冗餘/AI腔廢話段落（說白了/換句話說/首先其次綜上等花叔禁用詞）出現一處扣 1 分
8	實測表現	23	用測試 prompt 跑一遍，輸出品質是否符合 skill 宣稱的能力

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

#	維度	權重	評分標準
9	反例與黑名單	6	skill 必須有「不要做什麼」的反例清單；只寫「應該做 X」沒有「不要做 Y」扣 ≥3 分；紅燈/危險動作/反模式應單獨章節列出（SkillLens risk-action blacklist 維度）

評分規則

• 維度 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>/devnull

輸出非空 = 紅燈命中 → 強制把 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 格式

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，保證優化過程不會「一跑就卡住」。

情境	觸發條件	處理動作
不在 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 位小數，改進需嚴格 > 舊分（不靠四捨五入）

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

---

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

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

#	反模式	為什麼不要做	替代做法
1	同 context 自評自改	改完後立刻在同一 Claude session 打分，會有「我剛改的肯定更好」樂觀偏差（SkillLens 實證 LLM-as-judge 準確率僅 46.4%）	必須 spawn 獨立子 agent 評分，且至少 2 個 judge 共識才信
2	git reset --hard 當回滾	會丟工作樹未提交改動；CI 歷史斷裂	用 git revert HEAD 建立反向 commit，保留可追溯鏈
3	為湊分增冗餘	觸頂後繼續硬改往往是「加廢話/加段落讓 LLM 覺得更詳細」，實際品質變	觸頂訊號（連續 2 輪 Δ<2 分）→ break 進 Phase 3，見好就收
4	跳過 test-prompts 直接評分	沒有 test-prompts 的 dim8 是憑空打分，權重 23% 等於編造	Phase 0.5 強制設計 2-3 prompts；若使用者不給，預設編 3 個並展示確認
5	輪內改多個維度	多變數同時變，分數升降無法歸因到具體改動	每輪 1 個維度；相關群集（dim2/3/4）改其一時觀察另兩個是否跟漲
6	dry_run 比例 > 30%	dim8 實測維度形同虛設，分數虛高（早期 40 次紀錄 67% dry_run，0 revert）	強制至少 1 個真實 full_test；dry_run 多的優化在 results.tsv 顯式打 ⚠️
7

<!-- truncated for translation batch; full body continues in source -->