# Evaluate Skill

> Evaluate whether a Claude Code skill improves task outcomes through repeated paired experiments, blind LLM judging, statistical tests, and a self-contained HTML report. Use when the user asks to benchmark, compare, validate, or quantify the effectiveness of a skill. This is a costly explicit-only workflow.

- Skill: `chenwei791129/evaluate-skill` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add chenwei791129/evaluate-skill`
- Raw SKILL.md: https://api.skillmd.com/api/skills/chenwei791129/evaluate-skill/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: chenwei791129 (https://skillmd.com/u/chenwei791129)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/chenwei791129/evaluate-skill

---


# Evaluate Skill

以相同案例重複執行「啟用 skill」與「未啟用 skill」兩組 Claude Code 配對實驗，再由獨立模型盲評，產生自包含 HTML report 與 machine-readable JSON sidecar。

## 模型用量與執行前確認

每個案例、每輪會呼叫 Claude Code 三次（with skill、without skill、judge）。總呼叫數為 `案例數 × rounds × 3`，可能產生顯著模型用量。執行前先向使用者確認 model、judge model 與 rounds，並告知總呼叫數；建議先用 1 case、1 round 驗證配置。

此 skill 設為 `disable-model-invocation: true`，只能由使用者明確呼叫，避免自動啟動昂貴實驗。

## 案例格式

案例檔為 JSON：

```json
{
  "name": "example-suite",
  "cases": [
    {
      "id": "case-1",
      "prompt": "Complete the requested task.",
      "rubric": "Score correctness, completeness, and adherence to the fixture requirements.",
      "fixture": "fixtures/case-1"
    }
  ]
}
```

`id`、`prompt`、`rubric` 必填且不得為空，`id` 不可重複。`fixture` 選填，路徑相對於案例 JSON；每組 arm/round 都會複製到獨立暫存 workspace，原始 fixture 不會被修改。可複製 `${CLAUDE_SKILL_DIR}/examples/cases.example.json` 作為起點。

### 會改變外部狀態的 CLI 案例

若受測 skill 會透過 CLI 執行 deploy、publish、send、upload、delete，或修改 repository、cloud、ticket、database 等外部狀態，一律使用 **describe-only** 案例，不得要求 agent 真正執行操作：

- `prompt` 必須要求 agent 只說明「會怎麼做」以及會建議哪些命令，並明示不得執行命令、不得使用 tools、不得修改檔案或外部狀態。
- `rubric` 必須將任何實際 tool use、workspace／external-state mutation，或聲稱已完成操作視為嚴重缺失。
- 使用 synthetic placeholders，不提供可直接操作真實資源的識別資訊或 credentials。

這項規則必須寫進每個相關 case；evaluator 不會根據關鍵字猜測案例風險。可參考 example suite 中的 `external-cli-procedure`。

## 執行

```bash
uv run ${CLAUDE_SKILL_DIR}/scripts/evaluate_skill.py \
  --skill /path/to/skill \
  --cases /path/to/cases.json \
  --claude-bin cx \
  --model claude-sonnet-5 \
  --effort high \
  --rounds 5 \
  --judge-model claude-fable-5 \
  --judge-effort high \
  --output skill-evaluation.html
```

`--claude-bin` 預設為環境變數 `CLAUDE_BIN`，未設定時使用 `claude`；CLI 旗標優先。launcher 必須支援 Claude Code 的 `--print`、JSON output、model、effort 與其他實驗旗標。腳本只會以 `--version` 與 `--help` 執行零費用的 launcher metadata／static flag validation；Claude Code 沒有官方保證不呼叫模型的 runtime argv probe，因此 wrapper forwarding 與實際 runtime compatibility 只能由最小 smoke run 或第一個實驗 invocation 驗證。命令以 argv 直接執行，不經 shell。

其他選項：

- `--seed INTEGER`：控制 arm 執行順序、judge A/B 對調與統計抽樣，預設 `0`。
- `--keep-workspaces`：保留暫存 workspace 供除錯；預設清除。
- `--effort`、`--judge-effort`：`low`、`medium`、`high`、`xhigh` 或 `max`。

第一版採序列執行以降低 rate limit 與資源干擾。進度輸出至 stderr；stdout 僅顯示完成摘要與 report 路徑。

## 實驗界線

- 兩個 arm 都取得相同的 project-local skill tree，以維持 workspace 因果對稱；with skill arm 以 `/<skill-name>` 明確啟用，without skill arm 加上 `--disable-slash-commands`。
- 禁用 user/project/local settings、外部 MCP 與 Chrome integration，judge 也禁用 tools。候選內容中的 skill 名稱與來源路徑會先遮蔽再送 judge，但風格等間接線索仍可能洩漏身份。
- 不使用 `--dangerously-skip-permissions`；採非互動 `dontAsk` 權限模式。需要額外權限的動作會失敗並記入報告。
- 對會改變外部狀態的 CLI skill，一律使用上述 describe-only case。`dontAsk` 不是 external-state sandbox，不能取代 prompt 與 rubric 中的禁止執行條款。
- fixture 與 skill tree 拒絕 symbolic links，避免複製或 snapshot 時意外越界。fixture 不得預先包含 `.claude/skills`；evaluator 必須完全控制兩個 arm 的相同 skill baseline。
- 暫存 workspace 只用來避免 fixture 回寫與 arm 互相污染，**不是 OS-level sandbox**。Claude Code 仍可能透過獲准工具存取 workspace 外的 filesystem 或 network。只評估可信任的 skill/fixture；若需要強隔離，請在另行管理的 container、VM 或 sandbox 中執行整個 evaluator。
- 每輪記錄 response、stdout、stderr、return code、duration、CLI JSON、usage/cost（launcher 有回傳時）與 workspace changes。
- 執行失敗不重試，也不交給 judge 當作低品質答案；會標記為 failed pair。
- 文字內容與 diff 有容量上限；binary 或超限檔案只記 metadata 與 SHA-256。

## 報告版面

HTML report 使用「工程筆記本」風格（藍圖方格底、深藍描邊卡片、手寫標題字），以正體中文呈現，由上而下的閱讀順序固定為：

1. **Hero**：skill 名稱、一句話結論、執行設定 chips。
2. **分數卡**：with / without 兩組平均分與長條。
3. **一句話結論**：結論標籤對應的判讀，加上說明該標籤意義的 callout。
4. **統計數字**：平均／中位差異、95% CI、p-value、Cohen's dz、勝平敗、win rate、失敗率。
5. **Per-case 結果**表格。
6. **Judge 怎麼說**：逐 trial 的 judge rationale、偏好與信心。
7. **這次怎麼測**：模型、effort、rounds、seed、launcher 版本、總時間與總成本、workspace 變更數。
8. **完整回答**：每個 trial 的 with／without 回答與原始 trial JSON，預設收起。
9. **方法與限制**：預設收起的 details。

版面完全由 `render_html()` 從 report dict 產生，沒有手寫敘述；欄位缺漏時顯示 `n/a` 而不會中斷。所有動態內容都經過 HTML escape。字型透過 Google Fonts `@import` 載入，離線時自動退回系統字型，其餘樣式與資料都內嵌在單一 HTML 檔。

## 解讀報告

報告包含平均與中位 paired difference、with/without 平均分、win/tie/loss、Cohen's dz、seeded 95% bootstrap confidence interval，以及雙尾 paired sign-flip randomization test。

只有 `p < 0.05`、95% confidence interval 不跨 0，且 failed-pair ratio 不超過 25% 時，才標示 `significant improvement` 或 `significant regression`；其餘標示 `insufficient evidence` 或 `insufficient data due to failures`，這不代表「沒有差異」。有效 pair 少於 2 或失敗過多時不要做強結論。

LLM judge 不是客觀 ground truth。結果只描述該 suite、rounds、tested model 與 judge 設定，不代表所有任務；per-case 結果應一併檢視，避免整體平均掩蓋特定案例退步。