Elites Skills Architect

將一個粗略的想法轉化為一個能正常運作的技能：探索、規格化、驗證、測試執行、人工審查、描述調優和打包。關於一個技能的每一項宣稱，都必須有腳本或評分執行的支持，而不是憑直覺看過就覺得滿意。

從哪裡開始

八個階段。找到用戶目前所在的階段，然後從那裡開始：

探索：獲得具體問題和撰寫規格所需的事實
標記問題：太簡單、太廣泛、重疊、矛盾
分類：文件建立、工作流程自動化或 MCP 增強
構建與驗證：frontmatter、本體、資料夾、評估、scripts/validate_spec.py
測試與審查：執行評估，顯示輸出，評分，壓力測試技能強制執行的任何規則
改進：修正反饋背後的根本模式，而不是單一案例
描述調優：觸發測試與 scripts/optimize_description.py
打包：scripts/package_skill.py

根據用戶調整你的步調。對於主動說出 "MCP server" 和 "frontmatter" 的人，給他們速度。對於說 "我想讓 Claude 處理我的發票" 的人，則需要逐步引導，一次一個問題。使用簡單明瞭的語言，不要使用他們沒有先使用的術語。

所有腳本都使用標準庫的 Python 3.9 或更新版本，從技能根目錄執行：

cd <path-to-elites-skills-architect>
python3 scripts/validate_spec.py <skill-folder>

階段 1：探索

閱讀 references/discovery-questions.md 以獲取問題庫以及針對薄弱答案的後續問題。每次提出兩到三個問題，建立在答案之上，切勿一次列出所有問題。

第一批，問題：該技能必須產出的一個主要成果；使用者實際會說的 5 到 10 個短語；該技能不應該處理的事項。
第二批，資料：輸入及其格式；使用者成功運作時所擁有的資料；輸入常出錯的地方。
第三批，工作流程：步驟順序；依賴關係；if/then 路徑；當第三步驟失敗時，第一和第二步驟會發生什麼事。
第四批，整合：MCP 伺服器、API、Claude 內建功能、驗證和速率限制。
第五批，彈性：最可能發生的三個執行時期失敗；完全失敗時的訊息。

當你可以在不需要猜測的情況下完成以下四件事時，就停止提問：用真實的觸發短語撰寫描述，按順序列出每個步驟，命名三個失敗模式及其處理方式，並將技能解釋得足夠清楚，讓另一位開發者可以構建它。

如果用戶已經將知識寫下（手冊、API 文件、風格指南、儲存的網頁），請匯入它，而不是重新輸入：

python3 scripts/import_sources.py <files-or-folders> --skill <skill-folder> --dry-run

它會將 Markdown、純文字和儲存的 HTML 轉換為參考檔案，在標題處拆分長文件，在旁邊寫一個 sources-index.md，並列印出要放入本體的 "read X when Y" 行。它絕不下載任何內容；請先儲存網頁。

階段 2：在構建之前先標記問題

太簡單：Claude 已經能做到。一個技能只有在每次都需要領域邏輯或強制執行某種格式時，才有其存在的價值。詢問是否存在這樣的需求。
太廣泛：包含數個不相關的工作流程。建議拆分；小的技能觸發更可靠。詢問哪一個優先處理。
重疊：接近 docx、pptx、xlsx、pdf 或前端設計。說出來，並詢問是要擴展還是要構建不同的東西。
不可能或不安全：直接說出來，並提供最接近的可行版本。
矛盾：之前說 "全自動"，現在說 "先問我"。在撰寫任何程式碼之前先解決這個矛盾。

階段 3：分類

閱讀 references/categories-and-patterns.md。選擇一個：

類別 1，文件和資產建立：使用 Claude 內建功能建立檔案。探索批次 1 和 2 就足夠了。
類別 2，工作流程自動化：跨工具的順序步驟、驗證關卡、部分失敗或回滾。需要所有五個批次。
類別 3，MCP 增強：用判斷和預設值包裝現有的 MCP 伺服器。需要批次 1、2 和 4。

告訴用戶分類及其原因。混合分類也可以；為描述和資料夾結構選擇主要的那個。

階段 4：構建和驗證

在生成任何內容之前，先閱讀一次 references/worked-example.md，以便你的輸出與該範例的詳細程度相匹配。使用 references/spec-output-template.md 作為骨架。

4a：Frontmatter

閱讀 references/yaml-rules.md。驗證器會檢查的項目（除非另有標記，否則視為錯誤）：

name：kebab-case，不含 "claude" 或 "anthropic"；與資料夾名稱相符（警告，使用 --portable 時為錯誤）
description：1 到 1024 個字元；動作動詞、它建立什麼、何時使用、3 到 8 個用雙引號括起來的觸發短語、一個否定範圍（長度是錯誤；動詞、短語和否定範圍是警告）
無角括號、定位點、智慧型引號或連字號以外的破折號
描述中無撇號（警告；某些上傳解析器曾拒絕它們）
tags 為一個字串，tags: "a, b, c"，切勿使用 [a, b, c]（警告）；對看起來像數字的中繼資料值使用引號，version: "1.0"

讓描述具有強烈的提示性。在我們的測試中，Claude 不使用的次數多於錯誤選用的次數，所以為間接請求添加 "also triggers when someone mentions ..."。

4b：本體

最多 500 行，使用命令式語氣，並且解釋為什麼，而不只是做什麼。順序：一句話說明目的；何時使用和何時不使用；帶有每一步檢查的編號步驟；兩到三個範例（短語、動作、結果）；錯誤處理（含原因和回應）；簡短的最佳實踐。將任何較大的內容移到 references/ 中，並使用 "read X when Y" 來指向它。

4c：資料夾

skill-name/
  SKILL.md
  evals/evals.json        測試案例，請參閱 references/schemas.md
  scripts/                模型不應重新推導的確定性邏輯
  references/             按需載入的深度材料
  assets/                 模板和範例

技能資料夾內部沒有 README.md；文件存放在 SKILL.md 和 references/ 中。

4d：測試計劃和評估

撰寫 5 個或更多應觸發的查詢和 5 個或更多不應觸發的查詢。好的查詢是具體的，聽起來像真人會說的："ok kicking off the checkout redesign monday, set up the sprint in Linear, 2 weeks, frontend team"。最好的負面查詢與正面查詢共享詞彙，但想要其他的東西：建議而不是行動，報告而不是建立。

將 2 或 3 個評估寫入 evals/evals.json（格式請參閱 references/schemas.md）。每個期望是一個可供檢查的句子。在執行任何操作之前先向用戶展示它們。

4e：驗證

python3 scripts/validate_spec.py <skill-folder>
python3 scripts/validate_spec.py <skill-folder> --json     # 供工具使用
python3 scripts/validate_spec.py <skill-folder> --strict   # 警告也視為失敗
python3 scripts/validate_spec.py <skill-folder> --portable # 供 Claude 以外的代理使用

它會檢查 frontmatter 規則、本體長度、上述章節、遺留的佔位符、evals.json、存在的 pressure-evals.json，以及本體中提到的每個 scripts/... 或 references/... 路徑是否都存在。修正每個錯誤。絕不顯示驗證失敗的規格。--portable 會添加開放代理技能規範規則（資料夾名稱必須相符，中繼資料值必須為文字），適用於也將在其他代理中執行的技能。

階段 5：測試和審查

一個連續的序列；不要中途停止。

5a：執行評估

工作區佈局（完整樹狀結構請參閱 references/schemas.md）：

<skill-name>-workspace/iteration-1/eval-<id>/<configuration>/run-<k>/outputs/

將 eval_metadata.json 寫入每個 eval-<id>/ 資料夾。然後執行每個評估：

使用子代理（Claude Code, Cowork）：在同一個回合中啟動每個評估的「有技能」和「無技能」執行。每個執行器讀取技能、處理提示詞、將檔案儲存到 outputs/、為任何不確定的內容寫入 outputs/user_notes.md 以及 outputs/metrics.json。立即從任務通知中儲存 timing.json；這些數字不會保存在其他地方。
不使用子代理（claude.ai）：自行閱讀 SKILL.md 並逐一執行每個提示詞，將結果放入相同的資料夾中。

5b：在執行進行時草擬斷言

將可衡量的期望添加到 eval_metadata.json 和 evals/evals.json 中。用一句話向用戶解釋每個期望。跳過關於品味的斷言；這由人類來判斷。

5c：在判斷輸出之前先顯示它們

python3 eval-viewer/review.py <skill-name>-workspace/iteration-1 --skill-name <name>

頁面在瀏覽器中打開，可離線工作，並在用戶輸入時將反饋儲存到工作區的 feedback.json 中。在 Cowork 中，或者當無法使用伺服器時，添加 --static review.html；然後反饋會以檔案形式下載。先打開檢視器，然後你自己再看輸出。在用戶做出反應之前，不要修改技能。

5d：評分和基準測試（子代理）

使用 agents/grader.md 對每次執行進行評分。盡可能使用與執行評估不同的模型；模型很難公正地評判自己的工作。

聚合：

python3 scripts/aggregate_benchmark.py <skill-name>-workspace/iteration-1 --skill-name <name>

使用 --benchmark <iteration>/benchmark.json 重新打開檢視器以查看基準測試標籤頁。對於平均數無法顯示的模式，執行 agents/analyzer.md 的工作 2。

5e：壓力測試（強制執行規則的技能）

當技能的價值在於必須維持的規則（一種格式、一個檢查、一個批准步驟）時，請閱讀 references/pressure-tests.md 並將 3 到 5 個情境寫入 evals/pressure-evals.json：一個具體情況、兩個或多個壓力（截止日期、老闆、客戶要求、已經花費的時間），以及一個包含誘人妥協方案的強迫選擇。

python3 scripts/pressure_eval.py --skill-path <skill-folder> \
  --scenarios <skill-folder>/evals/pressure-evals.json --runs 3 --model <model-id> \
  --output <skill-name>-workspace/pressure-results.json \
  --report <skill-name>-workspace/pressure-report.md --dry-run

在用戶批准呼叫次數後，移除 --dry-run。每個情境都在「無技能」和「有技能」的情況下執行。"skill does not hold" 表示報告中包含了 Claude 給出的藉口：在技能中反駁每一個藉口（點名、說明為什麼是錯的、該怎麼做），然後重新執行。"passes, but the baseline passes too" 表示該情境太簡單，無法證明任何事情。

階段 6：改進

找到反饋背後的根本模式並修正它；三個測試提示詞並不能代表全部。閱讀對話記錄，而不僅僅是輸出，並刪除導致模型浪費步驟的指令。如果你在撰寫全大寫的 ALWAYS 或 NEVER，請停下來，改為解釋原因；一個理解原因的模型會比一個只記住規則的模型走得更遠。當每次執行都寫了相同的輔助函式時，將其放入 scripts/ 中並說明原因。小心那些能通過三個評估但除此之外什麼也做不了的技能。

然後：應用變更，將所有評估重新執行到 iteration-2/，使用 --previous-workspace iteration-1 打開檢視器，以便用戶可以並排查看新舊結果，閱讀反饋，然後重複。當用戶滿意、反饋為空或進度停滯時停止。

對於嚴格的「新 vs 舊」比較，請使用 agents/comparator.md（一個帶有交換檢查的盲測 A/B 評審），然後使用 agents/analyzer.md 的工作 1 來解釋結果。這是可選的；審查循環通常就足夠了。

階段 7：描述調優

描述是讓 Claude 選擇技能的關鍵。一旦技能本身能正常運作，就開始調優它。

7a：觸發查詢

將 20 個查詢寫入 evals/trigger-evals.json：大約一半應觸發，一半不應觸發。包括口語對話、檔案名稱、個人背景。有價值的負面查詢是那些接近觸發但意圖不同的。向用戶顯示列表，並更改他們要求更改的內容；糟糕的查詢會產生糟糕的描述。

7b：在花費之前先計數

python3 scripts/trigger_eval.py --skill-path <skill-folder> --eval-set <skill-folder>/evals/trigger-evals.json --dry-run

每次執行都是一個 claude -p 呼叫。告訴用戶數量並獲得同意。

7c：衡量

python3 scripts/trigger_eval.py --skill-path <skill-folder> \
  --eval-set <skill-folder>/evals/trigger-evals.json \
  --runs-per-query 3 --workers 4 --model <model-id> \
  --output <skill-name>-workspace/trigger-results.json --verbose

該腳本會將技能安裝到一個臨時專案中，並僅使用該專案的設定在那裡執行 Claude，因此不會影響用戶的真實專案，也不會受到其他技能的干擾。閱讀摘要：錯過的查詢（假陰性）表示描述太狹隘；錯誤觸發的查詢（假陽性）表示描述太寬泛。所有執行都報錯的查詢會報告為未知，絕不會視為通過。

7d：最佳化（僅限 Claude Code）

python3 scripts/optimize_description.py --skill-path <skill-folder> \
  --eval-set <skill-folder>/evals/trigger-evals.json --model <model-id> \
  --max-iterations 4 --results-dir <skill-name>-workspace/description-runs --verbose

它將查詢一次拆分為訓練集和留出集，進行評估，僅使用訓練失敗來要求 Claude 提供更好的描述，使用與 validate_spec.py 相同的規則驗證候選描述，然後重複。獲勝者是訓練得分最高的迭代；得分相同時，文字較短的勝出。留出得分會被報告，但從不用於選擇，因此它作為一個誠實的檢查：如果它遠低於訓練得分，則說明描述過度擬合於訓練查詢。它會寫入 results.json、report.md 和 best-description.txt，並且僅在獲勝者通過所有訓練查詢時才以退出碼 0 結束。在 claude.ai 上，請閱讀失敗案例並手動重寫。

7e：套用

將獲勝者貼到 SKILL.md 中，向用戶顯示帶有分數的前後對比，然後再次執行 scripts/validate_spec.py。

階段 8：打包

python3 scripts/package_skill.py <skill-folder> --output dist/
python3 scripts/package_skill.py --inspect dist/<skill-name>.skill

打包會先驗證，並在遇到錯誤時拒絕打包（預設情況下，遇到警告也拒絕，除非使用 --allow-warnings）。該存檔是可重現的，並會印出 SHA-256。將路徑或檔案本身提供給用戶。

...

elitesalgorithm/elites-skills-architect

elites-skills-architect 是什麼？

在你喜歡的 AI 中提問

說明文件