更好的技能產生器 (better-skill-gen) 是做什麼的？
此技能扮演元技能 (Meta-Skill)：接收使用者的想法、問題或工作流程，與使用者共同確定設計，然後為每個選定的供應商生成完整的技能目錄：
| 供應商 | 目錄 (專案範圍) | 特點 |
|---|---|---|
| Codex 與 Antigravity | .agents/skills/<skill-name>/ (共用版本) | 僅有 name、description；Codex 額外包含 agents/openai.yaml 設定技能呼叫策略 |
| Claude Code | .claude/skills/<skill-name>/ | 包含更多擴展的前置欄位，請參閱 references/frontmatter-spec.md |
此檔案適用於 Codex 與 Antigravity。所有 scripts/...、references/... 路徑均相對於本 SKILL.md 所在目錄。「執行命令」表示使用目前所使用供應商的 shell 命令執行工具（例如 Antigravity 的 run_command）。
1. 核心設計原則
- 三層 Progressive Disclosure 架構：
- 第 1 層：中繼資料 (啟動時載入)： YAML 前置欄位中的
name、description。消耗極少 token；description保持在 1,536 字元以下。 - 第 2 層：指令 (技能啟動時載入)：
SKILL.md主體，必須少於 500 行。僅包含工作流程、核心原則與限制。 - 第 3 層：資源 (實際需要時載入)：
templates/(結果範本)、examples/(黃金標準範例文字)、references/(技術規格)、scripts/(用於處理繁重工作而不耗費上下文的 bash/python 程式碼)。
- 第 1 層：中繼資料 (啟動時載入)： YAML 前置欄位中的
- 技能目的分類：
- 參考技能： 程式碼慣例、系統知識、設計模式，供代理作為背景知識應用。
- 任務技能： 逐步執行動作的流程。具有副作用的工作（部署、提交、刪除資料）必須僅在使用者直接呼叫時執行。
.agents/skills/版本會同時執行兩個動作：為 Codex 建立agents/openai.yaml並設定policy.allow_implicit_invocation: false，以及為 Antigravity 在description中寫入「僅在使用者直接要求時使用」(因 Antigravity 無對應欄位)。詳細資訊請見references/providers.md第 3 節。
- 各供應商專屬功能： Claude Code 擁有 subagent、參數變數以及在
SKILL.md中嵌入 shell 命令的功能 (請參閱references/frontmatter-spec.md)。僅在 Claude Code 版本中使用這些功能；其他供應商的版本應根據references/providers.md第 3 節進行轉換。 - 驗證而非信任：
- 每個生成的技能都必須附帶
scripts/validate.sh，並使用標準退出碼 (0= 通過，1= 失敗)。 - 100% 遵守 markdownlint 規範。
- 每個生成的技能都必須附帶
- 零工作區污染：
- 所有設定檔、資源和腳本僅位於各供應商目錄下的技能封裝目錄中。
- 所有範例文件僅位於技能的
examples/目錄。不得在專案的其他業務目錄（如src/、根目錄）中生成或複製範例檔案。 - 測試中的暫存檔應寫入作業系統的暫存目錄（或使用者指定的暫存目錄），並在完成後立即清除。
- 以結構化選項詢問使用者：
- 提供給使用者的所有選項（範圍、供應商、想法中的模糊點、設計方向）都應以選項形式詢問。如果階段提供選擇題形式的詢問工具，則使用該工具；否則，列出編號選項，然後停止並等待使用者回覆。
- 呈現順序：(1) 要建立的技能用途，(2) 問題詢問的內容和原因，(3) 每個選項的利弊說明，(4) 推薦選項，置於清單首位並標註
(推薦)。 - 每次最多詢問 4 個問題，優先詢問重要事項。始終允許使用者回答與已提供選項不同的答案。
- 在未獲得使用者回覆前，不得自行代為選擇。
- 每個供應商一份符合其標準的版本：
- 共用資源 (
template.md、examples/、references/、scripts/) 原樣複製。但SKILL.md(以及 Codex 的agents/openai.yaml) 需分別撰寫：一份給 Claude Code，一份給 Codex 與 Antigravity 共用。 - Codex/Antigravity 版本必須能在兩者上正確執行：僅使用標準開放欄位，不使用僅 Claude Code 理解的變數或工具，且不得將正在運行的代理稱為「Claude」。僅在技能主題涉及 Claude 時才能提及。
- 共用資源 (
2. 必要輸入
- 必要： 描述要建立技能的想法或業務目標。
- 選用： 特殊限制、所需工具、任務或參考類型。
- 必須詢問 (每次建立新技能時)： 範圍和供應商 (第 2.1 節)，以及想法中的所有模糊點 (第 2.2 節)。僅跳過使用者已在要求中明確回答的問題。
- 不得自行決定模糊點： 若想法粗略，則進行分析並提出建議 (第 2.2 節)，不得自行填寫內容並生成檔案。僅在慣例明顯的情況下 (例如從想法推斷出
kebab-case名稱) 才能自行設定，且必須在設計摘要中說明。
2.1. 詢問範圍與供應商
在生成任何檔案之前，根據原則 6 在同一次詢問中提出兩個問題：
- 範圍 (可複選)：根據下表的三個選項，
project-shared為推薦選項。 - 供應商 (可複選)：Codex、Claude Code、Antigravity。如果技能適用於所有供應商，則推薦全部三個。如果技能僅對某個供應商有意義 (例如僅檢查 Claude Code 的設定檔)，則推薦該供應商並說明原因。
| 範圍 | 意義 | 根目錄 | 執行腳本時的變數 |
|---|---|---|---|
project-shared | 僅用於目前專案，整個團隊共用 (提交至 git) | 專案根目錄 | SCOPE=project (預設) |
project-personal | 僅用於目前專案，僅限於此使用者 (不提交) | 專案根目錄 | SCOPE=project，然後將建立的目錄加入 .git/info/exclude |
user-global | 此使用者的所有專案 | $HOME | SCOPE=user |
規則：
- 若使用者選擇多個範圍，則依序為每個範圍部署。
- 若專案目錄不是 git 儲存庫，則省略
project-personal選項。 - 將所選的範圍和供應商記錄在交接報告中，並附上已建立的目錄清單。
- 技能包含專案特定的內容，但使用者選擇
user-global：在建立前警告一行。
2.2. 分析想法並提出建議
在取得範圍和供應商後，在撰寫任何檔案之前分析想法：
- 摘要已理解的事項： 技能解決什麼問題、誰使用、何時觸發、輸出是什麼。
- 確定設計要點，每個要點應清楚標明是使用者已說明還是代理正在推測：
- 技能類型：任務或參考；是否具有副作用。
- 觸發方式：根據
description自動觸發、僅在使用者直接呼叫時觸發，或兩者兼具；觸發詞彙和不使用的情況。 - 輸入、參數以及缺少時的處理方式。
- 輸出：格式、儲存位置、是否需要
template.md以及在scripts/validate.sh中的檢查標準。 - 執行方式：僅提供指示或需要腳本；所需工具。
- 應拆分到
references/的部分，以使SKILL.md少於 500 行。
- 提出最佳化方向： 針對每個仍有多種作法的要點，提出 2 到 3 個方向並附帶利弊，選擇一個推薦方向。例如：「使用腳本
scripts/check.sh檢查 (快速、準確，但需要 bash)」對比「代理自行閱讀和評估 (靈活，但消耗 token 且容易遺漏)」。 - 詢問使用者： 根據原則 6，將所有模糊點和所有有多種方向的要點整理成問題。
- 確定設計： 獲得回覆後，撰寫設計摘要 (技能名稱、類型、觸發方式、將建立的檔案清單、供應商、範圍、代理自行設定的值)。若回覆產生了新的模糊點，則繼續提問，暫不生成檔案。
2.3. 研究供應商
在為某個供應商撰寫版本之前，閱讀 references/providers.md：
- 若「驗證日期」超過 30 天、技能需要檔案中尚未包含的功能，或檔案中的資訊與實際情況矛盾：查閱該檔案第 6 節的官方文件，修正檔案，更新驗證日期，然後使用
scripts/sync-skill.sh better-skill-gen將檔案複製到其他供應商。 - Antigravity 在共用專案範圍中與 Codex 共用
.agents/skills/(第 5 節)。不要建立.agent/skills/。 - 不要猜測供應商的規格。若有無法查證的點，則向使用者說明並提問。
3. 執行流程
flowchart TD
A["使用者提供的業務想法"] --> A2["0. 詢問範圍與供應商"]
A2 --> B["1. 分析想法、提出建議、詢問模糊點"]
B --> B2["2. 研究供應商"]
B2 --> C["3. 參考 template.md 與 references/"]
C --> D["4. 生成原始版本"]
D --> E["5. 同步資源並為每個供應商撰寫專屬 SKILL.md"]
E --> F["6. 透過 scripts/validate.sh 自我驗證"]
F -->|"通過"| G["完成並交接"]
F -->|"失敗"| D
- 詢問範圍與供應商： 執行第 2.1 節，等待回覆後再繼續。
- 分析想法： 執行第 2.2 節，直到設計確定。技能名稱採用
kebab-case(≤ 64 字元，禁止與anthropic-skills、synced、claude、anthropic重複)。 - 研究供應商： 為所有選定的供應商執行第 2.3 節。
- 參考標準文件： 閱讀
template.md(結構框架)、references/providers.md(供應商之間的差異)、references/frontmatter-spec.md(Claude Code 的欄位) 以及examples/sample.md(寫作風格與腳本邏輯)。 - 生成原始版本： 在第一個選定供應商的目錄中撰寫所有必要元件：
SKILL.md：安全的前置欄位 (使用>-引用或縮排區塊)，少於 500 行。template.md(或templates/)：包含範例變數${VARIABLE}的輸出範本。examples/sample.md：不含任何佔位符的實際範例文字。references/(若有需要分離的規格/複雜知識文件)。scripts/validate.sh：用於檢查結果完整性的腳本。- 共用資源應保持供應商中立：腳本使用相對於技能目錄的相對路徑呼叫。
- 依供應商部署：
- 複製共用資源：執行
PROVIDERS="<選定的供應商>" bash scripts/sync-skill.sh <skill-name>。此腳本會複製除SKILL.md和agents/之外的所有檔案，並為缺少SKILL.md的供應商標記[TODO]。 - 對於其餘目錄，根據
references/providers.md第 3 節的轉換表撰寫專屬的SKILL.md。改寫主體內容，而不僅僅是刪除前置欄位。若同時選擇了 Codex 和 Antigravity，則只有一個.agents/skills/目錄，腳本會自動合併。 - 具有副作用的技能：
.agents/skills/版本需額外建立agents/openai.yaml，並設定policy.allow_implicit_invocation: false，以及將「僅在使用者直接要求時使用」寫入description。 - 範圍
user-global：執行腳本時額外設定SCOPE=user。 - 範圍
project-personal：將剛建立的技能目錄加入.git/info/exclude(不修改.gitignore，不提交)。
- 複製共用資源：執行
- 自我驗證：
- 執行
PROVIDERS="<選定的供應商>" bash scripts/validate.sh <skill-name>(若是user-global則加上SCOPE=user)。 - 腳本檢查：YAML 前置欄位是否有效、markdownlint、
SKILL.md≤ 500 行、所有選定供應商的必要檔案是否存在、以及 Codex/Antigravity 的SKILL.md是否不包含僅 Claude Code 理解的欄位或符記。 - 逐行檢查
[WARN]：若提及 Claude 是因為技能主題相關，則保留；否則修正。 - 若有錯誤則自行修正，直到收到
[PASS]。
- 執行
4. 限制與標準
- 強制規則：
- 所有選項必須根據原則 6 詢問，並等待回覆後再繼續。
- 在建立新技能前，務必詢問範圍與供應商 (第 2.1 節)。
- 不得自行決定模糊點： 在生成檔案前進行分析、提出建議並詢問 (第 2.2 節)。
- 在為供應商撰寫版本前，務必研究該供應商 (第 2.3 節)；不得猜測規格。
- 不得在不同的供應商之間直接複製貼上
SKILL.md： 每個供應商應有符合其標準的專屬版本；validate.sh必須為所有選定的供應商返回[PASS]。 - 零工作區污染： 範例文件僅存在於
examples/中；不得在技能封裝目錄外建立檔案。 - 保持 SKILL.md 少於 500 行： 將詳細內容移至
references/或templates/。 - 標準化前置欄位： 如果
description包含冒號:，則必須使用>-標量或雙引號"..."。 - 遵守 Markdownlint (MD001 - MD047) 針對所有生成的 Markdown 檔案。
- 應做的事：
- 對於所有具有副作用的技能，宣告「僅在使用者呼叫時執行」的機制，並遵循各供應商的特定方式 (Codex：
agents/openai.yaml；Antigravity：description中的句子)。 - 在範本中使用具有高度描述性的範例變數
${VARIABLE_NAME}。 - 在自動測試完成後立即清除產生的暫存檔案。
- 對於所有具有副作用的技能，宣告「僅在使用者呼叫時執行」的機制，並遵循各供應商的特定方式 (Codex：
- 不應做的事：
- 不要將完整的長篇參考文件直接塞入
SKILL.md。 - 不要在 markdown 檔案中留下未包裹
<>或未使用 markdown 連結格式的裸 URL。 - 技能名稱不超過 64 個字元，且不得包含大寫字母或特殊字元。
- 在非 Claude Code 的供應商版本中，不得將運行的代理稱為「Claude」。
- 不要將完整的長篇參考文件直接塞入