eval

eval skill 概覽

eval 在 AgentHub 工作階段中的用途

eval 是一個 AgentHub skill，用來替已完成的 agent 結果排名。它是為 /hub:eval 指令設計的：當多個 agents 已經針對同一個任務完成工作後，你可以用它來評分、比較，或選出最佳結果。eval skill 支援在已設定 eval command 時進行指標式評估；沒有可用指標時，則可使用 LLM judge 評估；當客觀分數與程式碼判斷都很重要時，也能採用混合式決策方式。

最適合的使用者與任務

eval skill 最適合使用 AgentHub 風格多 agent 工作流程的開發者：同一個任務、由多個 agent branches 或 worktrees 處理，最後再進行比較。當你需要可重複地回答像是「哪個 agent 做出了最快的實作？」、「哪個 patch 最安全、最適合 merge？」或「哪個結果最符合原始任務？」這類問題時，它會很有幫助。它不太適合作為獨立的 benchmarking framework，因為它假設你已經有 AgentHub session 結構、agent result posts、branches 與 diffs。

eval 與一般 prompt 的差異

一般 prompt 也可以請 LLM 比較輸出，但 eval 提供的是一條具體的評估路徑：有可用 metric command 時，針對每個 agent 執行指標評估；使用 judge mode 時，則檢查每個 agent 的 diff 與 result post。關鍵差異在於，這個 skill 會引導 assistant 以已完成的 AgentHub artifacts 為依據，而不是憑空給出自由式意見。這能減少猜測，也讓排名更容易稽核與追溯。

採用 eval 前的主要考量

在安裝或依賴 eval 之前，請先確認你的工作流程會把 agent results 存在 AgentHub 預期的位置，而且 agent branches 或 worktrees 仍然可用。Metric mode 也需要可正常執行的 evaluation command、metric name，以及方向設定，例如 latency 是 lower-is-better，或 score 是 higher-is-better。這個 skill 的 repository path 只包含 SKILL.md，因此大多數行為是由 command instructions 定義，而不是 skill 目錄內額外的 helper files。

如何使用 eval skill

eval 安裝與 repository 檢查

使用你平常的 skill installer，從 GitHub skill repository 安裝，例如：

npx skills add alirezarezvani/claude-skills --skill eval

安裝後，請先閱讀 engineering/agenthub/skills/eval/SKILL.md。這個 skill 目錄內沒有本機的 rules/、resources/、references/ 或 scripts/ 資料夾，因此 SKILL.md 就是主要依據。請注意，skill 文字中提到 metric mode 會使用 scripts/result_ranker.py；在依賴 metric-based ranking 之前，請確認你更完整的 AgentHub setup 是否提供該 script，或是否有等效的 evaluation runner。

基本 eval 使用指令

在 agents 完成一個 session 後使用指令：

/hub:eval
/hub:eval 20260317-143022
/hub:eval --judge

/hub:eval 會評估最新的 session。傳入 session ID 則會指定某一次執行。--judge 會強制使用 LLM judge mode，適合在 metric command 缺失、不可靠，或過於狹窄而無法反映正確性時使用。

讓 eval 運作更好的輸入

若使用 metric mode，請提供或設定：session ID、eval command、metric label，以及 direction。一個好的請求會很明確：

「Run /hub:eval 20260317-143022 using the configured benchmark. Rank by latency_ms, lower is better, and call out any agent whose result fails tests.」

若使用 LLM judge mode，請確保 assistant 能存取 base branch、agent branches、git diffs，以及像 .agenthub/board/results/agent-1-result.md 這類 result posts。更好的 prompt 會包含任務目標與優先順序：

「Use /hub:eval --judge for the latest session. Prioritize correctness first, then minimal risk, then simplicity. Treat changed public APIs as risky unless justified in the result post.」

產生可靠排名的實務流程

請等所有 agents 都已發布 results，且其 branches 已乾淨到足以進行 diff 後，再執行 eval。當任務有客觀分數時，例如 runtime、test count、accuracy、size 或 benchmark output，優先從 metric mode 開始。對於設計、重構、bug fixes，或容易被單一指標取巧的任務，則使用 LLM judge mode。若是重要的 merge，請要求 eval 不只回報 winner，也要列出主要風險、diff 中的證據，以及任何用來分出勝負的假設。

eval skill 常見問題

eval 是用於 Model Evaluation，還是 agent result ranking？

這個 eval skill 主要是用於 AgentHub agent result ranking，而不是通用型 Model Evaluation suite。它可以評估由模型產生的工作成果，但比較單位是 agent 已完成的 session result：包括它的 branch、diff、result note，以及可選擇在其 worktree 中執行的 metric command。

什麼時候該用 metric mode，而不是 judge mode？

當成功與否可以穩定衡量時，請使用 metric mode：例如 tests passed、benchmark score、latency、memory、accuracy、bundle size，或其他數值輸出。當真正的問題是 patch 是否正確、可維護且安全時，請使用 judge mode。如果 metric 只涵蓋任務目標的一部分，請要求混合式判讀：先依 metric 排名，再從 diffs 標出 correctness 或 regression 風險。

初學者可以使用 eval skill 嗎？

如果初學者已經理解 AgentHub session 的概念，就可以使用 eval。它的 command surface 很小，但評估品質取決於 repository state：branches、worktrees、result posts，以及已設定的 eval commands。如果這些 artifacts 缺失，初學者可能會看到令人困惑或不完整的排名。

什麼情況下 eval 不是合適工具？

在 agents 尚未完成、只有一個結果，或 assistant 無法存取 diffs 與 result files 時，不應使用 eval。它也不適合廣泛的 model benchmarking、prompt leaderboard 建立，或 offline dataset evaluation，除非你調整周邊工作流程。這些情境更適合使用專門的 evaluation harness。

如何改善 eval skill

用更清楚的準則改善 eval 結果

最能提升品質的是明確的排名政策。告訴 eval 什麼最重要：correctness、passing tests、performance、simplicity、security、compatibility，或 minimal code churn。避免像「pick the best」這類模糊請求。請改用：「Rank agents by correctness first; if tied, prefer fewer changed files and no new dependencies; mention any untested assumptions.」

避免常見的 eval 失敗模式

常見失敗包括被誤導性的 metric 牽著走、忽略失敗的 edge case、比較到過期的 branches，或高估較小但沒有真正解決任務的 diff。要避免這些問題，請在評估前確認 base branch、session ID、metric direction 與 task objective。若使用 judge mode，請要求以證據支持排名，並將判斷連結到特定 diffs 與 result posts。

在第一次排名後持續迭代

請把第一次 eval 輸出視為決策草稿。如果 winner 令人意外，可以要求第二輪只聚焦在有爭議的準則：「Re-evaluate only the top two agents for regression risk」，或「Explain whether agent-2’s faster metric comes from skipping required behavior.」這能讓 eval workflow 保持實用，而不需要重新跑完整個 agent session。

讓 skill 更貼合你的工作流程

如果你維護自己的 AgentHub setup，可以透過標準化 result post format、統一 metric 命名，以及讓 eval command 具備 deterministic 行為來改善 eval。加入專案專屬指引，明確定義什麼算是 correctness、哪些 tests 必須通過，以及哪些 risks 會阻擋 merge。這個 skill 本身很精簡，因此日常使用中 eval 是否值得信賴，很大程度取決於你在 sessions、branches 與 metrics 上建立的本地慣例。