# Skill Creator

> 建立新技能、修改與改進現有技能，並衡量技能表現。當使用者想要從頭建立技能、編輯或最佳化現有技能、執行評估以測試技能、透過變異數分析對技能表現進行基準測試，或最佳化技能描述以提高觸發準確性時使用。

- Skill: `tai-ch0802/skill-creator` (Agent Skill)
- Install (CLI): `npx skillmds@latest add tai-ch0802/skill-creator`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tai-ch0802/skill-creator/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: Tai-ch0802 (https://skillmd.com/u/tai-ch0802)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/tai-ch0802/skill-creator

---


# 技能建立器 (Skill Creator)

這是一個用於建立新技能並反覆迭代改進它們的技能。

從高層次來看，建立技能的流程如下：

- 決定你希望該技能做什麼，以及大致上該如何進行
- 寫出該技能的草稿
- 建立幾個測試提示詞，並在可以存取該技能的 Claude 實例上執行它們
- 協助使用者對結果進行定性與定量的評估
  - 在背景執行這些測試的同時，如果沒有定量評估，可以先草擬一些（如果已經有一些，可以直接使用或根據需要進行修改）。然後向使用者解釋它們（或如果它們已經存在，向使用者解釋現有的評估）
  - 使用 `eval-viewer/generate_review.py` 腳本向使用者展示結果供其查看，同時讓他們查看定量指標
  - 根據使用者對結果評估的回饋（以及定量基準測試中顯露出的任何明顯缺陷），重寫該技能
- 重複此過程，直到你滿意為止
- 擴大測試集，並在更大規模上再試一次

當使用此技能時，你的工作是弄清楚使用者在此流程中的進度，然後介入並協助他們推進這些階段。因此，例如，他們可能會說：「我想製作一個用於 X 的技能」。你可以幫助釐清他們的意思、編寫草稿、設定測試案例、弄清楚他們希望如何評估、執行所有的提示詞，並反覆迭代。

另一方面，也許他們已經有了技能的草稿。在這種情況下，你可以直接進入循環中的評估/迭代部分。

當然，你應該始終保持彈性，如果使用者說：「我不需要執行一堆評估，只要跟我同步一下感覺就好」，你也可以這麼做。

然後在技能完成後（不過同樣的，順序是有彈性的），你也可以執行技能描述改進器，我們有一個完全獨立的腳本，用於最佳化技能的觸發。

沒問題吧？太好了。

## 與使用者溝通

技能建立器可能會被程式設計術語熟悉度差異很大的人使用。如果你還沒聽說（你怎麼可能會聽說呢，這才剛開始不久），現在有一種趨勢是，Claude 的強大功能正激勵水管工打開他們的終端機，父母和祖父母 Google 搜尋「如何安裝 npm」。但另一方面，大部分的使用者可能都具備相當的電腦知識。

因此，請留意上下文線索，了解該如何遣詞用字！在預設情況下，只是給你一些概念：

- 「評估」和「基準測試」是處於邊緣地帶，但可以接受
- 對於「JSON」和「斷言 (assertion)」，除非你看到使用者有明確的線索顯示他們了解這些概念，否則在不解釋它們的情況下使用時要小心。

如果有疑慮，簡短解釋一下術語也無妨，如果你不確定使用者是否理解，請隨時提供簡短定義來澄清術語。

---

## 建立技能

### 擷取意圖

首先了解使用者的意圖。當前的對話可能已經包含使用者想要擷取的工作流（例如，他們說「把這個變成一個技能」）。如果是這樣，請先從對話歷史紀錄中提取答案 — 使用的工具、步驟順序、使用者所做的修正、觀察到的輸入/輸出格式。使用者可能需要填補空白，並應在繼續下一步之前確認。

1. 這個技能應該讓 Claude 能做什麼？
2. 這個技能應該在什麼時候觸發？（使用者的什麼短語/上下文）
3. 預期的輸出格式是什麼？
4. 我們應該設定測試案例來驗證技能是否確實運作嗎？有客觀可驗證輸出的技能（檔案轉換、資料擷取、程式碼生成、固定的工作流程步驟）會受益於測試案例。具有主觀輸出的技能（寫作風格、藝術）通常不需要。請根據技能類型建議適當的預設選項，但讓使用者決定。

### 訪談與研究

主動提出有關邊緣情況、輸入/輸出格式、範例檔案、成功標準和相依性的問題。在理清這部分之前，先不要急著寫測試提示詞。

檢查可用的 MCP - 如果對研究有幫助（搜尋文件、尋找相似的技能、查找最佳實踐），如果有的話透過子代理程式進行平行研究，否則進行行內研究。準備好相關背景知識，以減輕使用者的負擔。

### 編寫 SKILL.md

根據使用者訪談，填寫這些組件：

- **name**: 技能識別碼
- **description**: 何時觸發，它的作用。這是主要的觸發機制 - 應包含技能的功能以及何時使用它的特定情境。所有「何時使用」的資訊都放在這裡，而不是放在內文裡面。注意：目前 Claude 有「低估觸發」技能的傾向 -- 即在技能有用時不使用它們。為了對抗這個問題，請讓技能描述稍微「強勢」一點。因此，與其寫「如何建立簡單快速的儀表板來顯示內部 Anthropic 資料。」，不如寫「如何建立一個簡單快速的儀表板來顯示內部 Anthropic 資料。確保只要使用者提及儀表板、資料視覺化、內部指標，或想要顯示任何類型的公司資料時，即使他們沒有明確要求『儀表板』，也務必使用此技能。」
- **compatibility**: 需要的工具、相依性（選用，很少需要）
- **技能的其餘部分 :)**

### 技能寫作指南

#### 技能的解剖結構

```
skill-name/
├── SKILL.md (必填)
│   ├── YAML frontmatter (包含必須的 name, description)
│   └── Markdown 說明指令
└── Bundled Resources (選用)
    ├── scripts/    - 用於確定性/重複性任務的可執行程式碼
    ├── references/ - 視需要載入到內容上下文中的文件
    └── assets/     - 用於輸出的檔案 (範本、圖示、字型)
```

#### 漸進式揭露

技能使用三層載入系統：
1. **Metadata** (名稱 + 描述) - 始終在上下文中 (~100 個字)
2. **SKILL.md body** - 當技能觸發時在上下文中 (<500 行為佳)
3. **Bundled resources** - 依需要載入 (無限制，腳本可以在不載入的情況下執行)

這些字數只是估計值，如果需要，你可以自由增加。

**關鍵模式:**
- 保持 SKILL.md 少於 500 行；如果您接近此限制，請添加額外的層次結構，並向使用該技能的模型明確指示下一步應採取什麼行動來後續處理。
- 從 SKILL.md 明確引用檔案，並提供何時閱讀它們的指引。
- 對於大型參考檔案（> 300行），請包含目錄。

**領域組織**: 當一項技能支援多個領域/框架時，按變體組織：
```
cloud-deploy/
├── SKILL.md (工作流 + 選擇)
└── references/
    ├── aws.md
    ├── gcp.md
    └── azure.md
```
Claude 僅讀取相關的參考檔案。

#### 不會帶來驚嚇的原則 (Principle of Lack of Surprise)

不言而喻，技能不得包含惡意軟體、漏洞攻擊程式碼，或任何可能損害系統安全的內容。如果將技能內容描述出來，它不應該讓使用者的意圖感到驚嚇。請勿配合建立具誤導性或旨在促成未經授權之存取、資料外洩或其他惡意活動技能的請求。不過，像是「角色扮演成某某 XYZ」則是沒問題的。

#### 撰寫模式

在說明中盡量使用祈使句。

**定義輸出格式** - 你可以這樣做：
```markdown
## Report structure
ALWAYS use this exact template:
# [Title]
## Executive summary
## Key findings
## Recommendations
```

**範例模式** - 包含範例會很有用。你可以像這樣格式化它們（但如果範例中包含「Input」和「Output」，你可能需要稍微調整）：
```markdown
## Commit message format
**Example 1:**
Input: Added user authentication with JWT tokens
Output: feat(auth): implement JWT-based authentication
```

### 寫作風格

盡量向模型解釋事情為什麼重要，而不是使用強勢刻版的「必須（MUST）」。運用心智理論，嘗試讓技能具有普適性，而不是局限於非常狹隘的特定範例。從寫草稿開始，然後以全新的視角審視它並加以改進。

### 測試案例

寫完技能草稿後，想出 2-3 個真實的測試提示詞 — 真實使用者實際會說的那種話。與使用者分享它們：[你不需要使用這個確切的用語] 「這裡有幾個我想嘗試的測試案例。這些看起來正確嗎，還是你想增加更多？」然後執行它們。

將測試案例儲存到 `evals/evals.json`。暫時不要寫斷言 — 只要寫提示詞就好。你將在下一個步驟（程式執行時）草擬斷言。

```json
{
  "skill_name": "example-skill",
  "evals": [
    {
      "id": 1,
      "prompt": "User's task prompt",
      "expected_output": "Description of expected result",
      "files": []
    }
  ]
}
```

請參閱 `references/schemas.md` 獲取完整的架構（包含 `assertions` 欄位，稍後你將添加該欄位）。

## 執行和評估測試案例

本節是一個連續的序列 — 不要中途停下來。**請勿**使用 `/skill-test` 或任何其他測試技能。

將結果放在與技能目錄同層級的 `<skill-name>-workspace/` 中。在工作區內，按迭代次數組織結果（`iteration-1/`、`iteration-2/` 等），在其中，每個測試案例都有一個目錄（`eval-0/`、`eval-1/` 等）。不要預先建立所有這些 — 只需在過程中建立目錄即可。

### 步驟 1：在同一個輪次中產生所有執行 (包含使用技能的版本和基準版本)

對於每個測試案例，在同一輪次中產生兩個子代理程式 — 一個帶有技能，一個沒有。這很重要：不要先產生具有技能的執行，然後再回頭執行基準測試。一次啟動所有項目，這樣它們都會在同一時間完成。

**具備技能的執行：**

```
Execute this task:
- Skill path: <path-to-skill>
- Task: <eval prompt>
- Input files: <eval files if any, or "none">
- Save outputs to: <workspace>/iteration-<N>/eval-<ID>/with_skill/outputs/
- Outputs to save: <what the user cares about — e.g., "the .docx file", "the final CSV">
```

**基準測試執行** (相同的提示詞，但基準取決於上下文):
- **創建新技能**：根本沒有技能。相同的提示詞，沒有技能路徑，儲存到 `without_skill/outputs/`。
- **改進現有技能**：舊版本。在編輯之前，先建立技能的快照（`cp -r <skill-path> <workspace>/skill-snapshot/`），然後將基準測試子代理程式指向快照。儲存到 `old_skill/outputs/`。

為每個測試案例編寫一個 `eval_metadata.json` (目前斷言可以留空)。根據它正在測試的內容為每個評估提供一個描述性名稱 — 而不是僅僅是「eval-0」。將此名稱也用於目錄名稱。如果此迭代使用新的或修改過的評估提示詞，請為每個新的評估目錄建立這些檔案 — 不要假設它們會接續之前的迭代。

```json
{
  "eval_id": 0,
  "eval_name": "descriptive-name-here",
  "prompt": "The user's task prompt",
  "assertions": []
}
```

### 步驟 2：當程式還在執行時，草擬斷言

不要只是等待執行完成 — 你可以更有效率地利用這段時間。為每個測試案例草擬定量的斷言，並向使用者解釋它們。如果 `evals/evals.json` 中已經存在斷言，查閱並解釋它們在檢查什麼。

好的斷言是客觀可驗證的，並且具有描述性名稱 — 必須讀取起來很清楚在基準對測試中每一項檢查意味著什麼，讓任何一眼看去結果的人都能夠立即明白在檢查什麼。對於具備主觀性評估判斷的輸出（例如：寫作風格、視覺設計等）使用定性評估比較好 — 切勿去逼迫去斷言這些須要由人去實行判斷的事務。

一旦草稿就緒，請利用草擬好的斷言更新 `eval_metadata.json` 檔案及 `evals/evals.json`。同時要告訴使用者他們會在這個查看器 (viewer) 中看到什麼 — 包括定性的產出和定量的基準比較測試。

### 步驟 3：在各次執行完成時，記錄計時資料

每個子代理任務完成時，你會收到含 `total_tokens` 與 `duration_ms` 的通知。請立刻將這份資料存到該執行目錄下的 `timing.json`：

```json
{
  "total_tokens": 84852,
  "duration_ms": 23332,
  "total_duration_seconds": 23.3
}
```

這是擷取此資料的唯一機會——它透過任務通知傳遞，不會被保存到別處。請在每則通知抵達時立即處理，不要試圖批次處理。

### 步驟 4：評分、彙總並啟動檢視器

所有執行皆完成後：

1. **為每次執行評分** —— 派出評分子代理（或自己直接評分），它會讀取 `agents/grader.md` 並逐項對照斷言檢查產出。將結果存到該執行目錄下的 `grading.json`。`grading.json` 的 expectations 陣列**必須**使用 `text`、`passed`、`evidence` 這三個欄位（不可使用 `name`/`met`/`details` 等其他名稱）—— 檢視器仰賴這幾個確切名稱。對於可程式化檢查的斷言，請寫腳本執行而非肉眼比對 —— 腳本快、可靠，且可跨迭代重用。

2. **彙總成基準資料** —— 在 skill-creator 目錄底下執行彙總腳本：
   ```bash
   python -m scripts.aggregate_benchmark <workspace>/iteration-N --skill-name <name>
   ```
   這會產出 `benchmark.json` 與 `benchmark.md`，內含每個配置的 pass_rate、耗時與 token 數，附均值 ± 標準差以及差異值。若要手動產出 `benchmark.json`，請參考 `references/schemas.md` 中檢視器期待的精確 schema。請將每個 with_skill 版本放在其對應 baseline 之前。

3. **進行分析者視角的審視** —— 閱讀基準資料，找出彙總統計可能掩蓋的模式。詳見 `agents/analyzer.md`（「Analyzing Benchmark Results」段落），需特別留意：不論技能是否啟用都全數通過的斷言（無區分力）、變異度過高的評估（可能不穩定），以及時間／token 的取捨。

4. **啟動檢視器**，同時呈現質性產出與量化資料：
   ```bash
   nohup python <skill-creator-path>/eval-viewer/generate_review.py \
     <workspace>/iteration-N \
     --skill-name "my-skill" \
     --benchmark <workspace>/iteration-N/benchmark.json \
     > /dev/null 2>&1 &
   VIEWER_PID=$!
   ```
   第二代以後，請額外加上 `--previous-workspace <workspace>/iteration-<N-1>`。

   **Cowork／無頭環境**：若 `webbrowser.open()` 不可用，或環境沒有顯示器，請以 `--static <output_path>` 寫出獨立 HTML 檔案，而非啟動伺服器。當使用者按下「Submit All Reviews」時，回饋會以 `feedback.json` 的形式下載。下載完成後，將 `feedback.json` 複製到工作區目錄，供下一輪迭代取用。

注意：請使用 `generate_review.py` 來產生檢視器，無需自行撰寫 HTML。

5. **告知使用者**，例如：「我已在你的瀏覽器開啟結果。畫面有兩個分頁——『Outputs』讓你逐項瀏覽各測試案例並留下回饋，『Benchmark』則顯示量化比較。完成後請回到這裡告訴我。」

### 使用者在檢視器中會看到什麼

「Outputs」分頁一次顯示一個測試案例：
- **Prompt**：原始任務提示。
- **Output**：技能產出的檔案，能直接內嵌呈現的就直接內嵌呈現。
- **Previous Output**（第二代以後）：可摺疊區塊，顯示上一代的輸出。
- **Formal Grades**（若已執行評分）：可摺疊區塊，顯示斷言通過／未通過。
- **Feedback**：邊輸入邊自動儲存的文字方塊。
- **Previous Feedback**（第二代以後）：上次的回饋，顯示在文字方塊下方。

「Benchmark」分頁則顯示統計摘要：各配置的通過率、計時與 token 用量，並含每項評估的細節以及分析觀察。

可用「上一筆／下一筆」按鈕或方向鍵切換。完成後使用者會按下「Submit All Reviews」，將所有回饋寫入 `feedback.json`。

### 步驟 5：閱讀回饋

當使用者告訴你已完成時，讀取 `feedback.json`：

```json
{
  "reviews": [
    {"run_id": "eval-0-with_skill", "feedback": "the chart is missing axis labels", "timestamp": "..."},
    {"run_id": "eval-1-with_skill", "feedback": "", "timestamp": "..."},
    {"run_id": "eval-2-with_skill", "feedback": "perfect, love this", "timestamp": "..."}
  ],
  "status": "complete"
}
```

空白回饋代表使用者覺得結果可以。請把改進心力集中在使用者明確抱怨的測試案例上。

工作結束時記得關閉檢視器伺服器：

```bash
kill $VIEWER_PID 2>/dev/null
```

---

## 改進技能

這是整個循環的核心。你已經跑完測試案例，使用者也已審視結果，現在要根據他們的回饋讓技能更好。

### 改進思路

1. **從回饋中歸納出通則。** 整個任務的大格局是：我們希望打造能被使用上百萬次（也許更多）、適用於各種不同提示的技能。你和使用者反覆迭代少數幾個範例，是因為這樣比較快——使用者對這些範例瞭如指掌，能迅速評估新產出。但若你們共同開發出來的技能**只對這幾個範例有效**，它就毫無價值。遇到頑固的問題時，不要塞入過度針對性的修補，也不要硬塞「絕對必須（MUST）」這類僵硬規定；嘗試換個角度、改用不同的比喻，或建議不同的工作模式。這類嘗試成本低，說不定就找到好答案。

2. **保持指令精煉。** 把沒有實質貢獻的內容刪掉。請不只看最終產出，也看執行過程的對話紀錄——若技能讓模型在無謂的事情上耗費大量時間，可以試著刪除導致此情況的段落，看看會發生什麼。

3. **解釋「為什麼」。** 盡力把你要求模型做的每件事背後的**動機**講清楚。今天的 LLM 很*聰明*，具備理論心智，給予好的指令骨架後能超越照本宣科、真正把事情做好。即使使用者的回饋很簡短或語帶不耐，也請真正理解這項任務、使用者為何這樣寫、實際寫了什麼，再把這份理解轉化進技能指令中。如果你發現自己用全大寫的 ALWAYS／NEVER 或極度僵硬的結構，這就是黃旗訊號——可能的話，請改寫並解釋背後理由，讓模型理解這件事為何重要。這樣更有人情、更有力，也更有效。

4. **找出測試案例間的重複工作。** 閱讀執行紀錄，留意子代理是否各自獨立寫出類似的輔助腳本，或對同一件事採取了相同的多步驟流程。如果三個測試案例的子代理都寫了 `create_docx.py` 或 `build_chart.py`，這就是強訊號：這個腳本應該由技能本身打包提供。寫一次，放進 `scripts/`，並在技能裡指示模型使用它。這能讓未來每次呼叫都不必重造輪子。

這項任務相當重要（我們可是想創造一年數十億的經濟價值！），思考時間不是瓶頸；請放慢腳步，好好琢磨。建議先寫一份草稿修訂，再以新眼光重看一次並進一步改進。盡可能進入使用者的腦袋，理解他們真正想要與需要的東西。

### 迭代循環

改進技能之後：

1. 將改進套用到技能上。
2. 將所有測試案例（包含 baseline）重新跑進新的 `iteration-<N+1>/` 目錄。若是建立新技能，baseline 永遠是 `without_skill`（不啟用技能），跨迭代不變。若是改進現有技能，請依情境判斷適合的 baseline：使用者最初帶來的原始版本，或是上一代的版本。
3. 使用 `--previous-workspace` 指向上一代，啟動檢視器。
4. 等使用者審視完並告訴你結果。
5. 讀取新的回饋，再次改進，反覆進行。

持續直到下列任一條件滿足：
- 使用者表示滿意。
- 回饋全部空白（一切看起來都好）。
- 你已無法再做出有意義的改進。

---

## 進階：盲測比較

如果想對技能的兩個版本進行更嚴謹的比較（例如使用者問「新版真的比較好嗎？」），可以使用盲測比較系統。詳見 `agents/comparator.md` 與 `agents/analyzer.md`。基本概念是：把兩份產出交給一個獨立代理，不告訴它哪個是哪個，讓它判斷品質高低，然後分析勝出方為何勝出。

此步驟為選用，需要子代理，多數使用者並不需要。靠人工審查的循環通常已足夠。

---

## 描述最佳化

SKILL.md frontmatter 的 description 欄位是決定 Claude 是否啟用技能的主要機制。建立或改進技能後，請主動提出最佳化描述以提升觸發準確度。

### 步驟 1：產生觸發評估查詢

撰寫 20 條評估查詢——should-trigger 與 should-not-trigger 混合。以 JSON 儲存：

```json
[
  {"query": "the user prompt", "should_trigger": true},
  {"query": "another prompt", "should_trigger": false}
]
```

查詢必須擬真，是 Claude Code 或 Claude.ai 真實使用者會打出的內容；不要寫成抽象的需求，而是具體、有細節、帶有實際情境，例如：檔案路徑、使用者的工作或處境背景、欄名與欄值、公司名稱、URL，以及一點點來龍去脈。可以混入小寫、縮寫、錯字或口語。長度也要混搭，並聚焦在邊界案例而非一目了然的情境（使用者稍後會幫你把關）。

不好：`"Format this data"`、`"Extract text from PDF"`、`"Create a chart"`

好：`"ok so my boss just sent me this xlsx file (its in my downloads, called something like 'Q4 sales final FINAL v2.xlsx') and she wants me to add a column that shows the profit margin as a percentage. The revenue is in column C and costs are in column D i think"`

**should-trigger** 查詢（8–10 條）要思考覆蓋面，包含同一意圖的不同表達——有正式的、有口語的；包含使用者沒有明說技能名稱或檔案類型，但顯然需要它的情境；混入一些少見的用法，以及與其他技能競爭但本技能應勝出的案例。

**should-not-trigger** 查詢（8–10 條）最有價值的是「擦邊球」——與技能共用關鍵字或概念，但其實需要的是別的東西。可從相鄰領域、容易讓單純關鍵字匹配誤觸發的模糊措辭、以及雖然涉及技能擅長的事但其實另一工具更合適的情境著手。

最該避免的事：請不要讓 should-not-trigger 查詢明顯不相關。用「寫一個費氏數列函式」當作 PDF 技能的負樣本太過簡單，根本測不出任何東西。負樣本必須真有點難度。

### 步驟 2：交給使用者審視

用 HTML 範本將評估集呈現給使用者審視：

1. 讀取範本：`assets/eval_review.html`。
2. 替換佔位符：
   - `__EVAL_DATA_PLACEHOLDER__` → 評估項目的 JSON 陣列（不要加引號——它是 JS 變數的賦值）
   - `__SKILL_NAME_PLACEHOLDER__` → 技能名稱
   - `__SKILL_DESCRIPTION_PLACEHOLDER__` → 技能目前的描述
3. 寫入暫存檔（例如 `/tmp/eval_review_<skill-name>.html`）並開啟：`open /tmp/eval_review_<skill-name>.html`
4. 使用者可以編輯查詢、切換 should-trigger、新增／移除項目，然後按下「Export Eval Set」。
5. 檔案會下載到 `~/Downloads/eval_set.json`——若有多份（例如 `eval_set (1).json`），請取最新的那一份。

這一步很重要——評估查詢若不好，描述也好不到哪去。

### 步驟 3：執行最佳化循環

告訴使用者：「這需要一些時間 — 我會在背景執行最佳化循環並定期檢查。」

將評估集儲存到工作區，然後在背景執行：

```bash
python -m scripts.run_loop \
  --eval-set <path-to-trigger-eval.json> \
  --skill-path <path-to-skill> \
  --model <model-id-powering-this-session> \
  --max-iterations 5 \
  --verbose
```

使用系統提示詞中的模型 ID（驅動當前對話的模型），這樣觸發測試就會符合使用者實際體驗的狀況。

在執行期間，定期查看(tail)輸出，向使用者報告目前進行到第幾次迭代，以及分數看起來如何。

這會自動處理整個最佳化循環。它將評估集分為 60% 訓練集和 40% 測試集，評估目前的描述（每個查詢執行 3 次以獲得可靠的觸發率），然後呼叫 Claude 根據失敗的情況提出改進建議。它會在訓練集和測試集上重新評估每個新描述，最多迭代 5 次。完成後，它會在瀏覽器中開啟一個 HTML 報告，顯示每次迭代的結果，並回傳包含 `best_description` 的 JSON — 這是根據測試分數而非訓練分數選出的，以避免過度擬合。

### 技能觸發的運作方式

了解觸發機制有助於設計更好的評估查詢。技能以其名稱 + 描述出現在 Claude 的 `available_skills` 列表中，Claude 會根據該描述決定是否參考該技能。重要的是要知道，Claude 只有在無法輕易自行處理任務時才會參考技能 — 像「讀取此 PDF」這類簡單的單一步驟查詢，即使描述完全符合，也可能不會觸發技能，因為 Claude 可以直接使用基本工具處理它們。複雜、多步驟或專門的查詢在描述相符時，才能可靠地觸發技能。

這意味著你的評估查詢應該要夠具體且有實質內容，讓 Claude 真正覺得需要參考技能才有幫助。像「讀取檔案 X」這樣簡單的查詢是很差的測試案例 — 無論描述寫得多好，它們都不會觸發技能。

### 步驟 4：套用結果

從 JSON 輸出中取得 `best_description`，並更新技能的 SKILL.md frontmatter。向使用者展示修改前後的差異並報告分數。

---

### 打包與展示 (僅當有 `present_files` 工具時)

檢查你是否有權限使用 `present_files` 工具。如果沒有，跳過此步驟。如果有的話，打包該技能並將 .skill 檔案呈現給使用者：

```bash
python -m scripts.package_skill <path/to/skill-folder>
```

打包後，引導使用者前往產生的 `.skill` 檔案路徑，以便他們安裝。

---

## 關於 Claude.ai 的特定指示

在 Claude.ai 中，核心工作流程是相同的（起草 → 測試 → 審查 → 改進 → 重複），但因為 Claude.ai 沒有子代理 (subagents)，所以有些機制會改變。以下是需要調整的地方：

**執行測試案例**：沒有子代理意味著沒有平行執行。對於每個測試案例，讀取技能的 SKILL.md，然後自己遵循其指示來完成測試提示詞。一次做一個。這不如獨立的子代理嚴謹（你寫了技能而且你也在執行它，所以你有完整的上下文），但它是一個有用的健全性檢查 — 而且人類審查步驟可以彌補這一點。跳過基準測試 (baseline) 執行 — 只需使用技能來完成要求的任務。

**審查結果**：如果你無法開啟瀏覽器（例如，Claude.ai 的 VM 沒有顯示器，或者你在遠端伺服器上），完全跳過瀏覽器檢視器。改為直接在對話中呈現結果。對於每個測試案例，顯示提示詞和輸出。如果輸出是使用者需要看到的檔案（如 .docx 或 .xlsx），將其儲存到檔案系統並告訴他們檔案在哪裡，以便他們下載和檢查。在對話中直接詢問回饋：「這看起來如何？有什麼你想改變的嗎？」

**基準測試 (Benchmarking)**：跳過定量基準測試 — 它依賴於沒有子代理就沒有意義的基準比較。專注於使用者的定性回饋。

**迭代循環**：同前 — 改進技能，重新執行測試案例，詢問回饋 — 只是中間沒有瀏覽器檢視器。如果有檔案系統，你仍然可以將結果組織到迭代目錄中。

**描述最佳化**：此部分需要 `claude` CLI 工具（具體來說是 `claude -p`），這僅在 Claude Code 中可用。如果你在 Claude.ai 上，請跳過此步驟。

**盲測比較 (Blind comparison)**：需要子代理。跳過。

**打包 (Packaging)**：`package_skill.py` 腳本可在任何有 Python 和檔案系統的地方運作。在 Claude.ai 上，你可以執行它，使用者可以下載產生出來的 `.skill` 檔案。

**更新現有技能**：使用者可能要求你更新現有技能，而不是建立新技能。在這種情況下：
- **保留原始名稱。** 注意技能的目錄名稱和 `name` frontmatter 欄位 -- 保持不變。例如，如果安裝的技能是 `research-helper`，請輸出 `research-helper.skill`（而不是 `research-helper-v2`）。
- **在編輯前複製到可寫入的位置。** 安裝的技能路徑可能是唯讀的。複製到 `/tmp/skill-name/`，在那裡編輯，然後從該副本打包。
- **如果是手動打包，請先在 `/tmp/` 準備好**，然後再複製到輸出目錄 -- 直接寫入可能會因為權限問題而失敗。

---

## 針對 Cowork 的特定指示

如果你在 Cowork 中，需要了解的主要事項有：

- 你有子代理，所以主要工作流程（平行產生測試案例、執行基準測試、評分等）都能運作。（然而，如果你遇到嚴重的超時問題，可以改為循序執行測試提示詞，而非平行執行。）
- 你沒有瀏覽器或顯示器，所以在產生評估檢視器時，請使用 `--static <output_path>` 寫入獨立的 HTML 檔案，而不是啟動伺服器。然後提供一個連結讓使用者點擊以在他們的瀏覽器中開啟該 HTML。
- 不知為何，Cowork 的設定似乎讓 Claude 不太願意在執行測試後產生評估檢視器，所以為了再次強調：無論你是在 Cowork 還是 Claude Code 中，執行測試後，你都應該始終產生評估檢視器讓人類在你自己修改技能並嘗試修正之前查看範例，請使用 `generate_review.py`（不要自己寫客製化的 html 程式碼）。很抱歉我必須用大寫強調：在你自己評估輸入*之前*，請產生評估檢視器 (GENERATE THE EVAL VIEWER BEFORE evaluating inputs yourself)。你要盡快把它們呈現給人類！
- 回饋機制的運作方式不同：因為沒有運作中的伺服器，檢視器中的「提交所有審查 (Submit All Reviews)」按鈕會將 `feedback.json` 下載為一個檔案。然後你可以從那裡讀取它（你可能需要先要求存取權限）。
- 打包可以運作 — `package_skill.py` 只需要 Python 和檔案系統。
- 描述最佳化（`run_loop.py` / `run_eval.py`）在 Cowork 中應該可以順利運作，因為它使用 `claude -p` 作為子程序，而不是瀏覽器，但請留到你完全完成技能製作且使用者同意狀況良好時再使用。
- **更新現有技能**：使用者可能要求你更新現有技能，而不是建立新技能。請遵循上方 claude.ai 區塊中的更新指南。

---

## 參考檔案

`agents/` 目錄包含專門子代理的指示。當你需要產生相關子代理時請閱讀它們。

- `agents/grader.md` — 如何根據輸出評估斷言
- `agents/comparator.md` — 如何對兩個輸出進行盲測 A/B 比較
- `agents/analyzer.md` — 如何分析為什麼一個版本勝過另一個版本

`references/` 目錄有其他文件：
- `references/schemas.md` — evals.json、grading.json 等的 JSON 結構

---

在此再次重申核心循環以加強印象：

- 弄清楚該技能的目的是什麼
- 起草或編輯技能
- 在測試提示詞上執行有權限存取該技能的 claude
- 與使用者一起評估輸出：
  - 建立 benchmark.json 並執行 `eval-viewer/generate_review.py` 以幫助使用者審查它們
  - 執行定量評估
- 重複直到你和使用者滿意為止
- 打包最終技能並將其回傳給使用者。

請在你的待辦事項清單 (TodoList) 中新增步驟（如果你有的話），以確保你不會忘記。如果你在 Cowork 中，請特別將「建立 evals JSON 並執行 `eval-viewer/generate_review.py` 讓人類可以審查測試案例」放入你的 TodoList 中，以確保這一定會發生。

祝你好運！