Skill Creator — 結構與用法分析¶

概述¶

skill-creator 是一個 meta-skill（用來建立技能的技能），協助使用者從零開始設計、測試、評估與優化 Claude Code 的 skills。它覆蓋完整的 skill 生命週期：起草 → 測試 → 評估 → 改進 → 優化描述 → 封裝發佈。

目錄結構¶

skill-creator/
├── SKILL.md                      # 主要技能定義（指令 + 前端 YAML）
├── LICENSE.txt
├── agents/                       # 子代理人指令
│   ├── grader.md                 # 評分代理：斷言通過/失敗分析
│   ├── comparator.md             # 盲測比較代理：A/B 輸出對比
│   └── analyzer.md               # 分析代理：benchmark 結果解讀 & 後驗分析
├── references/
│   └── schemas.md                # 所有 JSON 資料結構定義
├── assets/
│   └── eval_review.html          # 描述優化評估集審查 HTML 模板
├── eval-viewer/
│   └── generate_review.py        # 生成 eval 結果瀏覽器（HTTP server 或靜態 HTML）
└── scripts/                      # 自動化 Python 腳本
    ├── __init__.py
    ├── utils.py                  # 共用工具（SKILL.md 解析）
    ├── quick_validate.py         # Skill 格式驗證
    ├── package_skill.py          # 封裝 .skill 壓縮檔
    ├── run_eval.py               # 觸發率評估（平行執行 claude -p）
    ├── improve_description.py    # 透過 Claude 改進 description 文字
    ├── run_loop.py               # 評估 + 改進的完整迴圈
    ├── aggregate_benchmark.py    # 彙整 grading.json → benchmark.json / .md
    └── generate_report.py        # 生成優化報告 HTML

核心工作流程¶

flowchart TD
    A([使用者提出需求]) --> B{已有草稿?}
    B -- 否 --> C[Capture Intent\n理解使用者意圖]
    C --> D[Interview & Research\n訪談邊界條件與格式]
    D --> E[撰寫 SKILL.md 草稿]
    B -- 是 --> F[設計測試案例\n2-3 個真實提示]
    E --> F

    F --> G[Spawn 子代理平行執行\nwith_skill + baseline]
    G --> H[同時草擬 assertions\n量化評估指標]
    H --> I[評分 grading.json\nGrader 代理]
    I --> J[aggregate_benchmark.py\n生成 benchmark.json]
    J --> K[generate_review.py\n啟動瀏覽器 / 靜態 HTML]
    K --> L([使用者審查輸出\n+ 填寫意見])
    L --> M{使用者滿意?}
    M -- 否 --> N[分析反饋\n改進 SKILL.md]
    N --> O[iteration-N+1/\n重新執行所有測試]
    O --> K
    M -- 是 --> P[Description 優化\nrun_loop.py]
    P --> Q[package_skill.py\n生成 .skill 檔]
    Q --> R([交付給使用者])

Progressive Disclosure（漸進式載入）¶

Skill 的內容依需要分三層載入，避免浪費 context 空間：

graph LR
    A["Layer 1\nMetadata\n(name + description)\n~100 字\n永遠在 context"] --> B["Layer 2\nSKILL.md body\n(Markdown 指令)\n觸發後載入\n建議 < 500 行"]
    B --> C["Layer 3\nBundled Resources\n(scripts / references / assets)\n按需載入\n無大小限制"]

• Layer 1：Claude 在每次請求時都會看到所有技能的 name 和 description，用來決定是否觸發。
• Layer 2：觸發後才讀取 SKILL.md 本文，包含詳細流程。
• Layer 3：scripts 可直接執行而不載入；references 按需讀取；assets 用於輸出。

Scripts 架構¶

模組依賴關係¶

graph TD
    run_loop["run_loop.py\n優化迴圈入口"] --> run_eval["run_eval.py\n觸發率評估"]
    run_loop --> improve["improve_description.py\n描述文字改進"]
    run_loop --> gen_report["generate_report.py\n生成 HTML 報告"]
    improve --> utils["utils.py\nparse_skill_md()"]
    run_eval --> utils
    aggregate["aggregate_benchmark.py\n彙整 benchmark"] --> |讀取| grading_json[("grading.json")]
    aggregate --> |產生| benchmark_json[("benchmark.json\nbenchmark.md")]
    package["package_skill.py\n封裝 .skill"] --> validate["quick_validate.py\n格式驗證"]

各腳本職責¶

run_eval.py 觸發評估機制¶

描述優化的核心是測試 Claude 是否會「觸發」技能。run_eval.py 實作細節：

sequenceDiagram
    participant RunLoop as run_loop.py
    participant Eval as run_eval.py
    participant FS as .claude/commands/
    participant Claude as claude -p (subprocess)

    RunLoop->>Eval: run_eval(eval_set, description)
    Eval->>FS: 寫入臨時 skill command file<br/>(含測試中的 description)
    Eval->>Claude: 啟動 claude -p --output-format stream-json<br/>--include-partial-messages
    Claude-->>Eval: Stream JSON 事件
    Note over Eval,Claude: 監聽 content_block_start<br/>偵測 Skill 或 Read 工具呼叫
    alt 觸發了技能
        Eval-->>RunLoop: triggered = True
    else 未觸發
        Eval-->>RunLoop: triggered = False
    end
    Eval->>FS: 清理臨時 command file

關鍵設計： - 使用 ProcessPoolExecutor 平行執行多個查詢（預設 10 workers） - 每個查詢執行 3 次（runs_per_query），以觸發率 ≥ 50% 判定為「通過」 - 透過 stream-json 的 content_block_start 事件早期偵測，避免等待完整回應 - 刪除 CLAUDECODE 環境變數以允許巢狀執行 claude -p

Description 優化迴圈¶

flowchart TD
    A[輸入: eval_set.json\n+ skill path + model] --> B[60/40 Train/Test 分割\n按 should_trigger 分層]
    B --> C[Iteration N]
    C --> D[run_eval: 平行執行\ntrain + test 查詢]
    D --> E{train 全部通過?}
    E -- 是 --> F[記錄結果]
    E -- 否 --> G[improve_description.py\n呼叫 claude -p 改進描述]
    G --> H{達到 max_iterations?}
    H -- 否 --> C
    H -- 是 --> F
    F --> I[選取 Test Score 最高的迭代\n作為 best_description]
    I --> J[generate_report.py\n生成 HTML 報告]
    J --> K([輸出 best_description JSON])

• 防 overfitting：train 集用於改進，test 集用於選拔最終結果
• 描述長度限制：超過 1024 字元時自動呼叫第二次 claude -p 縮短
• 歷史感知：blinded_history 傳給 improve 函式，要求不重複相同結構

子代理人（SubAgents）¶

三個子代理各有獨立職責，由 SKILL.md 描述的主工作流程按需 spawn：

graph LR
    Main[主工作流程\nClaude + skill-creator] -->|評分 assertions| Grader["grader.md\n讀取 transcript + outputs\n輸出 grading.json"]
    Main -->|盲測比較| Comparator["comparator.md\n比較 output A vs B\n輸出 comparison.json"]
    Main -->|後驗分析| Analyzer["analyzer.md\n解讀 benchmark 模式\n或分析 A/B 差異原因"]

資料流與檔案結構¶

eval 執行的工作區組織方式：

<skill-name>-workspace/
├── skill-snapshot/           # 改進現有技能時的舊版快照
├── evals/
│   └── evals.json            # 測試案例定義（prompts + assertions）
└── iteration-1/
    ├── benchmark.json        # 彙整統計（aggregate_benchmark.py 產生）
    ├── benchmark.md
    └── eval-<name>/
        ├── eval_metadata.json
        ├── with_skill/
        │   ├── outputs/      # 技能執行產物
        │   ├── timing.json   # tokens + duration（子代理完成通知時擷取）
        │   └── grading.json  # 評分結果
        └── without_skill/    # 或 old_skill/（基準對照）
            ├── outputs/
            ├── timing.json
            └── grading.json

JSON Schema 摘要¶

平台差異¶

設計原則摘要¶

1. Theory of Mind 優先：指令重視解釋「為什麼」，而非機械式的 MUST/NEVER，讓執行的 LLM 能真正理解意圖。
2. 避免過度擬合：描述優化使用 train/test split；技能改進指導不要針對特定範例微調，要泛化。
3. 並行優先：with_skill 與 baseline 在同一輪 spawn，描述評估用 ProcessPoolExecutor。
4. 人工審查是核心：每次迭代都透過 eval viewer 讓使用者親眼比較輸出，不跳過人工評估。
5. 可複用腳本：若多個測試案例都需要同樣的 helper 腳本，應打包進 scripts/，避免每次重複發明。