技能創作者

技能創作者 是做什麼的？

一個用於建立新技能並反覆改進的技能。

在較高的層次上，建立技能的過程如下：

• 決定您希望技能做什麼以及大致上要怎麼做
• 撰寫技能草稿
• 建立一些測試提示，並對其執行有技能存取權限的 claude
• 幫助使用者定性和定量評估結果
  • 在背景執行程式的同時，如果尚未有定量評估（如果已有，則可以沿用或根據需要修改），請起草一些定量評估。然後向使用者解釋這些評估（或者如果已經存在，則解釋現有的那些）
  • 使用 eval-viewer/generate_review.py 腳本向使用者顯示結果供其查看，也讓他們查看定量指標
• 根據使用者評估結果的回饋（以及如果從定量基準中發現任何明顯缺陷時）改寫技能
• 重複直到滿意為止
• 擴展測試集並在更大規模上再次嘗試

使用此技能時，您的工作是判斷使用者處於此過程的哪個階段，然後介入並幫助他們推進這些階段。例如，他們可能會說「我想為 X 建立一個技能」。您可以幫助他們釐清意圖、撰寫草稿、撰寫測試案例、決定他們想要如何評估、執行所有提示，然後重複。

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

當然，您應該始終保持靈活性；如果使用者說「我不需要執行一堆評估，只要跟我一起感受一下」，您也可以這樣做。

然後，技能完成後（順序仍然可以靈活調整），您還可以執行技能描述改進器（我們有一個單獨的腳本），以最佳化技能的觸發條件。

酷嗎？很酷。

與使用者溝通

技能創作者的使用者可能來自各種對程式碼術語的熟悉程度。如果您還沒聽說過（但您怎麼可能聽說呢，這是最近才開始的），現在有一個趨勢是 Claude 的力量正激勵水電工打開他們的終端機，父母和祖父母則在 Google「如何安裝 npm」。另一方面，大多數使用者可能具備相當的電腦素養。

所以請注意上下文線索，以了解如何措辭！在預設情況下，給您一些概念：

• 「評估」和「基準」還算可以，但使用前應確認
• 對於「JSON」和「斷言」，您需要看到使用者對這些東西有一定了解的明確線索，才能不加解釋地使用

如果不確定，短暫解釋一下術語是可以的；如果您不確定使用者是否會懂，請隨意用簡短的定義澄清術語。

---

建立技能

捕捉意圖

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

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

訪談與研究

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

檢查可用的 MCP——如果對研究有用（搜尋文件、尋找類似技能、查詢最佳實踐），請透過子代理並行研究（如果可用），否則內聯進行。帶著上下文來減少使用者的負擔。

撰寫 SKILL.md

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

• name：技能識別碼
• description：何時觸發、做什麼。這是主要的觸發機制——同時包含技能做什麼以及何時使用的特定上下文。所有「何時使用」的資訊都在這裡，而不是在主體中。注意：目前 Claude 有「低觸發」技能的傾向——即在技能有用時不使用它們。為了對抗這一點，請讓技能描述稍微「有推動力」。例如，不寫「如何建立一個簡單快速的儀表板來顯示內部 Anthropic 資料。」，而是寫「如何建立一個簡單快速的儀表板來顯示內部 Anthropic 資料。確保每當使用者提及儀表板、資料視覺化、內部指標或想要顯示任何類型的公司資料時，都使用此技能，即使他們沒有明確要求『儀表板』。」
• compatibility：所需的工具、依賴關係（可選，很少需要）
• **技能的其餘部分 :) **

技能寫作指南

技能的結構

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

漸進式揭露

技能使用三層級載入系統：

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」之類的內容是可以的。

寫作模式

在指令中偏好使用祈使句。

定義輸出格式 - 您可以這樣做：

## 報告結構
始終使用這個確切的範本：
# [標題]
## 摘要
## 主要發現
## 建議

範例模式 - 包含範例很有用。您可以這樣格式化它們（但如果範例中有「輸入」和「輸出」，您可能需要稍微偏離）：

## 提交訊息格式
**範例 1：**
輸入：Added user authentication with JWT tokens
輸出：feat(auth): implement JWT-based authentication

寫作風格

嘗試向模型解釋為什麼事情很重要，而不是使用強制性的 MUST。使用同理心，並嘗試使技能具有通用性，而不是特別狹隘地針對特定範例。先起草一個草稿，然後以全新的眼光審視並改進它。

測試案例

在撰寫技能草稿後，想出 2-3 個逼真的測試提示——實際使用者通常會說的那種。與使用者分享：[您不必使用完全相同的語言]「這裡有幾個我想嘗試的測試案例。這些看起來對嗎，或者您想添加更多？」然後執行它們。

將測試案例儲存到 evals/evals.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：在同一回合中產生所有執行（有技能 AND 基準）

對於每個測試案例，在同一回合中產生兩個子代理——一個有技能，一個沒有。這一點很重要：不要先產生有技能的執行，然後再回來進行基準執行。同時啟動所有執行，以便它們大約同時完成。

有技能執行：

執行此任務：
- 技能路徑：<path-to-skill>
- 任務：<eval prompt>
- 輸入檔案：<eval files if any, or "none">
- 將輸出儲存到：<workspace>/iteration-<N>/eval-<ID>/with_skill/outputs/
- 要儲存的輸出：<使用者關心的內容——例如「.docx 檔案」、「最終 CSV」>

基準執行（相同提示，但基準取決於上下文）：

• 建立新技能：完全沒有技能。相同的提示，沒有技能路徑，儲存到 without_skill/outputs/。
• 改善現有技能：舊版本。在編輯之前，快照技能（cp -r <skill-path> <workspace>/skill-snapshot/），然後將基準子代理指向快照。儲存到 old_skill/outputs/。

為每個測試案例編寫一個 eval_metadata.json（斷言目前可以為空）。根據測試的內容為每個評估命名——而不僅僅是 "eval-0"。也將此名稱用於目錄。如果此迭代使用新的或修改過的評估提示，請為每個新的評估目錄建立這些檔案——不要假設它們從之前的迭代繼承。

{
  "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：

{
  "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. 彙總成基準——從技能創建者目錄執行彙總腳本：

   python -m scripts.aggregate_benchmark <workspace>/iteration-N --skill-name <name>
   

   這會產生 benchmark.json 和 benchmark.md，其中包含每個配置的通過率、時間和 token，並附有平均值 ± 標準差和差異。如果手動生成 benchmark.json，請參閱 references/schemas.md 以了解檢視器期望的確切結構。 將每個 with_skill 版本放在其基準對應項之前。

3. 進行分析師遍歷——讀取基準資料並找出彙總統計資料可能隱藏的模式。請參閱 agents/analyzer.md（「分析基準結果」部分）以了解要尋找的內容——例如始終通過的斷言（非鑑別性）、高變異性評估（可能不穩定）以及時間/token 的取捨。

4. 啟動檢視器，同時顯示質化輸出和定量資料：

   nohup python <skill-creator-path>/eval-viewer/generate_review.py
   

…

[為翻譯而截斷]