e9tgldr/skill-router

Skill 路由器

此處安裝了大約 170 個技能，它們在品質和範圍上差異極大， 其中幾個彼此相似（三個獨立的「讓它看起來不通用」設計技能、兩個 impeccable 副本、 xlsx 旁邊還有 xlsx-dsh）。選錯技能是代價最高的錯誤：錯誤的技能會浪費整個上下文， 並使答案偏離目標；反之，不使用技能通常比用錯技能更好。

因此：先路由，再工作。這個檔案就是路由程序。它成本很低——一次檔案掃描，一或兩次工具呼叫—— 取代了從技能列表中猜測。此程序是安裝不可知的：以下描述的數量、名稱和家族寫的正是它所針對的目錄， 而搜尋功能會規範化到它找到的任何目錄。

1. 在接觸任何東西之前，先閱讀任務

在心中默默回答這些問題，每題一行。它們決定路由，而非交付物。

• 產出什麼？ 檔案 (docx/xlsx/pdf/pptx/png)、執行中的程式碼、一個決策、一則訊息、一個計畫。
• 領域是什麼？ 網頁前端、後端、資料、文件、設計、影片/動畫、VR、維運。
• 有現有的成品嗎？ 從無到有 vs 修改他人程式碼——這會使路由從「建構技能」轉向「審計/審查」與「先理解」的技能。
• 誰會讀取輸出？ 投資人、老師、團隊成員、編譯器。受眾會改變寫作技能，而不是技術技能。

如果請求只是一個意圖的句子（「幫我做個酷東西」），那也是一個路由訊號：意味著目前無法選擇任何技能， 且問題要先問（步驟 6）。

2. 快速路徑——檢查路由表

讀取 references/task-types.md（相對於此技能目錄）。第一個表格將約 40 種常見任務形狀映射到一個畫面的驗證技能鏈； 第二個表格列出具有難以猜測名稱的狹義工具（animation-vocabulary、cdn-caching、vercel-connect）， 這些名稱無人會搜尋，所以在下結論前請先檢查。

• 找到匹配 → 使用該鏈繼續步驟 4。不要同時搜尋；表格就是答案，再次搜尋只是浪費 token。
• 無匹配，或匹配不完全 → 步驟 3。
• 表格中列出的技能你沒有（不同的安裝、不同的 harness、全新的機器）→ 完全跳過表格，前往步驟 3。 表格是單一安裝的映射；搜尋功能適用於任何目錄。用 --doctor 驗證。

3. 搜尋目錄

一個命令，不需要模型：

# 路徑相對於此技能目錄
node scripts/find_skills.mjs "landing page feels generic" -n 8
node scripts/find_skills.mjs --doctor      # 掃描了哪些根目錄，找到了什麼

它會根據名稱 + 描述（使用 IDF 加權，因此罕見詞比 user/code/when 更重要）以及一個策展的概念層， 對所有已安裝技能進行評分——概念層用於那些與所需技能沒有共同詞彙的措辭。它會印出頂級匹配結果及其 SKILL.md 路徑， 如果沒有合適的匹配則印出 NO GOOD MATCH。

如何良好地查詢：

• 使用任務的名詞，而非使用者的句子：spreadsheet charts csv，而不是「你能不能把這個變成有圖表的東西」。
• 執行 2–3 個不同角度，而不是一個長查詢——成品角度 (pitch deck)、領域角度 (investor fundraising)、問題角度 (text looks templated)。 如果需要，可以用一個 bash 呼叫批次處理。
• --explain 會印出每個結果的排名原因，逐個 token 解釋——當結果看起來錯誤時使用它，而不是猜測原因。
• 每個結果都會標記為 [strong]、[likely] 或 [weak]。[weak] 表示路由器是從一個偶然的詞彙猜測的——將其視為建議，而非答案，並優先使用你自己的判斷。如果所有結果都是 weak，腳本會明確說明。
• --all 會傾印整個目錄，--name pdf 會將一個名稱解析為路徑，--json 給出機器可讀的輸出，-n 20 會擴展列表，當你想看到候選者時很有用（對於措辭不佳的查詢，正確答案通常是第 4 個）。
• 結果是排名，而非權威性的。你仍然需要選擇。
• 腳本存在於此技能的 scripts/ 目錄中。如果 harness 公開了絕對路徑，使用它；否則先 cd 到技能目錄。
• 它會索引任何存在的東西，而不是固定的列表：它會掃描各個 harness 常見的每個使用者和每個專案的技能目錄（~/.pi、~/.claude、~/.codex、 ~/.agents、~/.cursor，加上 <cwd>/skills 和 plugin node_modules）。可以用 SKILL_ROUTER_ROOTS=/a/skills:/b/skills 或 --root /a/skills 指向任何其他地方。 在陌生的機器上，先執行 --doctor：它會列出每個根目錄、是否存在、貢獻了多少技能、重複的名稱以及無法解析的 SKILL.md 檔案。 對於新的目錄，不需要任何概念或門檻——它們是選擇性的加分項，位於詞彙排名之上；即使沒有任何概念，搜尋仍然會根據名稱和描述進行排名。

如果腳本本身不可用，或搜尋連續兩次沒有返回合理的結果，則回退到從系統提示詞列表中讀取 ~/.pi/agent/skills/ 的描述。不要停滯，也不要打開五個 SKILL.md 檔案希望能找到一個對的。

4. 選擇——保持鏈簡短的原則

1. 流程優先於實作。 設定工作方式的技能（腦力激盪、撰寫計畫、系統性除錯、測試驅動開發、寫作技能）應先載入，然後才是設定輸出外觀的技能（設計、docx、nextjs）。 流程技能通常會指示你下一步載入實作技能——讓它們這麼做。

2. 最多三個技能。 一個是正常的，兩個是常見的，三個是上限。第四個意味著你只是在收集而非決定。

3. 同一家族只選一個。 永遠不要載入同一家族的兩個成員——選取第一個欄位：

   家族	選擇一個
   前端品味 / 反通用	design-taste-frontend、ui-craft、impeccable、frontend-design、craft
   重複副本	impeccable (agents/) 優於 impeccable-dsh；xlsx 優於 xlsx-dsh；kimi/* 優於 dsh/*，除非 dsh 的明顯更特定
   文件格式	嚴格匹配檔案類型：docx、pdf、pptx、xlsx
   動態	animate (網頁)、animate-expo (React Native) — 不能同時使用
   後端	backend-patterns、create-a-backend、api-design — 最多兩個
   Quest / VR	hz-* 家族 + metavr-cli；始終以 hz-quest-verify-first 開始

4. 尊重平台門檻。 hz-*、portal、metavr-cli 需要 Quest/VR 上下文； cloudbase 需要 CloudBase；kimi-webbridge / kimi-cu 需要真實的瀏覽器或桌面 GUI。 如果任務沒有指明平台，則無論詞彙匹配得多好，該技能都不適用。

5. 證明或拒絕。 對於每個候選者，用一個從句說明：為什麼選這個。如果從句是「它提到了相同的詞彙」，則拒絕它。兩個技能可以共享詞彙但仍然用於不同的機器。

6. 「沒有」也是一個有效答案。 如果沒有任何東西通過門檻，用幾句話說明，然後用自己的判斷完成任務。缺少技能不是啟動一個半相關技能的理由。

7. 僅在任務轉向時重新路由。 同一工作流程內的新子任務不會觸發新的搜尋。領域的改變（使用者說「其實把它做成一個簡報」）則會觸發。

5. 用一行宣告，然後繼續

在開始工作前，陳述一次路由：

使用 design-taste-frontend (反模板的登陸頁面) → 對英雄區域使用 animate。 文案部分沒有技能適用；我自己來寫。

那一行的規則：一或兩個句子，只包含名稱和理由。不要寫關於技能庫的文章，不要寫「我為此任務選擇了以下技能，因為…」。使用者想看的是決策，而不是討論過程。 如果路由不常見，或者你有意偏離表格，這才是值得多加一個從句的事。

6. 只詢問真正阻礙工作的問題

這是路由器真正發揮作用的地方：一個被選中的技能會告訴你需要知道什麼，所以只問那些問題——而且只問那些。

僅在以下情況提問：

• 任務有兩個或更多真正不同的交付物（「一張海報」可能是 PNG 或投影片，且檔案不同），
• 受眾或格式未知且從上下文無法猜測，
• 所選技能自身的指令要求使用者必須擁有的決策（品牌、預算、憑證、真實資料 vs 模擬資料），
• 路由會花費真錢或影響生產環境。

不要問：

• 該用哪個技能——這是本技能的工作。問關於結果的問題，讓路由從答案中跟進，
• 任何請求已經回答過的內容、程式碼庫或檔案已經回答的內容，
• 任何合理預設值可以涵蓋的內容。選擇預設值，在宣告行中說明你選擇了哪個預設值，然後繼續進行。 這個使用者偏好長時間不間斷的執行，而不是逐輪確認。

形式：一次 ask_user_question 呼叫，最多 3 個問題，每個問題 2–4 個選項，推薦選項放在前面並標記為 "(Recommended)"， 每個選項用一個短句說明它會承諾什麼。永遠不要在第一個問卷之後馬上堆疊第二個問卷；如果一個答案引出了新問題，優先選擇合理的預設值，而不是再來一輪。

如果你載入的技能本身有自己的探索或提問階段（大多數設計和規劃技能都有），執行那個階段，而不是自己發明。連續兩輪提問會讓使用者覺得你在拖延。

7. 載入並執行

• 使用 read 工具完整閱讀 SKILL.md，路徑為搜尋返回的路徑。略讀的技能會產生略讀的輸出。

• 將任何 references/、scripts/、assets/ 路徑解析為相對於該技能目錄的路徑——搜尋輸出會印出檔案，所以上層目錄就是技能根目錄。

• 按原樣執行腳本。如果腳本需要一個它未記錄的參數，請說明，而不是自行實作。

• 技能優先。 一旦載入，它的指令會覆蓋此檔案中關於如何完成工作的意見，並覆蓋通用最佳實踐。這個檔案只是選擇了它。

• 如果載入的技能開頭是「先問使用者」或「在寫程式碼前先規劃」，請執行該步驟——路由到一個流程技能然後跳過它的流程，比完全不路由更糟。

• 如果在工作過程中你發現技能是錯的，請明確說明並重新路由（步驟 4）。悄悄地繞過一個錯誤的技能是失敗模式。

• 記錄修正，這樣就不會重複犯同樣的錯誤：

  node scripts/find_skills.mjs --learn "<那個失敗的措辭>" <正確技能>
  node scripts/find_skills.mjs --wrong "<那個失敗的措辭>" <錯誤技能>
  

  每當使用者拒絕一個路由、載入的技能被發現是錯誤的工具，或者你因為搜尋遺漏而需要手動路由時，都執行此操作。 學習到的修正會在未來類似的查詢中優先於詞彙分數，並且它們會隨安裝一起遷移——這就是路由器在它從未見過的環境中變得更好的方式。

8. 結尾

在結尾用一行說明：使用了哪些技能，以及成品在哪裡。然後停止——不要總結技能內容，不要提供解釋路由的提議。

維護——在不破壞路由器的情況下進行修改

路由器是基於評分的，而不是基於感覺。scripts/eval_routing.mjs 包含 80 個真實查詢，每個查詢都有一組真正可接受的技能答案，以及十幾個門檻案例（泛 React 查詢絕不能出現 Quest 技能）。在任何更改前後執行它：

node scripts/eval_routing.mjs
# score: 80/80 (100.0%)  gate leaks: 0
node ... --verbose      # 每個案例的排名
node ... quest          # 只匹配的案例

node scripts/smoke_portable.mjs   # 外部目錄 + 學習 + 600 技能規模

smoke_portable.mjs 是可移植性測試：它會在路由器從未見過的領域中發明 16 個技能（Kubernetes、Rust、Salesforce、Terraform…），測試排名、改述穩健性、可移植門檻、學習、重複名稱、空目錄、路徑包含空格、SKILL_ROUTER_ROOTS，以及 600 技能規模的運行。如果你更改了評分，兩個套件都必須保持綠色——eval 保證已知目錄的品質，smoke 保證未知目錄的行為。

一個提高分數的更改是改進；一個降低分數的更改是回歸，無論程式碼看起來多麼整潔。預期技能未安裝的案例會被跳過，而不是失敗，因此套件可以在任何機器上運行。

當一個真實任務路由不良時，在能解釋問題的最便宜層級進行修復：

1. 相同概念但使用錯誤詞彙 → 在 find_skills.mjs 中添加一個策展的 CONCEPTS 規則（when 正規表達式 → boost 分數，可選的 unless 否決和 demote 扣分）。 這是用於意圖與技能沒有共同詞彙的層級：「模糊的想法，沒有規格」→ brainstorming。 一次性問題？ 不要使用這個——改用 --learn 記錄它。CONCEPTS 是為了通用行為；記憶體是為了「這個措辭，這個技能」。
2. 一個重複出現的任務形狀 → 在 references/task-types.md 中添加一行。查詢時不花費任何成本，而且快速路徑完全跳過搜尋。
3. 一個技能持續輸給嘈雜的鄰居 → 將其添加到 DEMOTE，或者讓嘈雜的鄰居在概念中有一個 demote（例如，僅 dashboard 不得擊敗帶有 ui-craft-dense-dashboard 的 ui-craft）。
4. 一個平台技能洩漏到通用查詢中 → 使用必須存在的詞彙擴展 GATES，使其合格。
5. 使用者修正過的路由 → 使用 --learn / --wrong，然後繼續。偶爾檢查 --memory：如果同一個技能因為同一種措辭而不斷被修正，請將模式提升到 CONCEPTS 中，並 --forget 那些條目。

首先將失敗的查詢添加到 CASES，觀察它失敗，然後修復。不要針對你沒有寫下來的查詢調整評分——這會導致路由器在你的範例上表現良好，但在使用者的範例上表現糟糕。

紅旗——你在合理化，停下來

想法	現實
「這很簡單，不需要路由」	快速路由，快速實作。快速路徑的設計就是為了這個——使用它。
「我可以載入這兩個相似的設計技能」	同一家族只能選一個。選擇其中一個，或者如果都不合適，兩個都不要。
「這個頂尖結果是弱匹配，但它的名字看起來對」	弱匹配意味著路由器在猜測。你的判斷優於弱結果。
「我只需要一個額外的技能來處理這個子任務」	子任務不會觸發重新路由。如果它是一個新的領域，是的——但通常它不是。
「這個腳本失敗了，所以我會用 Python 重寫它的邏輯」	報告失敗。不要用隨意實現的路由搜尋取代經過評估的路由搜尋。
「使用者問了問題，所以我必須回答」	使用者詢問路由。在回答之前，先描述路由。讓使用者確認，而不是從問題開始。
「這只是維護任務，不需要路由」	每次更改程式碼都是引入錯誤的機會。如果它觸及程式碼，它就能從路由中受益。

---

路由器 scripts/ 目錄中的所有腳本都應被視為可執行檔案，而不是需要解釋的文件。請按原樣運行它們。