Skill Creator — 五大設計模式分析¶

參考來源：Agent Skill 設計模式 (2026)

模式對應總覽¶

mindmap
  root((skill-creator))
    工具包裝 Tool Wrapper
      scripts/ 封裝 claude -p
      run_eval.py 觸發測試
      package_skill.py 封裝工具
      generate_review.py 瀏覽器工具
    生成器 Generator
      SKILL.md 模板生成
      evals.json 測試案例生成
      benchmark.json 統計報告生成
      HTML 報告生成
    審查者 Reviewer
      grader.md assertions 評分
      comparator.md A/B 盲測
      analyzer.md benchmark 模式分析
      quick_validate.py 格式驗證
    反轉 Inversion
      Capture Intent 需求澄清
      Interview & Research 訪談
      測試案例確認
      每輪迭代後的使用者審查
    管道 Pipeline
      起草→測試→評估→改進→優化→封裝
      明確的 checkpoint 暫停點
      iteration-N 版本管理

模式一：工具包裝（Tool Wrapper）¶

核心思想¶

將外部工具/CLI 包裝成可在 skill 中直接呼叫的內聚模組，讓 Claude 無需每次重新推斷如何使用這些工具。

skill-creator 的實作¶

skill-creator 的 scripts/ 目錄是一個完整的 工具包裝層，將多個底層能力封裝為清楚的 Python 模組：

graph LR
    Claude[Claude\n主工作流程] -->|呼叫| scripts["scripts/ 工具包裝層"]
    scripts --> A["run_eval.py\n包裝 claude -p\n+ stream 偵測"]
    scripts --> B["package_skill.py\n包裝 zipfile\n+ 驗證"]
    scripts --> C["improve_description.py\n包裝 claude -p\n+ prompt 工程"]
    scripts --> D["generate_report.py\n包裝 HTML 生成"]
    A --> CLI["claude -p\n(subprocess)"]
    B --> FS[".skill 檔案"]
    C --> CLI

關鍵設計特點¶

run_eval.py 對 claude -p 的包裝特別精細：

• 動態建立臨時 command file（.claude/commands/<name>-skill-<uuid>.md）
• 使用 --include-partial-messages + stream-json 進行 早期觸發偵測（不等完整回應）
• 刪除 CLAUDECODE 環境變數解決巢狀執行衝突
• 執行完畢自動清理臨時檔案

sequenceDiagram
    participant S as run_eval.py
    participant F as .claude/commands/
    participant C as claude -p

    S->>F: 寫入 <name>-skill-<uuid>.md
    S->>C: Popen(stream-json, include-partial-messages)
    C-->>S: content_block_start {tool_use: "Skill"}
    Note over S: 立即偵測到技能名稱 → return True
    S->>F: unlink() 清理臨時檔

模式二：生成器（Generator）¶

核心思想¶

從結構化模板產生一致的輸出，確保格式統一、避免遺漏關鍵欄位。

skill-creator 的實作¶

skill-creator 貫穿整個生命週期都在 生成結構化文件：

flowchart LR
    subgraph 生成對象
        A[SKILL.md\nYAML frontmatter\n+ Markdown 指令]
        B[evals.json\n測試案例\n+ assertions]
        C[eval_metadata.json\n單一 eval 描述]
        D[grading.json\n評分結果]
        E[benchmark.json\n統計彙整]
        F[HTML 報告\n優化過程視覺化]
    end
    SKILL.md --> A
    SKILL.md --> B
    run_loop --> E
    run_loop --> F
    grader --> D
    aggregate --> E

SKILL.md 模板生成（SKILL.md 第 64–68 行）定義了必填組件：

name: Skill identifier
description: When to trigger + what it does
compatibility: Required tools (optional)
...正文內容...

eval_review.html（assets/eval_review.html）是描述優化步驟的互動式生成器模板：

• 使用者在瀏覽器中編輯查詢、切換 should_trigger
• 點擊 "Export Eval Set" 生成 eval_set.json

generate_report.py 是最複雜的生成器——根據 run_loop.py 的 JSON 輸出動態生成 HTML 報告表格，每個迭代一行，每個查詢一列，以顏色標示 Train/Test 分區和通過狀態。

生成器的防錯設計¶

improve_description.py 的生成器含有安全保護：若生成的描述超過 1024 字元（SKILL.md 硬性限制），自動呼叫第二次 claude -p 縮短：

flowchart TD
    A[claude -p 生成新描述] --> B{len > 1024?}
    B -- 否 --> C[直接使用]
    B -- 是 --> D[再次呼叫 claude -p\n附上超長版本要求縮短]
    D --> E[使用縮短版]

模式三：審查者（Reviewer）¶

核心思想¶

根據明確的評分標準對輸出進行系統性審查，輸出有證據支撐的通過/失敗判斷。

skill-creator 的四層審查體系¶

graph TD
    subgraph 審查層次
        V["quick_validate.py\nLayer 0: 格式審查\n（packaging 前強制執行）"]
        G["grader.md\nLayer 1: 量化審查\nassertions pass/fail + 證據"]
        C["comparator.md\nLayer 2: 相對審查\nA/B 盲測 rubric 評分"]
        A["analyzer.md\nLayer 3: 模式審查\nbenchmark 異常 & 原因分析"]
    end
    V --> G --> C --> A

quick_validate.py — 格式審查，packaging 前強制執行：

• 驗證 YAML frontmatter 存在
• 檢查 name（kebab-case, ≤64 字元）、description（無角括號, ≤1024 字元）
• 只允許白名單屬性：{name, description, license, allowed-tools, metadata, compatibility}

grader.md — 8 步驟審查流程：

1. 讀取 transcript
2. 檢查 output 檔案
3. 逐一評估 assertions（PASS 需有實質證據，非表面合規）
4. 提取並驗證隱含 claims（factual / process / quality）
5. 讀取 user_notes.md
6. 批評 eval 本身的品質（弱斷言識別）
7. 讀取 metrics.json 和 timing.json
8. 寫出 grading.json

comparator.md — 盲測評分 rubric：

graph LR
    subgraph CR[Content Rubric]
        C1[Correctness 1-5]
        C2[Completeness 1-5]
        C3[Accuracy 1-5]
    end
    subgraph SR[Structure Rubric]
        S1[Organization 1-5]
        S2[Formatting 1-5]
        S3[Usability 1-5]
    end
    CR --> CS[Content Score\n平均]
    SR --> SS[Structure Score\n平均]
    CS --> OS[Overall Score\n1-10]
    SS --> OS
    OS --> W{Winner}

審查者的防偏設計：comparator.md 嚴格「不知道」是哪個 skill 產生哪個輸出，防止對特定版本的偏見，只根據輸出品質判斷。

模式四：反轉（Inversion）¶

核心思想¶

在行動前先提問，確保方案符合使用者真實需求；讓使用者持續參與決策而非被動接受結果。

skill-creator 中的反轉設計¶

反轉模式貫穿 skill-creator 的每一個關鍵決策點：

sequenceDiagram
    participant U as 使用者
    participant C as Claude + skill-creator

    C->>U: [Capture Intent] 這個技能要做什麼？什麼時候觸發？
    U-->>C: 說明意圖
    C->>U: [Interview] 邊界條件？輸入格式？成功標準？
    U-->>C: 補充細節
    C->>C: 撰寫 SKILL.md 草稿
    C->>U: [Test Case Review] 這幾個測試案例合適嗎？
    U-->>C: 確認 / 修改
    C->>C: 執行測試 + 同時草擬 assertions
    C->>U: [Assertion Review] 這些評估指標合理嗎？
    U-->>C: 確認
    C->>U: [Eval Viewer] 請查看輸出結果，提供意見
    U-->>C: feedback.json
    C->>C: 分析反饋，改進技能
    Note over C,U: 重複直到滿意
    C->>U: [Description Eval Review] 這 20 個觸發查詢合適嗎？
    U-->>C: 確認 / 編輯
    C->>C: run_loop.py 優化描述
    C->>U: 展示 before/after + 分數
    U-->>C: 最終確認

反轉的深層設計原則¶

SKILL.md 第 299–302 行（"How to think about improvements"）明確說明了反轉哲學：

"Rather than put in fiddly overfitty changes...try branching out and using different metaphors"

使用者的每次意見都是輸入，Claude 的改進是假設，需要再次提交使用者驗證。eval viewer 的設計就是為了讓這個反轉迴圈盡可能低摩擦。

模式五：管道（Pipeline）¶

核心思想¶

嚴格的多步驟工作流，每個階段有明確前置條件和暫停點（checkpoint）。

skill-creator 的雙層管道架構¶

skill-creator 同時實現了兩個管道：技能開發管道 與 描述優化管道。

技能開發管道¶

flowchart TD
    subgraph Phase1["Phase 1: 定義（必須）"]
        P1A[Capture Intent] --> P1B[Interview & Research]
        P1B --> P1C[撰寫 SKILL.md 草稿]
    end
    subgraph Phase2["Phase 2: 測試（必須）"]
        P2A[設計 2-3 個測試提示\n存入 evals/evals.json] --> P2B
        P2B[Spawn: with_skill +\nbaseline 同時執行] --> P2C
        P2C[同時草擬 assertions\n說明給使用者] --> P2D
        P2D[Grader 評分\n→ grading.json]
    end
    subgraph Phase3["Phase 3: 彙整（必須）"]
        P3A[aggregate_benchmark.py\n→ benchmark.json] --> P3B
        P3B[Analyst pass\n找出隱藏模式] --> P3C
        P3C[generate_review.py\n啟動 eval viewer]
    end
    subgraph Phase4["Phase 4: 審查（checkpoint ⏸️）"]
        P4[使用者審查輸出\n填寫 feedback.json]
    end
    subgraph Phase5["Phase 5: 改進（迴圈）"]
        P5A[讀取 feedback.json] --> P5B
        P5B[改進 SKILL.md] --> P5C
        P5C[iteration-N+1/\n重新執行 Phase 2-4]
    end
    subgraph Phase6["Phase 6: 優化描述（可選）"]
        P6A[生成 20 個觸發查詢] --> P6B
        P6B[使用者審查 eval set ⏸️] --> P6C
        P6C[run_loop.py\n優化迴圈]
    end
    subgraph Phase7["Phase 7: 交付"]
        P7[package_skill.py\n→ .skill 檔]
    end

    Phase1 --> Phase2 --> Phase3 --> Phase4
    Phase4 -->|使用者不滿意| Phase5
    Phase5 --> Phase2
    Phase4 -->|使用者滿意| Phase6
    Phase6 --> Phase7

描述優化管道（run_loop.py）¶

flowchart TD
    A[載入 eval_set.json] --> B[60/40 分層抽樣\ntrain / test split]
    B --> C{"Iteration N\n(最多 max_iterations)"}
    C --> D[run_eval 平行執行\ntrain + test 所有查詢]
    D --> E[記錄結果到 history\n更新 live HTML 報告]
    E --> F{train 全部通過?}
    F -- 是 --> G[exit: all_passed]
    F -- 否 --> H{N == max_iterations?}
    H -- 是 --> G
    H -- 否 --> I[improve_description.py\n傳入 blinded_history\n呼叫 claude -p]
    I --> J[更新 current_description]
    J --> C
    G --> K[選取 test_score 最高的\nbest_description]
    K --> L[generate_report.py 最終報告]

管道的 Checkpoint 設計¶

模式組合分析¶

skill-creator 並非單一模式的實現，而是 五種模式的有機組合：

graph TD
    subgraph 組合一: 管道 + 反轉
        PL[Pipeline\n嚴格步驟順序] <-->|每個 checkpoint 都是\n反轉互動點| IN[Inversion\n先問後做]
    end
    subgraph 組合二: 審查者 + 管道
        RE[Reviewer\ngrader + comparator] <-->|每個 iteration\n都有審查階段| PL2[Pipeline\niteration loop]
    end
    subgraph 組合三: 生成器 + 工具包裝
        GE[Generator\nSKILL.md + reports] <-->|生成後透過\n包裝工具執行| TW[Tool Wrapper\nscripts/ 工具層]
    end

    組合一 --> 組合二 --> 組合三

各模式在 skill-creator 的強度評估¶

設計啟示¶

skill-creator 可視為「如何建立高品質 skill」的示範實現。從模式分析可提煉以下原則：

1. 管道保障可重複性：將創意流程（起草、評估、改進）標準化為可追蹤的版本化步驟。
2. 反轉確保對齊：在每個代價高的步驟前，先用低代價的互動確認方向，避免大量無效工作。
3. 審查者提升可信度：量化的 assertions + 有證據的評分，讓「技能有沒有變好」有客觀依據。
4. 生成器固化知識：把 best practice 編碼進模板（SKILL.md 格式、grading.json schema），讓每次都能對齊標準。
5. 工具包裝降低摩擦：重複的底層操作（呼叫 claude、打包、解析 YAML）封裝後，主工作流程只需呼叫，不需重新發明。