Skill Creator

---
name: skill-creator
description: >
  建立新技能、修改和改進現有技能、衡量技能效能。當使用者想要從零開始建立技能、編輯或優化現有技能、執行評估測試、進行基準測試效能分析、或優化技能描述以提升觸發準確度時使用此技能。請確保在使用者提到建立技能、撰寫 skill、skill 開發、技能測試、技能優化、或想要將工作流程轉換為可重複使用的技能時啟用此技能。
---

# 技能建立器 (Skill Creator)

一個用於建立新技能並持續迭代改進的技能。

整體而言，建立技能的流程如下：

- 決定你希望技能做什麼，以及大致的實作方式
- 撰寫技能的草稿
- 建立幾個測試提示詞，並在具有該技能的 Claude 上執行
- 協助使用者從質性和量化兩方面評估結果
  - 在背景執行測試的同時，如果還沒有量化評估則撰寫一些（如果已有，可以直接使用或視需要修改）。然後向使用者解釋這些評估
  - 使用 `eval-viewer/generate_review.py` 腳本向使用者展示結果，同時讓他們查看量化指標
- 根據使用者評估結果的回饋重寫技能（以及量化基準測試中發現的明顯缺陷）
- 重複直到滿意為止
- 擴大測試集並在更大規模上再次測試

你使用此技能時的工作是判斷使用者在這個流程中的位置，然後協助他們繼續推進。例如，也許他們說「我想做一個 X 的技能」。你可以幫助釐清他們的意思、撰寫草稿、編寫測試案例、了解他們想要如何評估、執行所有提示詞，然後重複。

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

當然，你應該始終保持靈活，如果使用者說「我不需要執行一堆評估，跟我一起隨意試試就好」，那就這樣做。

然後在技能完成之後（但同樣，順序是靈活的），你也可以執行技能描述改善器，我們有一個專門的腳本來優化技能的觸發。

## 與使用者溝通

技能建立器可能被各種程度的使用者使用，從不熟悉程式術語的新手到經驗豐富的開發者都有。現在有一個趨勢：Claude 的強大能力正在啟發水電工打開終端機、讓父母和祖父母去搜尋「如何安裝 npm」。另一方面，大多數使用者可能相當懂電腦。

所以請注意上下文線索來理解如何措辭你的溝通！在預設情況下，給你一些參考：

- 「evaluation（評估）」和「benchmark（基準測試）」是可以接受的邊界用語
- 對於「JSON」和「assertion（斷言）」，你需要從使用者那裡看到明確的線索，確認他們知道這些是什麼，才能在不解釋的情況下使用
- 如果不確定，可以簡短地解釋術語，並在需要時用簡短的定義澄清

---

## 建立技能

### 捕捉意圖

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

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

### 訪談與研究

主動詢問關於邊界情況、輸入/輸出格式、範例檔案、成功標準和相依性的問題。等到這部分釐清後再撰寫測試提示詞。

檢查可用的 MCP —— 如果對研究有用（搜尋文件、尋找類似技能、查找最佳實踐），如果有子代理可用則並行研究，否則在行內進行。準備好上下文以減輕使用者的負擔。

### 撰寫 SKILL.md

根據使用者訪談，填入以下組件：

- **name**：技能識別碼
- **description**：何時觸發、做什麼。這是主要的觸發機制 —— 包含技能做什麼以及使用它的具體情境。所有「何時使用」的資訊放在這裡，不在本文中。注意：目前 Claude 傾向於「觸發不足（undertrigger）」技能 —— 在技能有用時不使用它們。為了解決這個問題，請讓技能描述稍微「積極」一些。例如，不要寫「如何建立一個簡單快速的儀表板來顯示內部資料」，你可以寫「如何建立一個簡單快速的儀表板來顯示內部資料。請確保在使用者提到儀表板、資料視覺化、內部指標、或想要顯示任何類型的公司資料時使用此技能，即使他們沒有明確要求『儀表板』。」
- **compatibility**：所需工具、相依性（可選，很少需要）
- **技能的其餘內容 :)**

### 技能撰寫指南

#### 技能的結構

```
skill-name/
├── SKILL.md (必要)
│   ├── YAML frontmatter（name、description 為必要欄位）
│   └── Markdown 指令
└── 附帶資源 (可選)
    ├── scripts/    - 用於確定性/重複性任務的可執行程式碼
    ├── references/ - 按需載入上下文的文件
    └── assets/     - 用於輸出的檔案（範本、圖示、字型）
```

#### 漸進式披露 (Progressive Disclosure)

技能使用三層載入系統：
1. **元資料**（name + description）—— 始終在上下文中（約 100 字）
2. **SKILL.md 本文** —— 技能觸發時在上下文中（理想 <500 行）
3. **附帶資源** —— 按需載入（無限制，腳本可以在不載入的情況下執行）

這些字數是近似值，如果需要可以寫得更長。

**關鍵模式：**
- 將 SKILL.md 控制在 500 行以下；如果接近此限制，增加額外的層次結構以及關於模型使用技能後應該去哪裡跟進的清晰指引
- 從 SKILL.md 中清楚地引用檔案，並說明何時讀取它們
- 對於大型參考檔案（>300 行），包含目錄

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

#### 無意外原則

這不用多說，但技能不得包含惡意軟體、漏洞利用程式碼或任何可能危及系統安全的內容。如果被描述，技能的內容不應在其意圖上讓使用者感到意外。不要配合建立誤導性技能或旨在促進未經授權存取、資料外洩或其他惡意活動的技能的請求。不過像「角色扮演為 XYZ」之類的是可以的。

#### 撰寫模式

在指令中優先使用祈使語氣。

**定義輸出格式** —— 可以這樣做：
```markdown
## 報告結構
永遠使用這個確切的範本：
# [標題]
## 執行摘要
## 關鍵發現
## 建議
```

**範例模式** —— 包含範例很有用。可以這樣格式化（但如果範例中有「Input」和「Output」，你可能想要稍微偏離）：
```markdown
## 提交訊息格式
**範例 1：**
Input: Added user authentication with JWT tokens
Output: feat(auth): implement JWT-based authentication
```

### 撰寫風格

嘗試向模型解釋事情為什麼重要，而不是使用沉重的「必須」。運用心智理論，嘗試讓技能通用化，而不是過度針對特定範例。先寫一個草稿，然後用新鮮的眼光審視並改進。

### 測試案例

撰寫技能草稿後，想出 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": []
    }
  ]
}
```

完整 schema 請參見 `references/schemas.md`（包括 `assertions` 欄位，你稍後會添加）。

## 執行和評估測試案例

此部分是一個連續序列 —— 不要中途停止。不要使用 `/skill-test` 或任何其他測試技能。

將結果放在 `<skill-name>-workspace/` 中，作為技能目錄的同層目錄。在工作空間中，按迭代組織結果（`iteration-1/`、`iteration-2/` 等），每個測試案例都有一個目錄（`eval-0/`、`eval-1/` 等）。不要預先建立所有這些 —— 隨著進展建立目錄。

### 步驟 1：在同一回合中啟動所有執行（有技能 AND 基線）

對每個測試案例，在同一回合中啟動兩個子代理 —— 一個有技能，一個沒有。這很重要：不要先啟動有技能的執行，然後再回來做基線。同時啟動所有內容，這樣它們大約會同時完成。

**有技能的執行：**

```
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` 中的斷言。同時向使用者解釋他們將在檢視器中看到什麼 —— 質性輸出和量化基準測試。

### 步驟 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 期望值陣列必須使用 `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 版本放在其基線對應版本之前。

3. **進行分析師檢查** —— 讀取基準測試資料並發現彙總統計可能隱藏的模式。參見 `agents/analyzer.md`（「分析基準測試結果」部分）了解要尋找什麼 —— 例如無論技能如何都會通過的斷言（無鑑別力）、高變異的評估（可能不穩定）以及時間/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=$!
   ```
   對於第 2 次以上的迭代，同時傳入 `--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**（第 2 次以上迭代）：折疊區塊顯示上次迭代的輸出
- **Formal Grades**（如果有評分）：折疊區塊顯示斷言通過/失敗
- **Feedback**：一個文字方塊，輸入時自動儲存
- **Previous Feedback**（第 2 次以上迭代）：上次的評論，顯示在文字方塊下方

「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. **從回饋中概括。** 這裡發生的大局是我們正在嘗試建立可以被使用百萬次（也許真的，也許更多）跨許多不同提示詞的技能。這裡你和使用者只在少數幾個範例上反覆迭代，因為這有助於加快速度。使用者對這些範例瞭若指掌，評估新輸出很快。但如果你和使用者共同開發的技能只適用於那些範例，那就沒有用了。與其加入瑣碎的過擬合變更或壓迫性的限制性「必須」，如果有一些頑固的問題，你可以嘗試分支出去，使用不同的隱喻，或建議不同的工作模式。嘗試相對廉價，也許你會找到很棒的方法。

2. **保持提示精簡。** 移除沒有發揮作用的內容。確保閱讀執行記錄，而不只是最終輸出 —— 如果看起來技能讓模型浪費大量時間做沒有成效的事情，你可以嘗試去掉技能中導致這種行為的部分，看看會發生什麼。

3. **解釋原因。** 努力解釋你要求模型做的每件事背後的**原因**。當今的 LLM 非常*聰明*。它們有良好的心智理論，在給予好的框架時可以超越機械式指令，真正發揮作用。即使使用者的回饋簡短或沮喪，也要嘗試真正理解任務、理解使用者為什麼寫了他們寫的東西、他們實際上寫了什麼，然後將這種理解傳達到指令中。如果你發現自己在全大寫寫 ALWAYS 或 NEVER，或使用超級嚴格的結構，那是一個黃旗 —— 如果可能，重新框架並解釋原因，讓模型理解你要求的東西為什麼重要。這是一種更人性化、強大和有效的方法。

4. **尋找測試案例間的重複工作。** 閱讀測試執行的記錄，注意子代理是否都獨立撰寫了類似的輔助腳本或採取了相同的多步驟方法。如果所有 3 個測試案例都導致子代理撰寫 `create_docx.py` 或 `build_chart.py`，這是一個強烈的信號，表示技能應該附帶那個腳本。寫一次，放在 `scripts/` 中，並告訴技能使用它。這可以讓每次未來的調用不必重新發明輪子。

這個任務相當重要，你的思考時間不是瓶頸；花時間好好思考。我建議寫一個修訂草稿，然後用新鮮的眼光看它並做改進。真正盡力進入使用者的角度，理解他們想要和需要什麼。

### 迭代循環

改進技能後：

1. 將你的改進應用到技能
2. 重新執行所有測試案例到新的 `iteration-<N+1>/` 目錄，包括基線執行。如果你正在建立新技能，基線始終是 `without_skill`（沒有技能）—— 這在迭代間保持不變。如果你正在改進現有技能，根據判斷決定什麼作為基線最合理：使用者帶來的原始版本，還是前一次迭代。
3. 使用 `--previous-workspace` 指向前一次迭代來啟動審查器
4. 等待使用者審查並告訴你他們完成了
5. 讀取新的回饋，再次改進，重複

持續直到：
- 使用者說他們滿意了
- 回饋都是空的（一切看起來都好）
- 你沒有取得有意義的進展

---

## 進階：盲測比較

對於需要更嚴格比較兩個版本技能的情況（例如使用者問「新版本真的更好嗎？」），有一個盲測比較系統。閱讀 `agents/comparator.md` 和 `agents/analyzer.md` 了解詳情。基本概念是：將兩個輸出交給一個獨立代理，不告訴它哪個是哪個，讓它判斷品質。然後分析為什麼贏家勝出。

這是可選的，需要子代理，大多數使用者不需要它。人工審查循環通常就足夠了。

---

## 描述優化

SKILL.md frontmatter 中的 description 欄位是決定 Claude 是否調用技能的主要機制。建立或改進技能後，提議優化描述以獲得更好的觸發準確度。

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

建立 20 個評估查詢 —— 混合應觸發和不應觸發的。儲存為 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"`

對於**應觸發**的查詢（8-10 個），考慮覆蓋率。你想要同一意圖的不同措辭 —— 有些正式，有些隨意。包含使用者沒有明確命名技能或檔案類型但顯然需要它的情況。加入一些不常見的用例以及此技能與其他技能競爭但應該勝出的情況。

對於**不應觸發**的查詢（8-10 個），最有價值的是接近但不是的查詢 —— 與技能共享關鍵字或概念但實際上需要不同東西的查詢。想想相鄰領域、天真的關鍵字匹配會觸發但不應該的模糊措辭，以及查詢觸及技能所做的事情但在另一個工具更合適的情境中的情況。

要避免的關鍵事項：不要讓不應觸發的查詢明顯不相關。「Write a fibonacci function」作為 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`），檢查 Downloads 資料夾中最新的版本

這個步驟很重要 —— 不好的評估查詢會導致不好的描述。

### 步驟 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` 列表中，帶有其 name + description，Claude 根據該描述決定是否查閱技能。重要的是要知道 Claude 只會為它自己無法輕鬆處理的任務查閱技能 —— 簡單的一步查詢如「read this PDF」可能不會觸發技能，即使描述完美匹配，因為 Claude 可以用基本工具直接處理它們。複雜的、多步驟的或專門的查詢在描述匹配時會可靠地觸發技能。

這意味著你的評估查詢應該足夠實質性，讓 Claude 實際上會受益於查閱技能。簡單的查詢如「read file 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 沒有子代理，一些機制會改變。以下是需要調整的部分：

**執行測試案例**：沒有子代理意味著沒有並行執行。對每個測試案例，讀取技能的 SKILL.md，然後按照其指令完成測試提示。一次做一個。這不如獨立子代理嚴格（你寫了技能也在執行它，所以你有完整上下文），但這是有用的健全性檢查 —— 人工審查步驟會補償。跳過基線執行 —— 只使用技能完成請求的任務。

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

**基準測試**：跳過量化基準測試 —— 它依賴於基線比較，在沒有子代理時沒有意義。專注於使用者的質性回饋。

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

**描述優化**：此部分需要 `claude` CLI 工具（特別是 `claude -p`），僅在 Claude Code 中可用。如果在 Claude.ai 上則跳過。

**盲測比較**：需要子代理。跳過。

**打包**：`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 程式碼）。在你自己評估輸入之前生成評估檢視器。你要盡快把它們呈現給人類！
- 回饋的工作方式不同：因為沒有執行中的伺服器，檢視器的「Submit All Reviews」按鈕會將 `feedback.json` 作為檔案下載。然後你可以從那裡讀取（你可能需要先請求存取權限）。
- 打包可以運作 —— `package_skill.py` 只需要 Python 和檔案系統。
- 描述優化（`run_loop.py` / `run_eval.py`）在 Cowork 中應該可以正常工作，因為它使用 `claude -p` 透過 subprocess，不是瀏覽器，但請在你完全完成技能製作且使用者同意狀態良好後再進行。
- **更新現有技能**：使用者可能要求你更新現有技能。遵循上面 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 中，請特別將「建立評估 JSON 並執行 `eval-viewer/generate_review.py` 讓人類審查測試案例」放入你的 TodoList 以確保它發生。

祝好運！