PluginEval 品質方法論 — 包含評估維度、評分標準、統計方法與計分公式。當你需要了解外掛品質如何衡量、解讀某個維度的低分、決定如何改善技能的觸發準確度或編排適配性、為你的市集校準評分門檻，或向 Neon 等外部合作夥伴解釋品質徽章時，請使用此技能。
評估方法論
本文件是 PluginEval 衡量外掛與技能品質的權威參考。
內容涵蓋三個評估層級、全部十個評分維度、複合公式、徽章
門檻、反模式標記、Elo 排名，以及可行的改善建議。
相關文件：完整評分標準錨點
三個評估層級
PluginEval 堆疊三個互補的層級。每個層級針對每個適用的維度產生 0.0 到 1.0 之間的分數，
後續層級會根據各維度的混合權重覆蓋或混合先前的分數。
層級 1 — 靜態分析
速度： < 2 秒。無需 LLM 呼叫。確定性。
靜態分析器 (layers/static.py) 直接對解析後的 SKILL.md 執行六項子檢查：
| 子檢查 | 衡量內容 |
|---|---|
frontmatter_quality |
名稱存在性、描述長度、觸發詞語品質 |
orchestration_wiring |
輸出/輸入文件、程式碼區塊數量、編排器反模式 |
progressive_disclosure |
行數 vs. 甜蜜點 (200–600 行)、references/ 與 assets/ 加分 |
structural_completeness |
標題密度、程式碼區塊、範例區段、疑難排解區段 |
token_efficiency |
MUST/NEVER/ALWAYS 密度、重複行比例 |
ecosystem_coherence |
對其他技能/代理的交叉引用、「相關」/「另見」提及 |
這六項子檢查直接對應到六個最終維度（透過 STATIC_TO_DIMENSION 對應）。
其餘四個維度 — output_quality、scope_calibration、
robustness 以及部分 triggering_accuracy — 沒有靜態貢獻，完全依賴層級 2 和/或層級 3。
反模式懲罰 以乘法方式應用於層級 1 分數：
penalty = max(0.5, 1.0 − 0.05 × anti_pattern_count)
每多偵測到一個反模式，分數降低 5%，最低降至 50%。
層級 2 — LLM 評審
速度： 30–90 秒。一次或多次 LLM 呼叫（預設為 Sonnet）。非確定性。
eval-judge 代理讀取 SKILL.md 及任何 references/ 檔案，然後使用錨定評分標準（參見 references/rubrics.md）對四個維度進行評分：
- 觸發準確度 — 從 10 個心智測試提示推導出的 F1 分數
- 編排適配性 — 工作者純淨度評估（0–1 評分標準）
- 輸出品質 — 模擬 3 個實際任務；評估指令品質
- 範圍校準 — 根據技能類別判斷深度與廣度
評審回傳結構化的 JSON 物件（無 Markdown 圍欄），評估引擎將其合併到複合分數中。當 judges > 1 時，分數取平均值，並報告 Cohen's kappa 作為評審間一致性指標。
層級 3 — 蒙地卡羅模擬
速度： 5–20 分鐘。N=50 次模擬的 Agent SDK 呼叫（預設）。統計性。
蒙地卡羅執行 N 個真實提示通過技能，並記錄：
- 觸發率 — 觸發技能的提示比例
- 輸出一致性 — 品質分數的變異係數 (CV)
- 失敗率 — 錯誤/崩潰比例，附 Clopper-Pearson 精確信賴區間
- Token 效率 — 中位數 token 數、IQR、離群值數量
層級 3 複合公式：
mc_score = 0.40 × activation_rate
+ 0.30 × (1 − min(1.0, CV))
+ 0.20 × (1 − failure_rate)
+ 0.10 × efficiency_norm
其中 efficiency_norm = max(0, 1 − median_tokens / 8000)。
複合計分公式
最終分數是每個維度跨三個層級的加權混合，然後加總：
composite = Σ(dimension_weight × blended_dimension_score) × 100 × anti_pattern_penalty
維度權重
| 維度 | 權重 | 為何重要 |
|---|---|---|
triggering_accuracy |
0.25 | 從不觸發或錯誤觸發的技能毫無價值 |
orchestration_fitness |
0.20 | 技能必須是純粹的工作者；監督邏輯應屬於代理 |
output_quality |
0.15 | 正確、完整的輸出是主要交付物 |
scope_calibration |
0.12 | 既非存根也非臃腫的怪物 |
progressive_disclosure |
0.10 | SKILL.md 精簡；細節存在於 references/ |
token_efficiency |
0.06 | 每次呼叫的上下文浪費最小化 |
robustness |
0.05 | 處理邊界情況而不崩潰 |
structural_completeness |
0.03 | 正確的區段以正確順序排列 |
code_template_quality |
0.02 | 可運作、可複製貼上的範例 |
ecosystem_coherence |
0.02 | 交叉引用；不與同類重複 |
層級混合權重
每個維度以不同比例從不同層級取得資料。當三個層級都啟用時（--depth deep 或 certify）：
| 維度 | 靜態 | 評審 | 蒙地卡羅 |
|---|---|---|---|
triggering_accuracy |
0.15 | 0.25 | 0.60 |
orchestration_fitness |
0.10 | 0.70 | 0.20 |
output_quality |
0.00 | 0.40 | 0.60 |
scope_calibration |
0.30 | 0.55 | 0.15 |
progressive_disclosure |
0.80 | 0.20 | 0.00 |
token_efficiency |
0.40 | 0.10 | 0.50 |
robustness |
0.00 | 0.20 | 0.80 |
structural_completeness |
0.90 | 0.10 | 0.00 |
code_template_quality |
0.30 | 0.70 | 0.00 |
ecosystem_coherence |
0.85 | 0.15 | 0.00 |
在 --depth standard（僅靜態 + 評審）時，混合權重會重新正規化以移除蒙地卡羅欄。在 --depth quick（僅靜態）時，所有權重落在層級 1。
混合分數計算
對於給定的深度，維度 d 的混合分數為：
blended[d] = Σ( layer_weight[d][layer] × layer_score[d][layer] )
─────────────────────────────────────────────────────
Σ( layer_weight[d][layer] for available layers )
此正規化確保在標準深度跳過蒙地卡羅時不會人為地降低分數。
解讀維度分數
每個維度分數是 [0.0, 1.0] 範圍內的浮點數。CLI 將其轉換為字母等級：
| 等級 | 分數範圍 | 意義 |
|---|---|---|
| A | 0.90 – 1.00 | 優秀 — 無需有意義的改進 |
| B | 0.80 – 0.89 | 良好 — 僅有微小差距 |
| C | 0.70 – 0.79 | 合格 — 有一兩個明確的改進領域 |
| D | 0.60 – 0.69 | 邊緣 — 需要針對性工作 |
| F | < 0.60 | 不及格 — 需要大幅修正 |
閱讀報告時，首先關注權重最高且等級最低的維度。triggering_accuracy（權重 0.25）的 D 等遠比 ecosystem_coherence（權重 0.02）的 D 等代價更高。
信賴區間 在層級 2 或層級 3 執行時會出現在報告中。窄信賴區間（± < 5 分）表示分數穩定。寬信賴區間則暗示不一致 — 通常由模糊的描述或對某些提示風格有效但對其他無效的指令所導致。
品質徽章
徽章需要同時滿足複合分數門檻和 Elo 門檻（當 Elo 可用時）。Badge.from_scores() 邏輯先檢查複合分數，然後檢查 Elo（如有提供）：
| 徽章 | 複合分數 | Elo | 意義 |
|---|---|---|---|
| 鉑金 ★★★★★ | ≥ 90 | ≥ 1600 | 參考級品質 — 適合黃金語料庫 |
| 金級 ★★★★ | ≥ 80 | ≥ 1500 | 生產就緒 |
| 銀級 ★★★ | ≥ 70 | ≥ 1400 | 功能正常，有改進空間 |
| 銅級 ★★ | ≥ 60 | ≥ 1300 | 最低可行 — 尚不建議使用者使用 |
| — | < 60 | 任意 | 未達最低標準 |
當 Elo 尚未計算時（即在 quick 或 standard 深度未使用 certify），會跳過 Elo 門檻。在這些情況下，技能可以僅憑複合分數獲得徽章。
反模式標記
靜態分析器偵測五種反模式。每種都有嚴重性乘數，影響懲罰公式。
OVER_CONSTRAINED
觸發條件： SKILL.md 中 MUST、ALWAYS 或 NEVER 出現超過 15 次。
問題： 過度規範的指令會降低模型靈活性、增加 token 開銷，並表示作者試圖微觀管理每個輸出，而非提供原則性指導。
修正： 審查每個 MUST/ALWAYS/NEVER。盡可能用解釋性框架取代指令性語言。將硬性限制保留給真正的安全或正確性需求。目標是每 100 行少於 10 個此類指令。
EMPTY_DESCRIPTION
觸發條件： frontmatter 的 description 欄位在去除空白後少於 20 個字元。
問題： 沒有有意義的描述，Claude Code 外掛系統無法判斷何時呼叫該技能。技能將對自主呼叫不可見。
修正： 撰寫至少 60–120 個字元的描述，包含：
- 「Use this skill when...」或「Use when...」觸發子句
- 兩個以上以逗號或「or」分隔的具體情境
MISSING_TRIGGER
觸發條件： 描述中不包含「use when」、「use this skill when」、「use proactively」或「trigger when」（不區分大小寫）。
問題： 即使描述很長，如果沒有明確的觸發訊號，對自主呼叫來說也是無用的。系統的路由模型需要明確的提示。
修正： 在描述前加上「Use this skill when...」，接著是具體情境。範例：「Use this skill when measuring plugin quality, interpreting score reports, or explaining badge thresholds to a team.」
BLOATED_SKILL
觸發條件： SKILL.md 超過 800 行且技能沒有 references/ 目錄。
問題： 龐大的 SKILL.md 迫使每次呼叫都將整個文件載入上下文，浪費 token 在僅邊緣情況才需要的內容上。
修正： 建立 references/ 目錄並將支援材料移至該處：
- 詳細評分標準 →
references/rubrics.md - 擴充範例 →
references/examples.md - 設定參考 →
references/config.md
SKILL.md 應使用 [text](references/filename.md) 連結到這些檔案，以便模型按需取得。
ORPHAN_REFERENCE
觸發條件： SKILL.md 包含 Markdown 連結 [text](references/filename)，其中 filename 在 references/ 目錄中不存在。
問題： 死連結浪費 token 在永遠無法解析的上下文上，並混淆模型。
修正： 建立缺少的參考檔案或移除死連結。
DEAD_CROSS_REF
觸發條件： SKILL.md 以相對路徑引用另一個技能或代理，且該路徑無法從 skills/ 目錄解析。
問題： 中斷的生態系統連結會削弱外掛的一致性分數，並可能導致模型嘗試導航到不存在的檔案。
修正： 驗證引用的技能存在。更新路徑或移除引用。
Elo 排名
PluginEval 使用 Elo/Bradley-Terry 評分系統將技能與黃金語料庫進行排名。
起始評分： 1500（依慣例為語料庫中位數）。
K 因子： 32（中等風險評分的標準值）。
期望分數公式（標準 Elo）：
E(A vs B) = 1 / (1 + 10^((B_rating − A_rating) / 400))
每次對戰後的評分更新：
new_rating = old_rating + 32 × (actual_score − expected_score)
其中 actual_score 為勝 1.0、平 0.5、負 0.0。
信賴區間 透過 500 次 bootstrap 計算，報告為 95% CI。
語料庫百分位 反映對黃金語料庫的勝率。
位置偏差檢查： 對戰以兩種順序評估；不一致處會被標記。
plugin-eval init 指令從外掛目錄建立語料庫索引：
plugin-eval init ./plugins --corpus-dir ~/.plugineval/corpus
CLI 參考
評分技能（快速靜態分析）
plugin-eval score ./path/to/skill --depth quick
在 < 2 秒內回傳層級 1 結果。適用於撰寫期間的快速回饋。
使用 LLM 評審評分（預設）
plugin-eval score ./path/to/skill
執行靜態 + LLM 評審（標準深度）。耗時 30–90 秒。
以 JSON 格式輸出完整結果
plugin-eval score ./path/to/skill --output json
輸出結構化 JSON，包含 composite.score、composite.dimensions 和 layers[0].anti_patterns。適合 CI 整合：
plugin-eval score ./path/to/skill --depth quick --output json --threshold 70
# 若分數 < 70 則以 exit code 1 結束
完整認證（所有三個層級 + Elo）
plugin-eval certify ./path/to/skill
執行靜態 + LLM 評審 + 蒙地卡羅（50 次模擬）+ Elo 排名。耗時 15–20 分鐘。
指派品質徽章。在將技能發佈到市集前使用。
頭對頭比較
plugin-eval compare ./skill-a ./skill-b
以 quick 深度評估兩個技能，並輸出逐維度比較表。
適用於在兩個實作之間做決定，或衡量改寫前後的進步。
初始化 Elo 語料庫
plugin-eval init ./plugins
在 ~/.plugineval/corpus 建立本地語料庫索引。Elo 排名運作前需要執行此步驟。
腳本化複合公式
離線重現複合分數（pre-commit hook、CI 閘道）：
def composite_score(dimension_scores: dict, anti_pattern_count: int = 0) -> float:
"""Replicate the PluginEval composite formula."""
WEIGHTS = {
"triggering_accuracy": 0.25,
"orchestration_fitness": 0.20,
"output_quality": 0.15,
"scope_calibration": 0.12,
"progressive_disclosure": 0.10,
"token_efficiency": 0.06,
"robustness": 0.05,
"structural_completeness":0.03,
"code_template_quality": 0.02,
"ecosystem_coherence": 0.02,
}
raw = sum(WEIGHTS[d] * s for d, s in dimension_scores.items())
penalty = max(0.5, 1.0 - 0.05 * anti_pattern_count)
return round(raw * 100 * penalty, 2)
# 範例：一個觸發分數較弱的技能
scores = {
"triggering_accuracy": 0.65, # D — 需要改善描述
"orchestration_fitness": 0.85,
"output_quality": 0.80,
# … 填入其餘 7 個維度 …
}
# composite_score(scores, anti_pattern_count=1) → ~76.5
JSON 輸出格式
--output json 的頂層結構：
{
"composite": { "score": 76.5, "badge": "Silver", "elo": null },
"dimensions": {
"triggering_accuracy": { "score": 0.65, "grade": "D", "ci_low": 0.60, "ci_high": 0.70 },
"orchestration_fitness": { "score": 0.85, "grade": "B", "ci_low": 0.80, "ci_high": 0.90 }
},
"layers": [
{ "name": "static", "duration_ms": 1243, "anti_patterns": ["OVER_CONSTRAINED"] },
{ "name": "judge", "duration_ms": 48200, "judges": 1, "kappa": null }
]
}
在 CI 中解析 composite.score 以閘控部署：
score=$(plugin-eval score ./my-skill --output json | python3 -c "import sys,json; print(json.load(sys.stdin)['composite']['score'])")
if (( $(echo "$score < 70" | bc -l) )); then
echo "Quality gate failed: score $score < 70"
exit 1
fi
改善技能分數的建議
按權重順序處理維度。最大的進步來自於先修正權重最高的維度。
應優先改善哪個維度
當分數報告顯示多個 D/F 等級且你需要優先排序工作時，使用此表格。
| 維度 | 權重 | 典型修正工作量 | 每小時分數影響 | 若以下情況則優先修正 |
|---|---|---|---|---|
triggering_accuracy |
0.25 | 低 — 改寫描述 | 高 | 總分 < 70 |
orchestration_fitness |
0.20 | 中 — 重組區段 | 高 | 技能混合工作者 + 監督邏輯 |
output_quality |
0.15 | 中 — 加入範例 | 中 | 評審分數 < 0.70 |
scope_calibration |
0.12 | 低 — 將內容移至 references/ | 中 | 檔案 < 100 或 > 800 行 |
progressive_disclosure |
0.10 | 低 — 建立 references/ 目錄 | 中 | 無 references/ 目錄 |
token_efficiency |
0.06 | 低 — 減少 MUST/ALWAYS/NEVER | 低 | 反模式數量 ≥ 3 |
robustness |
0.05 | 低 — 加入疑難排解區段 | 低 | 未記錄邊界情況處理 |
structural_completeness |
0.03 | 極低 — 加入標題/程式碼區塊 | 低 | 少於 4 個 H2 標題 |
code_template_quality |
0.02 | 極低 — 加入語言標籤 | 極低 | 程式碼區塊缺少語言標籤 |
ecosystem_coherence |
0.02 | 極低 — 加入相關區段 | 極低 | 完全沒有交叉引用 |
經驗法則： 優先修正 triggering_accuracy — 權重 0.25 帶來的複合分數增益每小時超過所有低權重維度的總和。
觸發準確度（權重 0.25）
- 包含「Use this skill when...」後接 3–4 個以逗號分隔的具體情境。
- 如果技能應在沒有明確使用者請求時自動啟動，加入「proactively」。
- 心智測試：撰寫 5 個應觸發的提示和 5 個不應觸發的提示 — 你的描述能區分嗎？如果不能，加入或收緊情境詞語。
編排適配性（權重 0.20）
- 記錄技能接收什麼和回傳什麼 — 而非它編排什麼。
- 避免在 SKILL.md 中使用「orchestrate」、「coordinate」、「dispatch」、「manage workflow」。
- 包含「Output format」區段和 2 個以上展示具體工作者行為的程式碼區塊。
輸出品質（權重 0.15）
- 提供具體、可操作的指令 — 而不只是目標。
- 明確涵蓋至少一個邊界情況（空輸入、格式錯誤的資料等）。
- 包含一個範例區段，展示代表性的輸入和預期輸出。
- 指令越具體，評審對這個維度的評分就越高。
範圍校準（權重 0.12）
- 目標 200–600 行。低於 100 是存根；超過 800 且無
references/則是臃腫。 - 將背景閱讀、擴充範例和參考表格移至
references/。 - 非常狹窄的技能應與同類合併；非常廣泛的技能應拆分。
漸進式揭露（權重 0.10）
- 加入
references/目錄（獲得 0.15–0.25 加分）並保持 SKILL.md 專注於執行路徑。assets/目錄可進一步加分。
Token 效率（權重 0.06）
- 審查 MUST/ALWAYS/NEVER 數量。目標每 10 行少於 1 個。
- 合併幾乎重複的項目符號和重複結構的表格。
穩健性（權重 0.05）
- 加入「Troubleshooting」或「Edge Cases」區段，涵蓋至少 3 種失敗模式。
- 說明技能在無法完成任務時回傳什麼。
結構完整性（權重 0.03）
- 確保至少 4 個 H2/H3 標題、3 個程式碼區塊、一個 Examples 區段和一個 Troubleshooting 區段。
程式碼範本品質（權重 0.02）
- 所有程式碼區塊必須語法正確且可複製貼上，並附有語言標籤。
生態系統一致性（權重 0.02）
- 加入「## Related」區段，列出同類技能或代理及其相對路徑。
- 避免重複其他技能中已有的內容 — 改為連結到它。
疑難排解
「加入內容後分數遠低於預期」
反模式懲罰會疊加。使用 --output json 執行並檢查 layers[0].anti_patterns。如果你有 5 個以上反模式，無論內容多好，乘數都可能將分數降至原始值的 75%。先修正標記。
「儘管描述詳細，triggering_accuracy 仍然很低」
_description_pushiness 評分器尋找特定的語法模式，而不只是長度。確認你的描述包含「Use this skill when」或「Use when」（確切措辭很重要 — 這是正規表示式比對）。同時檢查你是否有多個以逗號或「or」分隔的使用案例，以獲得具體性加分。
「LLM 評審分數在不同執行之間差異很大」
這對於模糊的技能是預期的。評審非確定性地產生 10 個心智測試提示。透過收緊描述和加入具體範例來改善分數穩定性。當 judges > 1 時，平均分數會更穩定。使用 --depth deep 搭配 certify，它會執行蒙地卡羅以獲得統計上有界的分數。
「progressive_disclosure 分數很低，儘管檔案長度正確」
檢查檔案是否在 200–600 行的甜蜜點。少於 100 行的檔案在此子檢查中僅得 0.20 分。同時確認 references/ 檔案不為空 — 評分器檢查的是非空的參考檔案，而不只是目錄存在。
「compare 顯示我的改寫分數低於原始版本」
Quick 深度（--depth quick）僅執行靜態分析。如果改寫將內容移至 references/ 並大幅縮短 SKILL.md，結構完整性的靜態分數可能會下降，即使整體品質提升。執行 --depth standard 以獲得包含 LLM 評審對內容品質評估的更公平比較。
參考資料
相關代理
- eval-judge (
../../agents/eval-judge.md) — 對層級 2 維度（triggering_accuracy、orchestration_fitness、output_quality、scope_calibration）進行評分的 LLM 評審。當你需要僅重新執行評審層級或檢查其推理過程時，直接呼叫。 - eval-orchestrator (
../../agents/eval-orchestrator.md) — 頂層編排器，負責排序所有三個層級、合併結果、指派徽章並撰寫最終報告。當執行完整認證或頭對頭比較兩個技能時呼叫。
