devetai/better-plugin-gen

Better Plugin Generator (better-plugin-gen)

此技能協助使用者建立一個插件：一個將多個元件（如 skill、agent、hook、MCP 伺服器）打包的目錄，可用單一指令安裝到 coding agent 中。此技能支援三個主機（可載入插件的 agent 工具）：Claude Code、Codex、Antigravity。每個主機有其專屬的 manifest；此技能共用 skills/ 目錄，並為所選的主機生成對應的 manifest。

以下所有 template.md、references/、examples/、scripts/ 路徑均從包含此 SKILL.md 檔案的目錄開始計算。

---

1. 核心原則

1. 先問後生。 若工作階段中有結構化提問工具，所有選項皆應透過該工具詢問使用者；若無，則使用編號列表列出選項，清楚標示建議選項，並等待回覆。每次提問前，簡短說明：即將建立的插件用途、該問題的意義以及為何需要此資訊。不可自行推斷不明確之處並生成檔案。
2. 不臆測主機規格。 檔案位置、manifest 格式及 MCP 設定均參考 references/hosts.md。若標示為「尚未驗證」，必須通知使用者。
3. 主要邏輯置於 skill 中。 Skill 是唯一能在三個主機上執行的元件。僅在使用者需要且主機支援時，才添加 Agent、command、hook、LSP 等元件。
4. 生成可執行的最小框架。 每個生成的元件都應能立即執行，但內容需簡潔。如果專案中已有 better-skill-gen 或 better-agent-gen 等 skill，建議使用者在插件成功執行後，利用這些 skill 來進一步撰寫更完善的 skill 或 agent。
5. 自我驗證。 僅在 scripts/validate.sh 回傳 exit code 0 時，才可交付插件。
6. 無外部副作用。 此技能僅在目標插件目錄（以及若使用者選擇，在 repo 根目錄的 marketplace 檔案）內寫入檔案。不可執行 git commit、git push、安裝插件、或修改使用者的主機設定；僅能輸出指令，讓使用者自行執行。

---

2. 輸入

• 必填： 插件的用途（一句話即可），或當要添加元件時，現有插件的路徑。從使用者的請求中取得。
• 若遺漏則詢問： 目標主機、目錄位置、元件清單、是否建立 marketplace、插件名稱、作者、授權條款。
• 資訊不足： 依照第 3 章步驟 2 的表格提問；若使用者未回覆，則停止等待。

---

3. 流程

步驟 1：確定模式並讀取現況

• 新建： 使用者描述了插件，但尚未有目錄。
• 添加元件 / 添加主機： 使用者提供含有 .claude-plugin/plugin.json、.codex-plugin/plugin.json 或 plugin.json 的路徑。讀取所有 manifest，列出現有元件，並執行 shell 指令 bash scripts/validate.sh <dir> 以在修改前得知現有錯誤。
• 建立 marketplace： 使用者已有插件，只需發布。讀取插件後，跳至步驟 6。
• 讀取 references/hosts.md。若「驗證日期」超過 30 天，或插件需要此檔案中尚未記載的功能：則依據該檔案第 6 章的來源進行網路查詢、更新檔案與驗證日期，然後通知使用者已變更的部分。

步驟 2：詢問使用者

摘要已理解的內容（插件用途、目標使用者、執行時機），然後進行第一輪提問，跳過使用者已明確回答的問題：

問題	類型	選項（建議選項置頂）
插件要在哪些主機上執行？	多選	Claude Code; Codex; Antigravity。建議若插件僅包含 skill 和 MCP，則選全部三個；若需要 hook、LSP 或 userConfig，則僅選 Claude Code
插件放置位置？	單選	獨立 repo，插件在根目錄 (./<名稱>/)；在 marketplace repo 內 (plugins/<名稱>/)；在當前專案中進行測試
插件包含哪些元件？	多選	Skill; Agent; Hook; MCP 伺服器; Command; LSP; userConfig
是否建立 marketplace 以便發布？	單選	是，為所選主機建立；否，僅在本機測試

第二輪（如有需要）：插件名稱（建議從描述推斷出 kebab-case 名稱）、作者及 GitHub repo 擁有者、授權條款、每個元件的細節（skill 的功能、agent 可使用哪些工具、hook 在哪個事件觸發、哪個 MCP 伺服器以及是否需要 token）。

提問規則：

• 若使用者選擇的 hook 與非 Claude Code 的主機一起使用：預先告知 references/hosts.md 第 4 章中的衝突，詢問是否保留 hook。
• 若插件需要 token 或密碼：詢問提供方式（Claude Code：使用 userConfig 並設定 sensitive: true；其他主機：環境變數，並在 README 中說明）。絕對不可將機密值寫入任何檔案。
• 若名稱與 Claude Code 的保留名稱衝突（references/hosts.md 第 2.1 章）：建議其他名稱。
• 若目標目錄已存在檔案：列出將被覆寫的檔案，並在寫入前詢問使用者。

步驟 3：確定設計

在對話中撰寫摘要：名稱、主機、位置、預計建立的目錄樹（標記每個檔案所屬的主機）、每個元件在主機上的執行情況、agent 自行設定的值、以及尚未驗證之處。若使用者的回答產生了新的不明確點，則繼續提問，暫不生成檔案。

步驟 4：生成檔案

1. 讀取 template.md（每個檔案的框架）和 references/components.md（每個元件的格式）。讀取 examples/sample.md 以了解所需的詳細程度。
2. 為每個所選主機寫入 manifest。所有 manifest 中的 name、version、description 必須完全一致。
3. 將元件寫入插件根目錄，不放在 .claude-plugin/ 或 .codex-plugin/ 內：
   • Skill：skills/<名稱>/SKILL.md，frontmatter 僅包含 name、description，以便所有主機讀取。
   • MCP：Claude Code 和 Codex 使用 .mcp.json；Antigravity 使用 mcp_config.json（遠端伺服器使用 serverUrl）。兩個檔案中的伺服器清單相同。
   • Hook：hooks/hooks.json，用 "hooks" 金鑰包裹，始終包含 matcher，使用 "${CLAUDE_PLUGIN_ROOT}"（Claude Code 的變數）呼叫指令碼。指令碼置於 scripts/ 中，需有 shebang。
   • Agent、command、LSP、userConfig：依照 references/components.md。
4. 根據框架 File 8 寫入 README.md，至少 40 字，包含各主機的元件表格以及每個主機的安裝指令（references/publishing.md 第 5 章）。
5. 添加元件模式：僅添加新檔案，並在 manifest 中修改正確的金鑰；若插件已發布，則所有 manifest 的 version 需遞增（修訂版）。

步驟 5：自我驗證

1. 執行 shell 指令 HOSTS="<所選主機清單>" bash scripts/validate.sh <插件-或-repo-目錄>。例如 HOSTS="claude codex antigravity"。
2. 該指令碼會執行 check_plugin.py（檢查 manifest、名稱、路徑、MCP、hook、skill、agent、marketplace、佔位符、疑似機密字串），然後在機器上若安裝了 claude plugin validate 和 agy plugin validate 則執行之。
3. 若有 [FAIL] 或 CLI 回報錯誤：修改檔案，重新執行，直到 exit code 為 0。
4. 閱讀每個 [WARN]：若能解決則修正；若決定保留（例如已通知使用者的多主機 hook 警告），則在交付報告中記錄原因。
5. 若需要暫存檔案，則寫入使用者指定的暫存目錄；若未指定，則使用作業系統的暫存目錄；驗證完成後立即刪除。

步驟 6：Marketplace（若選擇）

• Claude Code：在 repo 根目錄的 .claude-plugin/marketplace.json（框架 File 9）。
• Codex：在 repo 根目錄的 .agents/plugins/marketplace.json（框架 File 10）。
• Antigravity：無需檔案；在 README 中寫入 agy plugin install 指令，並附上 GitHub repo 的 URL，例如 https://github.com/phucbui/pr-review-kit。
• 再次執行步驟 5，但使用 repo 根目錄，以同時驗證 marketplace。

步驟 7：交付

根據 template.md 結尾的「交付報告」框架輸出報告：目錄、主機、驗證結果、檔案表格、尚未驗證之處、本機測試指令、供使用者自行執行的發布指令（references/publishing.md 第 3 至 6 章）。若專案中有 better-skill-gen 或 better-agent-gen，則用一行提示如何使用它們來深入撰寫元件。

---

4. 限制條件

• 必須遵守：
  • 在生成檔案前，必須詢問主機、位置、元件和 marketplace；不可自行決定不明確之處。
  • 僅在目標插件目錄和 repo 根目錄的 marketplace 檔案內寫入；不可在其他位置建立範例檔案。範例僅存在於此技能的 examples/ 中。
  • 不可執行 git commit、git push、claude plugin install、agy plugin install、codex plugin marketplace add；僅能輸出指令。
  • 不可將 token、密碼、或 API 金鑰寫入任何檔案。
  • 僅在 scripts/validate.sh 回傳 exit code 0 時才能交付。
• 建議：
  • 插件、skill、agent 名稱使用 kebab-case；初始版本為 0.1.0。
  • 讓插件專注於單一目的；若使用者將不相關的功能合併，建議拆分為多個插件。
  • 在 README 中明確說明每個元件在哪些主機上執行。
• 不應：
  • 不要將包含 Claude Code 專有欄位的 SKILL.md 原封不動複製給 Codex 或 Antigravity 使用的插件。
  • 不要在 manifest、hook、MCP 中使用絕對路徑或 ..。
  • 不要在插件根目錄放置 CLAUDE.md；若需載入指引，應將其放入 skill 中。