plugin-forge

plugin-forge skill 概覽

plugin-forge 是一個面向 Claude Code 外掛作者的建置與維護 skill，適合用在你想要正確的資料夾結構、manifest 檔案，以及 marketplace 註冊流程，但又不想每次都從頭摸索工作流程的情境。真正要解決的問題不是「寫一點 JSON」，而是「把外掛用正確的 scaffold 建起來、版本維持一致，並且能在 marketplace 式的安裝流程中順利安裝」。

plugin-forge 最適合哪些人

如果你符合以下情況，就很適合使用 plugin-forge skill：

• 從零開始建立新的 Claude Code plugin
• 要替 plugin 加入 commands/、agents/、skills/ 或 hooks/ 等元件
• 需要同步更新 .claude-plugin/plugin.json 與 marketplace metadata
• 想在發佈前先做本機測試
• 維護採 marketplace 風格、且包含多個 plugin 的 repository

對於重視可重複結構、而不只是一次性產出 prompt 結果的開發者來說，plugin-forge 特別實用。

plugin-forge 和一般 prompt 的差異在哪裡

一般 prompt 也可以幫你草擬 plugin 骨架，但 plugin-forge 多了一層實務上的保護機制：

• 明確定義的 plugin 目錄結構
• manifest 檔案位置與欄位要求都更清楚
• 提供 marketplace schema 參考
• 包含本機安裝與測試流程
• 附帶 scaffold 與版本升級的自動化腳本

這個組合很重要，因為最常見的 plugin 失敗原因，往往不是程式碼品質，而是結構不一致，或 metadata 對不上。

plugin-forge 實際涵蓋哪些內容

從 repository 內容來看，plugin-forge 主要聚焦在：

• scripts/create_plugin.py：建立新 plugin 的 scaffold
• scripts/bump_version.py：同步更新版本號
• references/plugin-structure.md：資料夾與 manifest 結構說明
• references/marketplace-schema.md：marketplace 項目規則
• references/workflows.md：建立、測試與發佈流程

所以它比較像是「實作指南 + 輔助工具」，而不是泛泛而談的理論文件。

在 Code Generation 情境下，plugin-forge 何時特別適合

用在 Code Generation 時，plugin-forge 最適合的情境，是你希望模型產出的檔案能直接落在正確的 plugin 結構中，例如：

• 產出帶有有效 metadata 的新 plugin 骨架
• 在既有 plugin 中新增 command 或 skill
• 同步更新 plugin.json 與對應的 marketplace 項目
• 發佈前準備，包含 semantic version bump

如果你的主要需求只是替一個已經能正常運作的 plugin 補純商業邏輯，那 plugin-forge 的幫助通常不如專門的領域型 coding skill。

如何使用 plugin-forge skill

plugin-forge 的安裝背景

上游的 SKILL.md 沒有提供它自己的安裝指令，因此實際安裝方式會取決於你在環境中如何載入 skills。若你使用的是這個 repository 的 skill bundle，常見做法是：

npx skills add softaworks/agent-toolkit --skill plugin-forge

安裝後，當你的任務涉及 plugin 建立、manifest、marketplace 註冊、本機測試或版本管理時，就可以叫用 plugin-forge。

先讀這些檔案

如果你想快速上手，建議依照這個順序閱讀：

1. skills/plugin-forge/SKILL.md
2. skills/plugin-forge/references/plugin-structure.md
3. skills/plugin-forge/references/marketplace-schema.md
4. skills/plugin-forge/references/workflows.md
5. skills/plugin-forge/scripts/create_plugin.py
6. skills/plugin-forge/scripts/bump_version.py

這條路徑會先讓你理解「它在做什麼」，接著掌握預期的檔案結構、marketplace 契約，再來看可直接執行的輔助工具。

plugin-forge 需要你提供哪些輸入資訊

plugin-forge 在你提供具體的 repository 與發佈背景時，效果會最好，而不是只丟一句「幫我做個 plugin」。至少要說明：

• plugin 名稱，使用 kebab-case
• marketplace root path
• plugin 用途
• 作者姓名與 email
• 初始 keywords
• category
• 是否需要 commands、agents、skills、hooks 或 MCP config
• 這是全新 plugin，還是更新既有 plugin

如果缺少這些資訊，模型仍然可以先草擬檔案，但通常後續還是得手動整理與修正。

把模糊需求改寫成更有效的 plugin-forge prompt

較弱的 prompt：

Create a Claude Code plugin for my project.

較強的 prompt：

Use plugin-forge to scaffold a new Claude Code plugin named schema-audit inside /repos/internal-marketplace. Author is Jane Doe <jane@example.com>. Description: “Validate JSON and OpenAPI schemas in CI.” Keywords: schema,openapi,json,validation. Category: developer-tools. Include commands/ and skills/, but no hooks yet. Generate the expected folder layout, plugins/schema-audit/.claude-plugin/plugin.json, the matching .claude-plugin/marketplace.json entry, and a short README. Follow the marketplace and plugin structure references.

第二種寫法能讓 plugin-forge 取得足夠資訊，因此產出的檔案會更接近可直接使用的狀態。

想求快，就用 scaffolding script

如果你的 metadata 已經想清楚了，建立初始樹狀結構時，比起手動慢慢建，更建議直接使用 helper script：

python scripts/create_plugin.py plugin-name \
  --marketplace-root /path/to/marketplace \
  --author-name "Your Name" \
  --author-email "your.email@example.com" \
  --description "Plugin description" \
  --keywords "keyword1,keyword2" \
  --category "productivity"

如果你在意的是「先正確建好」，而不是「每個檔案都自己手刻」，這通常是最快的路徑。

用版本腳本避免 manifest 漂移

plugin-forge 很實用的一點，是它把版本同步這件事處理得比較扎實。skill 內建的 scripts/bump_version.py 會同時更新：

• plugins/<plugin-name>/.claude-plugin/plugin.json
• .claude-plugin/marketplace.json

範例：

python scripts/bump_version.py plugin-name patch \
  --marketplace-root /path/to/marketplace

這很重要，因為這兩個檔案版本不一致，是維護 plugin 時最常見的錯誤之一。

照 plugin-forge 的實際工作流程走

比較可靠的 plugin-forge 使用流程如下：

1. scaffold plugin
2. 檢查產生的 plugin.json
3. 確認 .claude-plugin/marketplace.json 中的 marketplace 項目
4. 加入 commands 或 skills 等元件
5. 透過 marketplace 安裝流程做本機測試
6. 持續迭代
7. 發版前再 bump version

比起一開始就丟一個超大 prompt，要求模型一次完成全部事情，這種流程通常更穩。

本機測試流程要提早納入規劃

參考文件中有一條很具體的本機測試路徑：

/plugin marketplace add /path/to/marketplace-root
/plugin install plugin-name@marketplace-name

這代表你在設計 prompt 時，應該讓 plugin-forge 產出的是「可安裝的路徑與 metadata」，而不只是描述型檔案。只要 source path 或 plugin name 不一致，測試幾乎會立刻失敗。

plugin-forge 常會修改的關鍵檔案

實際使用時，可以預期 plugin-forge 會建立或編輯這些內容：

• plugins/<plugin-name>/.claude-plugin/plugin.json
• .claude-plugin/marketplace.json
• plugins/<plugin-name>/README.md
• plugins/<plugin-name>/commands/
• plugins/<plugin-name>/agents/
• plugins/<plugin-name>/skills/
• plugins/<plugin-name>/hooks/hooks.json
• plugins/<plugin-name>/.mcp.json

這對 review 規劃很有幫助，因為 plugin-forge 往往不是只動單一檔案，而是一次跨多個檔案一起變更。

提升 plugin-forge 輸出品質的實用技巧

你可以明確要求 plugin-forge：

• 完整保留既有 plugin 名稱與路徑，不要自行改寫
• 所有 identifier 一律維持 kebab-case
• 同時列出 plugin manifest 與 marketplace entry
• 對於無法推斷的必要欄位，直接說明缺了什麼
• 把「generated files」和「manual follow-up」分開
• 檢查各個 manifest 之間的版本與名稱是否一致

這些要求能有效降低結果看起來漂亮、但其實無法安裝的風險。

plugin-forge skill 常見問題

如果我本來就很會寫 prompt，還有必要用 plugin-forge 嗎？

有，前提是你的主要風險在於結構正確性。當你需要一致的 manifest、marketplace 項目與目錄配置時，plugin-forge 會比一般 prompt 更有價值。反過來說，如果你只是想在既有 plugin 裡補一個 command 檔案，它的優勢就沒那麼明顯。

plugin-forge 對新手友善嗎？

大致上算友善。plugin-forge 讓新手在 plugin 建立與測試上有一條比較具體的路可以走。要注意的是，新手仍然得知道自己的 marketplace root 在哪裡、命名規則是什麼，以及自己實際想要哪些元件。它比較擅長協助你把結構做對，而不是幫你完成產品設計。

什麼情況下不該使用 plugin-forge？

以下情況建議跳過 plugin-forge：

• 你做的不是 Claude Code plugin
• 你不是用 marketplace 風格的發佈方式
• 你只需要一般性的 Python 或 JavaScript 程式碼產生
• 你的 repository 刻意採用一套和文件不同的自訂 plugin 結構

在這些情境裡，plugin-forge 反而可能把你往錯的結構上推。

plugin-forge 會自動處理發佈嗎？

不算完整自動化。plugin-forge 很擅長處理發佈前準備：例如 scaffold、manifest、marketplace 註冊、本機測試指引，以及版本更新。但它不是端到端的 release 平台。你還是需要自己 review 檔案、做本機測試，並執行既有的發佈或分發流程。

採用 plugin-forge 最大的阻礙是什麼？

通常是缺乏 repository context。plugin-forge 預設你知道 marketplace root 在哪，以及 plugin 應該歸在哪個 category。若這些問題你答不出來，產出內容通常就會停留在草稿品質，而不是可直接上線的結果。

plugin-forge 和手動編輯 manifest 相比如何？

如果只是偶爾改一次，手動編輯也可以；但如果你想要可重複、可維護，或想避免 plugin.json 與 marketplace.json 之間出現漂移，plugin-forge 會更適合。它內建的 scripts，是最清楚也最實際的優勢之一。

如何改進 plugin-forge skill 的使用效果

給 plugin-forge 帶有 repository 脈絡的輸入

最有效的改進方式，就是提供精確路徑與目前檔案狀態。不要只說「幫我升版本」，而是像這樣描述：

Use plugin-forge to bump schema-audit in /repos/internal-marketplace from its current version using a minor change. Check both plugins/schema-audit/.claude-plugin/plugin.json and .claude-plugin/marketplace.json, then show the diff.

這樣會把 skill 推向「可驗證的修改」，而不是停留在泛泛建議。

要求逐檔輸出，不要只要摘要

當你要求 plugin-forge 交付具體成果物時，效果通常會更好，例如：

• 完整的 plugin.json
• 精確的 marketplace entry
• 建議的 directory tree
• README 起始版本
• 本機測試要執行的後續指令

這對於用在 Code Generation 的 plugin-forge 尤其重要，因為它真正的價值就在於產出可直接套用的檔案。

預防最常見的失敗模式

檢查 plugin-forge 輸出時，特別留意以下問題：

• plugin name 在不同檔案中不一致
• marketplace 的 source path 和實際資料夾結構對不上
• 版本只更新了一個 manifest，另一個沒改
• metadata 提到了可選元件，但實際上沒有建立
• 產出的結構漏掉 .claude-plugin/plugin.json

只要快速對照 references/plugin-structure.md 與 references/marketplace-schema.md，大多數問題都能提早抓到。

用兩階段 workflow，plugin-forge 效果通常更好

實務上更穩的 plugin-forge 用法是：

1. 第一輪：先產生結構與 manifests
2. 第二輪：再產生 plugin 元件與 README 強化內容

如果你想在單一 prompt 裡同時完成 scaffolding、商業邏輯、文件、測試設定與發佈說明，品質通常反而會下降。plugin-forge 最強的地方，還是先把結構做對。

第一次輸出後，用精準修正指令繼續迭代

不要只說「幫我修一下」，而是給出具體修補指令，例如：

• 「Regenerate marketplace.json entry so source points to ./plugins/schema-audit。」
• 「Add skills/ to the tree and keep manifest fields unchanged。」
• 「Update only version fields; do not rewrite descriptions or keywords。」
• 「Align the plugin name to kebab-case everywhere。」

這種帶約束條件的迭代方式，會讓 plugin-forge 穩定很多。

將 plugin-forge 和參考文件搭配使用，而不是拿來取代文件

想讓 plugin-forge 輸出更可靠，最好的做法是要求它明確依照 repository 內的參考文件。你可以在 prompt 中直接提到：

• references/plugin-structure.md：確認目錄結構要求
• references/marketplace-schema.md：確認 marketplace 欄位
• references/workflows.md：確認安裝與測試流程

這樣能讓 skill 牢牢對齊 repository 的實際慣例，而不是退回一般化的 plugin 假設。