plugin-forge

plugin-forge スキルの概要

plugin-forge は、Claude Code プラグイン作者向けの「作って終わり」ではなく「正しく出荷して運用する」ための build-and-maintain スキルです。フォルダ構成、manifest ファイル、マーケットプレイス登録を、毎回ゼロから組み立て直さずに進めたいときに向いています。実際に片づけたい仕事は単に「JSON を書く」ことではなく、「正しい形で scaffold され、バージョン管理が揃い、マーケットプレイス前提のワークフローでインストールできるプラグインを出す」ことです。

plugin-forge が特に向いている人

次のようなケースなら、plugin-forge スキルを使う価値があります。

• 新しい Claude Code プラグインをゼロから作る
• commands/、agents/、skills/、hooks/ などの構成要素を追加する
• .claude-plugin/plugin.json と marketplace metadata をまとめて更新する
• 公開前にプラグインをローカルでテストする
• 複数プラグインを持つ marketplace-style のリポジトリを運用する

特に、単発でそれっぽい出力がほしいのではなく、再現性のある構成を保ちたい開発者に向いています。

汎用プロンプトと比べた plugin-forge の違い

一般的なプロンプトでもプラグインの骨組みは作れますが、plugin-forge には実務向けのガードレールがあります。

• 定義済みの plugin directory layout
• manifest の置き場所と必要フィールドの明示
• marketplace schema の参照先
• ローカル install と testing のワークフロー
• scaffolding と version bump の自動化スクリプト

この組み合わせが重要なのは、プラグインでよく起きる失敗がコード品質ではなく、構成の不整合や metadata の食い違いだからです。

plugin-forge が実際にカバーしている範囲

リポジトリを見る限り、plugin-forge の中心は次のとおりです。

• 新規プラグインの scaffolding を行う scripts/create_plugin.py
• バージョンを同期更新する scripts/bump_version.py
• フォルダ構成と manifest 配置を説明する references/plugin-structure.md
• marketplace entry のルールを示す references/marketplace-schema.md
• 作成・テスト・公開の流れをまとめた references/workflows.md

つまり、広く理論を語るドキュメントというより、実装ガイドと補助ツールのセットと考えるのが適切です。

Code Generation で plugin-forge が強い場面

Code Generation 向けの plugin-forge が特に役立つのは、モデルに「正しいプラグインの形」で着地するファイルを生成させたいときです。たとえば次のような場面です。

• 妥当な metadata を備えた新規 plugin skeleton を作る
• 既存プラグインに新しい command や skill を差し込む
• plugin.json を更新し、それに対応する marketplace entry も合わせて変える
• semantic version bump を含むリリース準備を進める

逆に、すでに動いているプラグインの中で純粋な business logic だけを書きたいなら、plugin-forge よりドメイン特化の coding skill のほうが有効なこともあります。

plugin-forge スキルの使い方

plugin-forge のインストール前提

上流の SKILL.md には専用の install command は書かれていないため、インストール方法は使っている環境の skill 読み込み方式に依存します。リポジトリの skill bundle を使っているなら、よくあるパターンは次のとおりです。

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

そのうえで、プラグイン作成、manifest、marketplace registration、local testing、version management が関わるタスクで 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 の契約、最後に実行できる helper へと自然に入れます。

plugin-forge に渡すべき入力情報

plugin-forge は、「プラグインを作って」だけの曖昧な依頼より、リポジトリや公開方法に関する具体的な前提があるほど精度が上がります。最低限、次は指定したいところです。

• kebab-case の plugin 名
• marketplace root path
• plugin の用途
• author name と email
• 初期 keywords
• category
• commands、agents、skills、hooks、MCP config のどれが必要か
• 新規 plugin なのか、既存 plugin の更新なのか

この情報がなくても下書きは作れますが、最終的には手作業での修正が増えがちです。

曖昧な要望を、強い plugin-forge プロンプトに変える

弱いプロンプト:

Create a Claude Code plugin for my project.

より強いプロンプト:

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"

細かく手作業で scaffold することより、まず正しいセットアップを素早く作りたいときの最短ルートです。

manifest のズレを防ぐなら version script を使う

plugin-forge の実用面で特に効くのが、バージョンの同期管理です。スキルには 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

これは重要です。というのも、この 2 ファイル間の version mismatch は、運用時によくあるミスだからです。

実際の plugin-forge ワークフローに沿って進める

実務で安定しやすい plugin-forge の流れは次のとおりです。

1. plugin を scaffold する
2. 生成された plugin.json を確認する
3. .claude-plugin/marketplace.json の marketplace entry を検証する
4. command や skill などのコンポーネントを追加する
5. marketplace install flow でローカルテストする
6. 必要に応じて調整する
7. リリース前に version を上げる

巨大な 1 本のプロンプトで全部やらせるより、この流れのほうが信頼できます。

早い段階で見込んでおくべきローカルテストの流れ

reference には、ローカルテストの具体的な手順も含まれています。

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

つまり、plugin-forge に投げるプロンプトも、単に説明文を作らせるのではなく、「インストール可能な path と metadata を出す」前提で設計すべきです。source path や plugin 名が不一致だと、その時点でテストは止まります。

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

レビュー範囲を見積もるうえで、この点は重要です。plugin-forge は単一ファイルではなく、複数ファイルにまたがる変更を生みやすいスキルです。

plugin-forge の出力品質を上げる実践的なコツ

plugin-forge には、次のように依頼すると精度が上がります。

• 既存の plugin 名と path を厳密に維持する
• すべての identifier を kebab-case のままにする
• plugin manifest と marketplace entry を必ずセットで示す
• 推測できなかった必須フィールドは明示して説明する
• 「generated files」と「manual follow-up」を分けて出す
• manifest 間で version と name が一致しているか検証する

見栄えはよくても install できない出力を減らすうえで、こうした指示が効きます。

plugin-forge スキル FAQ

すでにプロンプトが上手くても plugin-forge を使う価値はある？

あります。特にリスクが「構造の正しさ」にあるなら有効です。manifest、marketplace entry、directory layout を揃える必要があるときは、普通のプロンプトより plugin-forge のほうが役に立ちます。すでにあるプラグイン内で command ファイル 1 つだけ書きたい、といった用途なら優位性は小さめです。

plugin-forge は初心者にも使いやすい？

概ね使いやすいです。plugin-forge は、プラグイン作成から testing までの道筋を具体的に示してくれます。ただし、marketplace root がどこにあるか、命名規則をどうするか、何のコンポーネントが必要かまでは、自分で理解している必要があります。得意なのは product design より構造面です。

plugin-forge を使わないほうがいいのはどんなとき？

次のケースでは plugin-forge は見送ったほうがよいです。

• Claude Code plugin を作っていない
• marketplace-style の配布を使わない
• 汎用的な Python や JavaScript のコード生成だけがほしい
• リポジトリが、文書化された構成と意図的に異なる独自レイアウトを採用している

こうした場合、plugin-forge はむしろ違う方向の構成へ寄せてしまう可能性があります。

plugin-forge は公開作業まで自動でやってくれる？

完全には対応しません。scaffolding、manifest、marketplace registration、local testing のガイド、version 更新といった公開前の準備には強いです。ただし、エンドツーエンドの release platform ではありません。最終的には、自分でファイルを確認し、ローカルテストを行い、公開や配布の処理を進める必要があります。

導入時にいちばん詰まりやすいポイントは？

たいていはリポジトリの文脈不足です。plugin-forge は marketplace root の場所や、plugin をどう分類すべきかを把握している前提で動きます。その答えを出せない状態だと、出力は production-ready ではなく draft-quality に留まりやすいです。

manifest を手で編集するのと比べて plugin-forge はどう違う？

単発の変更なら手作業でも十分です。ただし、再現性がほしいときや、plugin.json と marketplace.json のズレを避けたいときは plugin-forge のほうが向いています。実務上のわかりやすい利点は、同梱されている scripts です。

plugin-forge スキルを改善するには

plugin-forge にはリポジトリ前提の入力を渡す

最も効果的な改善は、正確な path と現行ファイルを与えることです。たとえば「version を上げて」ではなく、次のように伝えます。

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.

こうすると、一般論ではなく、検証可能な変更に寄せやすくなります。

要約ではなく、ファイル単位の出力を求める

plugin-forge は、具体的な成果物を求めたほうが安定します。

• 完全な plugin.json
• 正確な marketplace entry
• 提案する directory tree
• README のたたき台
• ローカルテスト用の follow-up commands

特に Code Generation 向けの plugin-forge では、すぐ適用できるファイルが出てくること自体が価値です。

よくある失敗パターンを先回りして防ぐ

plugin-forge の出力では、次の点を確認してください。

• plugin 名がファイルごとに異なる
• marketplace の source path が実際のフォルダ構成と一致しない
• 片方の manifest だけ version が更新されている
• metadata では optional component を参照しているのに実体が作られていない
• 生成された構成に .claude-plugin/plugin.json が欠けている

references/plugin-structure.md と references/marketplace-schema.md に照らしてざっと見直すだけでも、多くの不具合を拾えます。

plugin-forge は 2 パス運用にすると結果が良くなる

実務では、次の 2 段階に分けるのが堅実です。

1. 1 回目: 構成と manifest を生成する
2. 2 回目: plugin components と README の改善を行う

scaffolding、business logic、docs、testing setup、publishing notes を 1 本のプロンプトに詰め込むと、品質は下がりがちです。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 は reference docs と組み合わせて使う

plugin-forge の出力を改善するいちばん良い方法は、リポジトリ内 reference を明示的に参照させることです。プロンプトでは次を挙げておくと有効です。

• directory の期待形を確認する references/plugin-structure.md
• marketplace fields を確認する references/marketplace-schema.md
• install と testing の流れを確認する references/workflows.md

こうしておくと、一般的なプラグイン前提に流れず、そのリポジトリ固有の慣習に anchored された出力になりやすくなります。