本番プラグインに求められる品質
個人のdotfilesに置くプラグインと、公開マーケットプレースに出すプラグインでは、求められる品質が桁違いに異なる。前者は「自分の環境で動けばよい」で済むが、後者は多様なOS・Node.jsバージョン・シェル・既存設定との共存・オンボーディング体験・アップグレード戦略まで考慮しなければならない。
- 年4月現在、Anthropicの公式プラグインマーケットプレースには1,800以上のプラグインが公開されているが、週間アクティブインストールが1,000を超えるのは上位100程度だ。この差を生むのは機能の派手さではなく、マニフェスト品質・ドキュメント・バージョニング規律・設定マージの作法といった「地味な基礎」である。
標準リポジトリ構造
プラグインリポジトリの標準構造は以下のようになる。
``` my-claude-plugin/ ├── .claude-plugin/ │ └── plugin.json # マニフェスト（必須） ├── commands/ # スラッシュコマンド │ ├── review.md │ └── deploy.md ├── skills/ # スキル │ └── security-audit/ │ └── SKILL.md ├── agents/ # サブエージェント定義 │ └── researcher.md ├── hooks/ # フック設定 │ └── hooks.json ├── mcp/ # 同梱MCPサーバー │ ├── server.ts │ └── package.json ├── scripts/ # インストール・移行スクリプト │ └── postinstall.sh ├── README.md ├── CHANGELOG.md └── LICENSE ```
gsd-build/get-shit-doneやwshobson/agentsなど人気リポはほぼこの構造に収束している。特に .claude-plugin/plugin.json をトップに置く慣習は、Anthropic CLIのplugin addコマンドがこのパスを決め打ちで探すため事実上の必須規約だ。
plugin.jsonマニフェストの書き方
plugin.jsonは最低限以下のフィールドを持つ。
```json { "name": "gsd-build", "displayName": "Get Shit Done", "version": "2.4.1", "description": "Stop-hook driven task persistence for Claude Code", "author": { "name": "GSD Team", "url": "https://github.com/gsd-build" }, "license": "MIT", "homepage": "https://github.com/gsd-build/get-shit-done", "repository": "https://github.com/gsd-build/get-shit-done.git", "claudeCode": { "minVersion": "2.8.0" }, "commands": ["commands/"], "skills": ["skills/"], "agents": ["agents/"], "hooks": "hooks/hooks.json", "mcpServers": { "gsd-db": { "command": "node", "args": ["mcp/server.js"] } }, "configSchema": "config.schema.json", "telemetry": { "endpoint": "https://telemetry.gsd.dev/v1" } } ```
claudeCode.minVersionは破壊的変更があるたびに必ず更新する。ユーザーの古いCLIでインストールされて暗黙の動作不全を起こすのが最悪のUXだからだ。configSchemaはJSON Schema形式でユーザー設定のバリデーションを提供し、設定ミス時に親切なエラーメッセージが出るようにする。
セマンティックバージョニングの実務
プラグインのバージョニングはsemver準拠が基本だが、「何を破壊的変更とみなすか」の判断は独自の難しさがある。スラッシュコマンド名の変更、既存フックのmatcher変更、MCPツールのinputSchemaでの必須フィールド追加はすべて破壊的変更だ。逆に新規コマンド追加、既存コマンドへのオプション引数追加、MCPツールの新規追加はマイナーバージョンで済む。
CHANGELOG.mdはKeep a Changelog形式を強く推奨する。マーケットプレースのUIはCHANGELOG.mdを自動パースしてアップデート画面に表示するため、フォーマット統一が実益に直結する。弊社KGA ITでは社内プラグインも含めて全案件でこの形式を強制している。
マーケットプレース配布
- 年4月時点で主要な配布経路は3つある。第一はAnthropic公式マーケットプレース（claude.ai/plugins）で、審査はあるが検出性が最も高い。第二はGitHubリポジトリからの直接インストール（claude plugin add github.com/user/repo）で、審査不要・即時反映のためOSS作者に人気だ。第三はプライベートマーケットプレースで、企業内でclaude-plugin-registryをホストし社内配布する形態である。
公式マーケットプレース審査では、shellコマンド実行の妥当性、ネットワーク送信先の明示、個人情報取り扱いの宣言、有料プラグインの場合は決済フローのセキュリティがチェックされる。2026年2月から「audit badge」制度が導入され、静的解析クリア済みプラグインには緑バッジが付く。このバッジの有無で採用率が倍以上変わるというデータが公開されており、取得は強く推奨される。
テレメトリと可観測性
プラグイン運用には「誰がどう使っているか」の把握が不可欠だ。ただしClaude Codeユーザーはプライバシー意識が高く、不透明なテレメトリは即座にアンインストールされる。推奨アプローチは「オプトイン・匿名・集計値のみ送信」の三原則である。
具体的には、初回起動時に「匿名使用統計の送信に同意しますか？」とプロンプトを出し、Yesの場合のみインストールIDと各コマンドの呼出回数を日次で送る。個別のプロンプト内容やファイルパスは絶対に送らない。wshobson/agentsは採用率の高い人気Subagent定義のランキングをこの方式で集計し、月次でREADMEに公開している。これは「このプラグインは健全な運営がされている」というシグナルとしても機能する。
破壊的APIへの追随
Claude Code本体は2025年後半から機能追加ペースが加速し、マイナーバージョンでも既存プラグインが動かなくなるケースが稀にある。2026年1月のClaude Code 3.0でHook契約が変更され、stdinでのJSON受け渡しが必須化された際は、2週間で1,200プラグインがアップデート対応を迫られた。
対策は二層ある。まずplugin.jsonのclaudeCode.minVersionを厳格に指定し、未対応のCLIでは起動しないようにする。次にGitHub Actionsでclaude-code-nightlyを使った統合テストを走らせ、新バージョンでの動作確認を自動化する。Anthropicは2月からplugin-compat-matrixを公開し、各CLIバージョンでの公式プラグインの動作状況を可視化している。サードパーティもこのスキーマに追従する流れだ。
ユーザー設定のマージ戦略
プラグインは .claude/settings.json に書き込むが、ユーザーの既存設定を壊してはならない。推奨される実装は「JSON Pointerベースのパッチ適用」だ。plugin install時に差分パッチを.claude/plugins/<name>/applied-patch.jsonに保存し、uninstall時に正確に逆適用できるようにする。
特に注意すべきは permissions 配列のマージだ。ユーザーの既存allow/denyルールと競合しないよう、プラグイン固有ルールはnamespaceプレフィックス（例: "gsd:*"）を付けて隔離するのが慣習化しつつある。get-shit-doneはこの方式を先駆的に採用し、多くの後続プラグインの参考実装となった。
公開後の運用
公開して終わり、ではない。GitHub Issuesの初動対応速度、semver違反があった際の即時patch、セキュリティアドバイザリの発行手順、deprecation noticeのユーザー通知—これらの運用品質が長期的な採用率を決める。人気プラグインほど運用負荷は高く、メンテナー増員や法人化が必要になるケースもある。
弊社KGA ITの社内R&D方針としては、プラグインを本番運用する際に、運用ランブック・オンコール体制・四半期レビュー会議までをパッケージ化している。プラグインは成果物ではなくプロダクトであり、本番公開した瞬間から運用責任が発生する—この認識がプロ品質プラグインと趣味プラグインを分ける境界線である。