1つのリポジトリで複数のAIエージェントにプラグインを配る：marketplace と版管理の設計

第1回では、AIコーディングエージェントに守らせたい社内ルールを、エージェントが読む Skills と実行を縛る hooks に分け、プラグインとして束ねて配る、という選択肢を整理しました。そこから1か月ほど運用を続けて分かったのは、配る仕組みを作るより、配ったものが各自の端末で同じ版のまま動いているかを確かめるほうが難しい、ということです。

フィールフロウの社内向けプラグインのうち、OSS として公開している ff-dev-toolkit だけでも、2026年9月17日の v0.118.0 から10月23日の v0.164.0 までの約5週間で、56回リリースしています。これだけ頻繁に版が上がると、利用者ごとに違う版が動いている状態は例外ではなく日常になります。それに気づけなければ、ルールを直しても「配ったつもり」で終わります。

この記事はプラグインシリーズの第2回として、1つのリポジトリで複数のAIエージェントにプラグインを配る構成と、版管理の設計を扱います。想定読者は、第1回を読んで「自社でも配ってみたい」と考えた中小企業の開発リーダー・CTOと、その指示で手を動かす技術リードです。後半では、私たちが実際に踏んだ落とし穴を4件、症状・原因・対策の順に書きます。

結論：配布元は1つにまとめ、版のずれは起きる前提で検出する

要点：1つの GitHub リポジトリを marketplace（プラグインのカタログ）にすれば、同じ marketplace を Codex CLI、GitHub Copilot CLI、grok CLI にも登録して、Claude Code 形式のプラグインを配れます（Codex などは互換としての読み込みで、筆者の環境で実測）。ただし「配った版」と「動いている版」は別物です。版の上げ方の規則と、ずれに気づく仕組みを最初からセットで設計します。

先に結論を3つにまとめます。

配布元は1か所にする。 1つのリポジトリに1つの marketplace を置き、その中にN個のプラグインを並べます。ハーネス（エージェントを動かす実行環境）ごとにリポジトリを分けると、同じルールの写しが増え、直すたびに全部を揃える作業が発生します。
動いている版は、配った版とずれる。 セッションは起動時に読み込んだ版を使い続け、ハーネスはそれぞれ自分の写し（キャッシュ）を持ちます。さらに配布の経路によっては、同じ版番号なのに中身が違う配布物が並びます。
だから版の規則と検出をセットにする。 いつ版を上げるか、何を壊したら破壊的変更か、を決めたうえで、更新通知・版の照合・ゲートで、ずれに利用者が気づける形にします。

構成：1つのリポジトリ = 1つの marketplace = N個のプラグイン

要点：リポジトリ直下の .claude-plugin/marketplace.json がカタログで、各プラグインは plugin.json（名前と版）と、Skills・hooks・MCP 設定・スクリプトを持つフォルダです。フィールフロウの社内 marketplace には2026年10月23日時点で13のプラグインが登録されています。

フィールフロウの社内 marketplace は、GitHub の Private リポジトリ feelflow-plugins です。構成を図にすると次のようになります。

カタログの marketplace.json には、プラグインの名前と取得元（source）が並びます。2026年10月23日時点の13件のうち12件は、同じリポジトリの plugins/ 配下を相対パスで指しています。残る1件（業務向けの ff-work-toolkit）は別の GitHub リポジトリを source に指定していて、別リポジトリで開発しているプラグインも、カタログからは同じように配れます。第1回の時点（2026年9月17日）では9件だったので、約1か月で4件増えました。Claude Code の取得元には、相対パスと GitHub のほかに、任意の Git の URL、リポジトリ内のサブディレクトリ、npm パッケージ、zip アーカイブなどが用意されています（Marketplace reference）。

プラグイン1つの中身は、開発ワークフローを担う ff-dev-toolkit を例にとると次のとおりです。

.claude-plugin/plugin.json：プラグインの名前と版（version）
skills/：エージェントが必要なときに読む手順（SKILL.md）
hooks/：ツール実行の前後に走る検査
.mcp.json：同梱する MCP サーバー（社内の仕様書検索など）
scripts/：hooks や Skills から呼ぶ補助スクリプト

部品をすべて持つ必要はありません。校正や思考法のプラグインは Skills だけで成り立っています。

なお、.claude-plugin/marketplace.json という置き場所は Claude Code の形式です。Codex の公式ドキュメントが正式な置き場所としているのは .agents/plugins/marketplace.json で、.claude-plugin/marketplace.json は互換として扱われています（Package your plugin）。GitHub Copilot CLI も .claude-plugin/marketplace.json を読みますが、探す順番は最後です（Copilot CLI plugin reference）。今日は1つのファイルで配れていても、互換の扱いが変わる可能性は残ります。

ハーネスごとに、どの部品がどこまで動くか

同じプラグインを登録できても、中の部品がどこまで動くかはハーネスごとに違います。私たちが社内 marketplace の README に記録している実測を、公開できる範囲で表にしました。Claude Code の列は、2026年10月23日に筆者の環境（Claude Code 2.1.308）で確かめた結果です。「確認済み」は実際に動かした項目で、版と時期が分かるものはセルに書きました。「一部確認済み」はセル内に書いた範囲だけを動かした項目、「未確認」は実際には走らせていない項目です。

部品	Claude Code	Codex CLI	GitHub Copilot CLI	grok CLI
marketplace の登録と導入	確認済み（本家）	確認済み（0.144、2026年7月）	確認済み（1.0.75、2026年8月）	確認済み（0.2.118、2026年8月）
Skills（`SKILL.md`）	確認済み	確認済み	確認済み（明示的な呼び出し）。自然文での自動選択は条件付き（プラグインを絞った設定で3回中3回、多数のスキルを入れた通常設定で3回中0回）	確認済み（1.0.13 で23スキルを確認）
MCP サーバー	確認済み	未確認	確認済み（隔離した環境では、プロジェクトルートを環境変数で指定する必要があった）	確認済み
hooks	確認済み（2026年10月23日、`UserPromptSubmit` と `PreToolUse` の発火を確認）	確認済み（`UserPromptSubmit` と `Stop`。0.144 系、2026年8月）	一部確認済み（`SessionStart` のみ。他のイベントは未確認）	一部確認済み（プラグインの hooks は認識されるが発火しない。同梱スクリプトで全体設定へ展開すると発火することを 1.0.52 で確認）

表から言えることは2つです。

1つは、Skills はほぼどこでも動くことです。第1回で書いたとおり、SKILL.md は Agent Skills という公開仕様になっていて、ルールを Skills として書いておけば、ハーネスが変わっても書き直しは最小で済みます。

もう1つは、hooks の動き方がハーネスごとにばらばらなことです。Codex は、実行する hooks の種類をコマンド型と MCP ツール型に限っています。さらに、プラグインの hooks は導入しただけでは信頼されず、利用者が /hooks で定義を確認して信頼するまで実行されません。信頼は定義のハッシュに対して記録されるので、プラグインの更新で hooks の定義が変わると、信頼し直すまで実行されなくなります（Hooks）。grok CLI は、私たちが確かめた版ではプラグインの hooks を発火させないため、ff-dev-toolkit は全体設定へ展開するスクリプトを同梱しています。「縛る」ルールを hooks で配る場合は、ハーネスごとに発火を確かめた表を持ち、未確認の組み合わせや、更新の直後には縛りが効いていない可能性がある前提で運用します。

配布経路：誰が押し、更新は誰が追うか

要点：経路は3つあります。利用者が CLI で marketplace を登録する経路、管理者が設定で強制する経路、Claude の管理画面で GitHub から同期する経路です。経路ごとに「導入を誰が押すか」と「更新を誰が追うか」が違うので、両方を決めてから配ります。

経路	導入を押す人	更新を追う人	注意点
CLI で marketplace を登録	利用者本人	利用者本人。自動更新の既定値はハーネスごとに違う	ハーネスの数だけ登録が要る。Claude Code では、自分で追加した marketplace の自動更新は既定でオフ
管理者が設定で強制	管理者（Claude Code の managed settings、Codex のワークスペース設定の「Installed」）	管理者が配る設定で決め、取得は各端末（Claude Code は managed settings の `autoUpdate` で自動更新を指定できる）	強制できる範囲はハーネスごとに違う（第1回で整理）
Claude の管理画面で GitHub から同期	管理者が同期し、配布設定（必須／既定で導入／利用者が選ぶ／配布しない）を選ぶ	管理画面側が同期元を取り込み、利用者には次のセッションか再読み込みで届く	同期元は Private または Internal のリポジトリに限られる。同期に失敗すると、利用者は最後に同期した版のまま

自動更新の既定値は、ハーネスごとに次のように違います（2026年10月23日に各公式ドキュメントで確認）。

Claude Code： claude-plugins-official など Anthropic 公式の marketplace の多くと、claude.ai から追加した marketplace は既定でオン、自分で追加したものを含むそれ以外の marketplace は既定でオフです。利用者が /plugin の画面でオンにするか、管理者が managed settings の autoUpdate で指定します（Plugin loading reference）。
GitHub Copilot CLI： 組み込みの marketplace のプラグインだけが自動更新され、自分で追加した marketplace は、ユーザー設定か管理設定で autoUpdate: true を指定したときだけ自動更新されます。リポジトリ側の設定に書いた autoUpdate は無視されます（Copilot CLI plugin reference）。
Codex CLI： プラグイン単位の更新コマンドはなく、codex plugin marketplace upgrade で marketplace を取り込み直します（Codex CLI のコマンド一覧）。自動更新の既定値は、公式ドキュメントで確認できず未確認です。

3つ目の経路には、未確認の点も残っています。Claude のヘルプ記事は、自動同期が走る条件について、「版を上げた PR が既定ブランチにマージされたとき（既定ブランチへの直接の push では走らない）」とする記述と、「追従するブランチへの PR のマージや直接の push で走る」とする記述の両方を載せています（Manage plugins for your organization、2026年10月23日確認）。私たちの記録では、版を上げない PR を既定ブランチへマージすると、約10秒後に claude.ai 側でプラグインの更新が記録され、デスクトップアプリの写しにもその修正が入っていました。少なくとも、版を上げない PR のマージでも同期は走っています。既定ブランチへの直接の push で同期が走るかは未確認です。

私たちの社内では、この3つ目の経路と1つ目の経路が同じ端末に同居しています。Claude のデスクトップアプリには組織のプラグインディレクトリから配り、利用者が自分で導入を選ぶ設定にしています。一方で、Claude Code の CLI や Codex CLI では、各自が marketplace を登録して使っています。経路が増えると、同じ人の同じ端末に、別々の経路で届いた写しが並びます。これが次の版管理の節の出発点です。

版管理：「配った版」と「動いている版」は別物

要点：版番号はセマンティックバージョニング（semver）で上げ、互換性を約束する範囲を文書で決め、変更履歴は断片ファイルで集めます。そのうえで、動いている版が配った版とずれる3つの理由（セッションの保持・ハーネスごとの写し・同じ版番号での中身違い）を前提に、ずれに気づく仕組みを入れます。

版の上げ方：semver・互換性の約束・変更履歴

プラグインの版は plugin.json の version に書きます。Claude Code は、plugin.json の version、marketplace のエントリの version、取得元から求めた値（相対パスや Git の取得元なら、コミットを識別する commit SHA）の順で版を決め、その版が変わったときだけ利用者の写しを更新します（Plugin loading reference）。公式ドキュメントは、version を 1.0.0 に固定したまま新しいコミットを積んでも、利用者には届かないと明記しています。版を書かなければ、利用者は commit SHA を版としてコミットごとに追従します（Host and maintain a marketplace）。

ff-dev-toolkit は plugin.json に版を書き、0.x の semver で運用しています。semver は、互換性を壊す変更・機能の追加・修正のどれかによって上げる桁を変える規則です。ただし ff-dev-toolkit はまだ 1.0.0 より前なので、破壊的変更は版番号ではなく、変更履歴への記録で示しています。リリースの多い運用で決めておくべきことは3つです。

互換性を約束する範囲。 ff-dev-toolkit では、Skills の起動名、登録する hooks、導入先へ配置するファイルのパス、FF_ で始まる環境変数、FF_ で始まらない環境変数の5系統について、導入先が名前で依存してよい「契約」と、予告なく変えてよい「内部」を1つずつ区別して列挙しています（PUBLIC-SURFACE.md）。同じ系統の中でも、契約になるのは一部です。契約を壊す変更は、変更履歴の「破壊的変更」の節に、置き換え先と移行手順と一緒に書きます。
変更履歴の集め方。 並行して進む複数の PR が1つの CHANGELOG.md を直接編集すると、競合しやすくなります。私たちは PR ごとに changelog.d/ へ断片ファイル（Issue 番号・種別・名前を付けた1ファイル）を置き、リリースのときに集約しています。
版を上げるタイミング。 利用者が受け取る中身が変わるたびに版が変わるようにします。ここが崩れたときの話は、落とし穴の1件目で書きます。

動いている版がずれる3つの理由

版を正しく上げても、利用者の手元で動いている版は配った版とずれます。理由は3つあります。

1. セッションは起動時の版を使い続ける。 Claude Code は、動いているセッションの途中で更新が届いても読み込んだ版を使い続け、/reload-plugins か次の起動で新しい版に切り替えます（Plugin loading reference）。ff-dev-toolkit の README には、Claude のデスクトップアプリで既存の会話を再開すると古い写しに再接続される、という注意も書いています。

2. ハーネスごとに写しが別にある。 2026年10月23日の筆者の環境では、ff-dev-toolkit の版が、Claude Code の CLI（公開 marketplace から導入）で 0.162.0、Codex CLI（同）で 0.164.0、Claude のデスクトップアプリ（社内 marketplace を組織のプラグインディレクトリで同期）で 0.164.0 でした。1人の1台の端末の中でも、ハーネスと経路が違えば、版が揃うとは限りません。

3. 同じ版番号でも、中身が違うことがある。 同じ日に、デスクトップアプリの 0.164.0 と Codex CLI の 0.164.0 を比べると、24個のファイルの内容が異なり、デスクトップアプリ側にだけ存在するファイルが2個ありました。差分には、0.164.0 のリリース後に社内の既定ブランチへ入った修正が含まれていました。仕組みは落とし穴の1件目で説明します。

ずれに気づかせる仕組み

ずれを無くすことはできないので、利用者が気づける形にします。ff-dev-toolkit には、次の仕組みを入れています（詳細は ff-dev-toolkit の README）。更新通知と自動更新は、セッション開始時に走る hooks として Claude Code 向けに作っています。他のハーネスで同じように動くかは、前述の表の hooks の行のとおりです。

更新通知。 セッション開始時に公開リポジトリの最新リリースを確かめ、新しい版があれば通知します。更新するまで、日をまたぐたびに通知します。
marketplace の自動更新。 セッション開始時に、Claude Code の登録済みの marketplace とプラグイン本体の更新をバックグラウンドで実行します。自分で追加した marketplace は既定では自動更新されないため、この仕組みを含む版へ一度更新すれば、以降は各自の設定に依存せず追従します。反映は次のセッションからです。
版の照合スキル。 /ff-dev-toolkit:check-plugin-versions は、GitHub 上の plugin.json と、Claude Code の登録・デスクトップアプリの保存済みセッションを読み取り専用で比べます。古い照合スキルは自分自身が最新かを保証できないので、照合は最新の版を使える別のセッションから行う、という限界も README に明記しています。
導入先のゲート。 このサイトのリポジトリでは、push 前の検査（pre-push ゲート）が、レビュー用スクリプトとプラグインの版の整合を確かめ、ずれていれば push を止めます。

落とし穴集：実際に踏んだ4件

要点：4件のうち3件は、「版」か「場所」の扱いを誤ったことが原因でした。同じ版番号のまま中身を配る、版付きのパスを外から書き込む、処理を持つスクリプトを各リポジトリへコピーさせる、の3つです。残る1件は、公開リポジトリを組織配布の同期元にできないというプラットフォームの制約です。

ここからは、フィールフロウが実運用で踏んだ落とし穴を、症状・原因・対策の順に書きます。根拠の Issue は社内リポジトリ（非公開）のもので、番号は記録のためにリポジトリ名とあわせて示します。公開側で追える変更は、ff-dev-toolkit の CHANGELOG の版を添えます。

1. 同じ版番号で、中身の違う配布物が並んだ

症状： レビュー用スクリプトの照合が「版が一致しません」で止まるのに、表示される版は両方とも 0.149.0 で同じでした（2026年10月10日）。原因を辿る手がかりがありませんでした。
原因： 配布の経路ごとに、届く中身と版の決まり方が違っていました。社内 marketplace の marketplace.json では ff-dev-toolkit の source を相対パスにしており、marketplace は ref を指定せずに取り込んでいたため、配布物は既定ブランチ（develop）の先端です。リリース後に develop へ入った変更は、plugin.json の版を据え置いたまま配布物に入ります。デスクトップアプリには、この社内 marketplace を Claude の管理画面で同期して配っていました。Claude Code の公式ドキュメントは、claude.ai でホストする marketplace のプラグインは claude.ai が記録した版で扱い、plugin.json の version は読まないと説明しています（Plugin loading reference）。デスクトップアプリも同じ扱いだと私たちは推定しています。実際に、版が変わらなくても同期のたびに develop の先端が届いていました。一方、CLI のキャッシュは公開リポジトリから入れたもので、中身はリリース時点のままです。こうして、同じ 0.149.0 という版番号で中身の違う2つの配布物が、1台の端末に並びました。
対策： 照合の出力に内容の識別子を加え、版が同じで中身が違う場合に原因と対処を表示するようにしました（feelflow-plugins #2095 / #2096、2026年10月22日に解決）。これは原因を見つけやすくする対策で、ずれ自体は防げません。前節で書いたとおり、同じ状態は10月23日にも起きています。根本的には、配るブランチと版を上げるタイミングを揃える必要があり、この対策は2026年10月23日時点ではまだ入れていません。既定ブランチの先端を配るなら取り込みのたびに版を上げ、そうでなければ配布元をリリースのタグやブランチに固定します。Claude Code には「リリースチャネル」の機能はなく、安定版と先行版を分けたい場合は、異なる ref を指す2つの marketplace を用意します（Host and maintain a marketplace）。

2. 版のディレクトリを書き込んだ設定ファイルが、更新のたびに古くなった

症状： このサイトのリポジトリで、push 前の検査は成功と表示されたまま、検査の実行記録だけが黙って途切れました（2026年9月11日に2回）。後述の第1段の対策を入れた後は、プラグインが更新されるたびに push が拒否され、手作業で設定し直す必要がありました。観測台帳に記録した同じ原因の発生は、9月11日から28日までに計12回です。
原因： セットアップ時に、プラグインのキャッシュ内の版ディレクトリ（.../ff-dev-toolkit/0.100.0/ のような絶対パス）を設定ファイルに書き込んでいました。プラグインが更新されると、古い版のディレクトリはいずれ消えます。記録した例のほとんどで、設定ファイルが指していたのは Codex のキャッシュで、更新後には古い版のディレクトリが残っていませんでした（Codex が古い版をいつ消すかは、公式ドキュメントで確認できていません）。Claude Code の場合は、更新で古くなった版のディレクトリを14日後に削除します（Plugin loading reference）。どちらでも、版のディレクトリを書き込んだ設定ファイルは、いずれ存在しない場所を指します。
対策： 2段階で直しました。第1段では、手がかりがあるのに解決できないときは push を拒否するようにして、黙って劣化する経路を塞ぎました（feelflow-website-2026 #1864）。第2段では、レビュー用スクリプトに「いま有効な版の場所だけを返す」入口を足し（feelflow-plugins #1488、公開版 v0.102.0）、ゲートが実行時にその入口で解決するよう切り替えました（feelflow-website-2026 #1884、2026年9月30日）。これで、ゲートは版付きのパスに依存しなくなりました。版付きのパスは、入口が解決を拒否したときの予備としてだけ残しています。教訓は、プラグインの外から版付きのパスを固定して参照しないことです。プラグインの中からは、ハーネスが用意する変数を使います。Claude Code の ${CLAUDE_PLUGIN_ROOT} は版ごとに変わるプラグインのルートを、${CLAUDE_PLUGIN_DATA} は更新をまたいで残るデータ用のディレクトリを指します（Plugin loading reference）。Codex も互換のために同じ名前の変数を設定します（Hooks）。

3. レビューの入口がリポジトリごとに分岐し、Codex が無言で止まった

症状： Codex を使った別モデルのレビューが、50分以上1バイトも出力しないまま止まり、レビューを断念しました（2026年8月）。
原因： 2つ重なっていました。1つは、標準入力（stdin）を開いたまま codex exec を起動していたことです。公式ドキュメントによれば、プロンプトを引数で渡したうえで標準入力をパイプすると、codex exec は標準入力を追加の文脈として読みます（Non-interactive mode）。私たちの実測（Codex CLI 0.144.5）では、</dev/null で標準入力を閉じると9秒で完走し、開いたままだと、私たちが設けた60秒の制限時間内に終わりませんでした。開いたままの標準入力を待ち続ける挙動は、公式ドキュメントでは確認できていません。もう1つは、レビューを起動するスクリプトをプラグインが配っておらず、各リポジトリが自前で持っていたことです。調べると、7つのリポジトリで15個のファイルが13通りに分岐していて、2つは依存ファイルが欠けて起動できず、1つは標準入力を閉じていませんでした。
対策： レビューの入口を、共通の実行役へ処理を渡すだけの薄いスクリプトとしてプラグインに同梱し、セットアップで各リポジトリへ配置するようにしました（feelflow-plugins #406、公開版 v0.28.0）。このスクリプトが AI の CLI を直接起動しないことは、静的な検査で固定しています。教訓は、手順書だけでなく実行の処理もプラグインで配ることです。各リポジトリに置くのは処理を委譲するだけの薄い入口に限り、処理そのものはコピーさせません。コピーさせた処理は、その時点で版管理の外に出ます。ただし薄い入口も各リポジトリの写しなので、プラグイン側との版のずれは起きます。前節で書いた、版の整合を確かめるゲートはそのためのものです。

4. 公開リポジトリは、そのままでは組織に同期できなかった

症状： OSS として公開した ff-dev-toolkit を、Claude の組織のプラグインディレクトリ（管理画面の GitHub 同期）の同期元に指定できませんでした。
原因： github.com での GitHub 同期の対象は Private または Internal のリポジトリに限られ、Public のリポジトリは指定できません（Manage plugins for your organization）。さらに GitHub では、Public のリポジトリのフォークは Public になり、フォークの公開範囲だけを変えることもできません（About permissions and visibility of forks）。
対策： 組織で配る場合は、公開リポジトリを組織の Private リポジトリへ複製（ミラー）し、それを同期元にする手順を README に書きました（組織のプラグインディレクトリで配布する場合）。複製には GitHub の Import repository や、git clone --bare と git push --mirror を使います。ただし複製は、それ自体が版のずれの新しい発生源になります。公開側の更新を誰がいつ複製へ反映するかまで決めてから使います。複製しない選択肢もあります。Private か Internal でなければならないのは同期元のカタログ（marketplace のリポジトリ）で、プラグイン本体は、Public のリポジトリを github などの取得元として参照できます（同じヘルプ記事）。この方法なら本体を複製せずに済みます（私たちはまだ試していません）。

設計チェックリスト：配布前に決めておく7項目

要点：配布元・配るブランチ・版の規則・部品の対応表・更新の追い方・ずれの検出・外からの参照の7つを、最初のプラグインを配る前に決めます。多くは、後から変えると利用者全員の手元に手作業が発生します。

自社で設計するときは、次の7項目を配布前に決めてください。

配布元はどこか。 1つのリポジトリに1つの marketplace を置くか。Public か Private か。Claude の組織のプラグインディレクトリで配るなら、同期元の marketplace は Private か Internal にする（Public のプラグイン本体は、Private のカタログから取得元として参照するか、Private へ複製する）。
利用者は、どのブランチの中身を受け取るか。 既定ブランチの先端か、リリースのタグやブランチか。版を上げるタイミングと必ず揃える。経路によって版の決まり方が違うことも前提にする（Claude Code の公式ドキュメントでは、claude.ai でホストする marketplace のプラグインは plugin.json の版を読まない。デスクトップアプリへの同期でも、版を上げない変更が届くことを私たちは観測している）。
版の規則は何か。 semver の上げ方、互換性を約束する範囲（Skills の名前、hooks、環境変数、配置するファイルなど）、破壊的変更の記録の仕方、変更履歴の集め方。
どのハーネスで、どの部品が動くか。 ハーネス × 部品の表を、確認済み／未確認を分けて、確かめた版と日付つきで持ち続ける。
更新は誰が追うか。 経路ごとに、導入と更新を誰が押すか。ハーネスごとの自動更新の既定値。更新後に再起動を促す方法。Codex では hooks を信頼し直す手順も含める。
版のずれにどう気づくか。 更新通知、動いている版の照合、ゲートでの検査。同じ版番号で中身が違う状態を識別できるか。
プラグインの外から、版付きの場所を参照していないか。 セットアップで絶対パスを書き込む、処理を持つスクリプトを各リポジトリにコピーさせる、といった設計になっていないか。各リポジトリに置くのは、処理を委譲するだけの薄い入口に限る。

FAQ

要点：ハーネスごとにプラグインを分ける必要はなく、1つで配れます（Codex などは互換としての読み込み）。版は利用者に届く中身が変わるたびに上げます。社内向けと OSS は、社内側を正本にした一方向の同期で両立できます。

Q. Claude Code 用に作ったプラグインを、Codex や GitHub Copilot CLI 用に分けて作る必要はありますか？

2026年10月時点では、分けずに1つで配れます。私たちは Claude Code 形式の marketplace を、Codex CLI、GitHub Copilot CLI、grok CLI でもそのまま登録して使っています。ただし、Codex は .claude-plugin/ の置き場所を互換として読み、GitHub Copilot CLI はそこを探す場所の最後に置いています。どちらも、公式ドキュメントが案内する置き場所は別にあります（構成の節を参照。Codex のプラグイン形式は第1回で詳しく書きました）。ハーネスごとに分けて持つべきなのは、プラグインではなく、部品がどこまで動くかの記録です。

Q. プラグインの版は、いつ上げればよいですか？

利用者が受け取る中身が変わるたびに上げます。既定ブランチの先端を配っているなら、取り込みのたびに版を上げないと、同じ版番号で中身の違う配布物が並びます（落とし穴の1件目）。版を上げる回数を減らしたいなら、配布元をリリースのタグやブランチに固定します。版を書かずに commit SHA で追従させる方法もありますが、利用者が見る版の表記は人が読める番号ではなくなります。

Q. 社内向けのプラグインと、OSS として公開するプラグインを両立できますか？

できます。私たちは社内の Private リポジトリを正本にして、公開してよいファイルの許可リストと、社内情報を含むパターンの検査を通した一方向の同期で、ff-dev-toolkit だけを公開リポジトリへ写しています。公開側への反映は人が確認して行います。社内の Issue 番号やリポジトリ名が公開側に漏れないよう、公開用の変更履歴の書式も分けています。

まとめ

要点：1つのリポジトリを marketplace にすれば、複数のAIエージェントに同じプラグインを配れます（Codex などは互換としての読み込み）。ただし版は、セッションの保持・ハーネスごとの写し・同じ版番号での中身違いによってずれます。版の規則とずれの検出をセットで設計し、配る前にチェックリストの7項目を決めます。

1つの GitHub リポジトリを marketplace にすれば、同じ marketplace を Codex CLI、GitHub Copilot CLI、grok CLI にも登録して、Claude Code 形式のプラグインを配れます（Codex などは互換としての読み込みです）。難しいのは配ることではなく、配ったものが各自の手元で同じ版のまま動いているかを確かめることでした。セッションは起動時の版を使い続け、ハーネスは別々の写しを持ち、配布の経路によっては同じ版番号で中身が違う配布物が並びます。

だから、版をいつ上げるか、何を壊したら破壊的変更かを決め、更新通知・版の照合・ゲートで、ずれに気づける形にします。私たちが踏んだ4件の落とし穴のうち3件は、「版」か「場所」の扱いを誤ったことから起きていました。配布前に、チェックリストの7項目を決めておいてください。

第3回「ff-dev-toolkitの実例：AIにルールを守らせ、経験を次の開発へ残す」では、プラグインの中に何を入れるかを、品質ゲートとACEによる知見の再利用から紹介しています。プラグインの配布設計や、Claude Code / Codex の社内展開についてご相談があれば、お問い合わせからご連絡ください。

参考資料・データソース

確認範囲：ハーネスの仕様に関する記述は、各公式ドキュメントの記述を2026年10月23日に確認しました。ハーネスごとの部品の動作は、社内 marketplace の README に記録した実測（版と時期はセル内に記載）と、筆者の環境での2026年10月23日の観測に基づきます。落とし穴の根拠は、フィールフロウの社内リポジトリ（非公開）の Issue と、公開リポジトリ ff-dev-toolkit の CHANGELOG です。

Claude Code / Claude

Claude Code Docs. Marketplace reference. marketplace.json の置き場所と、プラグインの取得元（source）の種類。
Claude Code Docs. Plugin loading reference. 版の決まり方（plugin.json → marketplace のエントリ → 取得元から求めた値）、claude.ai でホストする marketplace では plugin.json の版が読まれないこと、キャッシュの置き場所と ${CLAUDE_PLUGIN_ROOT} / ${CLAUDE_PLUGIN_DATA}、古い版のディレクトリを14日後に削除すること、自動更新の既定値、セッション中の更新と /reload-plugins。
Claude Code Docs. Host and maintain a marketplace. 版を据え置いたコミットが利用者に届かないこと、リリースチャネルを2つの marketplace で作る方法、ref / sha による固定。
Claude Help Center. Manage plugins for your organization. 組織のプラグインディレクトリ、GitHub 同期が Private / Internal のリポジトリに限られること、配布設定の種類、自動同期の条件。
Agent Skills. Specification. SKILL.md の公開仕様。

OpenAI Codex / GitHub Copilot

OpenAI Developers. Package your plugin. Codex の marketplace の正式な置き場所（.agents/plugins/marketplace.json）と互換の置き場所、プラグインのキャッシュ。
OpenAI. Codex CLI のコマンド一覧. codex plugin marketplace add / codex plugin marketplace upgrade / codex plugin add。
OpenAI. Hooks. 実行される hooks の種類（コマンド型・MCP ツール型）、プラグインの hooks の信頼と定義変更時の再確認、プラグインの hooks に渡される環境変数。
OpenAI. Non-interactive mode. codex exec がパイプされた標準入力を読む仕様。
GitHub Docs. Copilot CLI plugin reference. marketplace.json を探す順番（.claude-plugin/ は最後）、プラグインの自動更新の既定値と autoUpdate。
GitHub Docs. About permissions and visibility of forks. Public リポジトリのフォークは Public になり、フォークの公開範囲だけは変えられないこと。

フィールフロウ

feel-flow/ff-dev-toolkit（GitHub、Public、Apache-2.0）. 他のツールで使う手順、組織のプラグインディレクトリで配布する場合の注記、更新通知・自動更新・版の照合スキルの説明。
ff-dev-toolkit. CHANGELOG.md. v0.28.0（2026年8月11日、レビュー入口のスクリプトを同梱）、v0.102.0（2026年9月11日、有効な版の場所を返す入口を追加）ほか。リリースの回数は Releases で確認。
ff-dev-toolkit. PUBLIC-SURFACE.md. 互換性を約束する範囲（契約）と内部の区別。
社内リポジトリ（非公開）の Issue：feelflow-plugins #406 / #1488 / #2095 / #2096、feelflow-website-2026 #1864 / #1884。
社内 marketplace feelflow-plugins（Private）の登録プラグイン数と README の実測表、筆者の環境（Claude Code 2.1.308、Codex CLI 0.163.0、GitHub Copilot CLI 1.0.101、grok CLI 1.0.62）でのプラグインのキャッシュとデスクトップアプリの写しは、2026年10月23日に確認。