数百名がClaude Codeを使う組織で、チームごとのスキル・エージェント資産を1つのプラグインマーケットプレイスに統合し、約10ヶ月運用した実例がある。全プラグインの情報を1枚の設定ファイルに集約した瞬間、コンフリクト・登録漏れ・構造ミスの見逃しという5つの課題が噴き出した。そこで採られた対策は「手で編集しない」という一点に集約される。個人で複数プロジェクトを回す運用にも、そのまま持ち込める型がある。
ZOZO TECH BLOGの事例から、共通設定ファイルを複数の書き手（あるいは複数の未来の自分）が触るときに何が壊れるかを先回りして知り、「生成する・検証してから通す・可視化する」という3段構えの型を、一人運用のポートフォリオにも使える形で取り出したもの。
ZOZO TECH BLOGが公開した事例では、数百名がClaude Codeを使う組織で、チームごとに閉じていくスキル・エージェント資産を横断共有するために、1つのプラグインマーケットプレイスを構築している。仕組みの核はリポジトリルートの.claude-plugin/marketplace.jsonで、これが全プラグインのカタログを一元管理する。各プラグインは個別に.claude-plugin/plugin.jsonというメタデータを持ち、マーケットプレイスはこれらを集約する形になっている。
ディレクトリ構成もチーム単位で分離されていて、common-plugins/（全社共通）と各チーム名を冠したxxx-plugins/を並べることで、プラグインの置き場所を見ただけでメンテナンス責任の所在がわかるように設計されている。運用開始は2025年下期、記事公開時点の2026年8月で約10ヶ月が経過し、対象スキル数は73件に達している。大規模なトラブルは起きていないというが、その裏には後述する試行錯誤があった。
「共通のカタログファイルを持つ」という発想そのものは自然だが、実際に複数チームで運用すると、以下の5つの課題が具体的に噴き出した。
プラグインをフラットに並べただけでは、どのチームがどのプラグインを保守しているのかが誰にもわからなくなる。
全プラグインの情報を1つのJSONファイルに集約しているため、複数のPRが同時に走るとほぼ確実にコンフリクトが起きる。
JSONの構文エラーやフィールドの欠落が人間のレビューでは検出されず、マージされた瞬間に全チームへ波及する。
開発者寄りの説明文だと「やりたいこと」で検索できず、既に誰かが作った機能をまた別のチームが作ってしまう重複が起きる。
自分の変更が他チームでどれだけ使われているか見えないため、「直していいのか」の判断が先送りされ続ける。
共通する原因は1つ。「共通ファイルはみんなで手で編集するもの」という前提そのものが、書き手が増えるほど壊れていく。
対策は「人間が直接 marketplace.json を編集する場面をなくす」方向に一貫している。
自動生成：marketplace.json をプラグイン単体の plugin.json から機械的に再生成する仕組みに変えた。人間はもう共通ファイルを直接触らない。これだけでコンフリクトと登録漏れの両方が構造的に起きなくなる。静的バリデーション：CI上でJSON構文・必須フィールド・プラグイン名の重複・SKILL.md のフロントマターを自動チェックする。人間のレビュー精度に依存せず、壊れた構造はマージ前に機械的に止める。スキルインデックス：LLMを使って「想定される作業フレーズ」をあらかじめ生成しておき、開発者向けの説明文とは別に「やりたいこと」ベースでクライアントサイド検索できるようにした。@claude の自動チェック：破壊的変更の検出とマーケットプレイス規約への適合をPRコメントとして自動で行う。
約10ヶ月の運用で、修正・改善のためのPRが全体の6割近くを占めているという。これは「壊れて直す」を繰り返しながら、規約とCIチェックそのものを育て続けてきた運用の跡と読める。
個人開発者は複数チームではない。だが複数プロジェクト・複数スキルを自分一人で横断管理する場面は普通にある——このポートフォリオ自体がそうだ。FLOW・SURPLUS・toto・アプリ群を横断する_dashboard/facts.jsonや各種レジストリファイルは、書き手が「今日の自分」と「1ヶ月前の自分」に分かれているだけで、構造としては複数チームの共通ファイルとまったく同じ壊れ方をする。
一般化できる設計パターンは3つに絞れる。共通ファイルは人間が直接編集する対象ではなく、個々の単位から生成する対象にすること。変更は検証してから反映する経路を1本に固定すること。そして影響範囲を可視化し、直す判断を先送りしないこと。
これは公開中の記事44本を壊さず一括更新する｜マーカーコメント＋dry-runの型で書いた思想の裏返しでもある。あちらは「差分編集を安全にする」型（マーカー＋冪等＋dry-run）、今回は「そもそも人間が編集しない」型（生成＋CI検証）。どちらも共通しているのは、共通ファイルの正しさを人間の注意力に依存させないという一点だ。
複数チームの共同運用も、一人が時間差で編集する個人開発も、共通ファイルが壊れる理由は同じだった——「人間が正確であること」に依存する設計だったからだ。