結論から書くと、Claude Code のカスタム機能をチームに配るなら、もう .claude/ ディレクトリのコピペで済ませる時代ではないです。Claude Code v2 系で plugin と marketplace が正式機能になり、Skill / Agent / Hook / MCP / LSP をひとまとめにして git や npm 経由で配布できるようになりました。私自身も社内で「便利スキルだけ配って終わり」だったところを、marketplace.json 化したらバージョン管理と更新がだいぶ楽になりました。
とはいえ公式ドキュメントのCreate pluginsとCreate and distribute a plugin marketplaceを行ったり来たりしないとつながりが見えづらく、最初は「plugin.jsonとmarketplace.jsonのどっちに何を書くんだ？」となりがちです。今回は最小構成からはじめて、ローカルテスト・GitHub 配布・version 管理の落とし穴まで一気通貫で整理しました。バージョンは記事執筆時点の Claude Code v2 系（claude --version で 2.x.x と出るもの）を前提にしています。
plugin と「.claude/直置き」の違いを整理する
そもそも ~/.claude/skills/foo/SKILL.md や .claude/commands/foo.md に置く方式と plugin 化は何が違うのか。公式ドキュメント When to use plugins vs standalone configuration の比較表を下敷きに自分の言葉で並べ直したのがこちらです。
| 観点 | standalone (.claude/) | plugin |
|---|---|---|
| スキルの呼び出し名 | /hello | /plugin-name:hello （名前空間付き） |
| 共有のしやすさ | 手でコピペ／Git submodule | /plugin install 一発 |
| 更新 | 各人が pull して同期 | marketplace 側で更新→各環境が自動取得 |
| バージョン管理 | 事実上なし | plugin.json の version または commit SHA |
| 向いている用途 | 個人ワークフロー、PoC | チーム配布、コミュニティ公開 |
名前空間がついて回ることに注意
plugin にすると、スキル名は必ず /<plugin-name>:<skill-name> 形式になります。短いコマンドで呼びたいうちは standalone のままが正解で、判断を後回しにすると「自分しか使わないのにフルパスが面倒」になりがちです。
まず standalone、あとで plugin に昇格、が定石
公式ドキュメントもConvert existing configurations to pluginsで「standalone から始めて、共有したくなったら plugin に変換しろ」と推奨しています。Skill 単体の作り方は別記事のClaude Code Skillの作り方—SKILL.md設計とtrigger発動の勘所にまとめたので、まず .claude/skills/ で書いて安定したら plugin に昇格、が摩擦の少ない順序だと思います。
最小構成のplugin.jsonを作る
plugin の本体は、ディレクトリ直下にある .claude-plugin/plugin.json 一枚です。サジェストでもよく出る「claude code plugin 作り方」を一行で答えるなら「.claude-plugin/plugin.json を置く」が正解。
必須フィールドはnameとdescriptionだけ
{
"name": "my-first-plugin",
"description": "A greeting plugin to learn the basics",
"version": "1.0.0",
"author": {
"name": "Your Name"
}
}このファイルを my-first-plugin/.claude-plugin/plugin.json として置き、同じプラグインルート直下に skills/hello/SKILL.md を作れば、それがそのまま /my-first-plugin:hello スキルになります。
commands/とskills/を「.claude-plugin/の中」に入れない
公式が Common mistake としてわざわざ警告している地雷です。.claude-plugin/ の中に入れるのは plugin.json だけ。skills/・agents/・hooks/・.mcp.json・.lsp.json はプラグインルート直下に置きます。最初うっかり .claude-plugin/skills/ に入れたらスキルが一切ロードされず、エラーも出ない種類のミスで気付くのに10分かかりました。
my-first-plugin/
├── .claude-plugin/
│ └── plugin.json ← ここだけ
├── skills/
│ └── hello/
│ └── SKILL.md ← プラグインルート直下
├── agents/ ← 同上
├── hooks/
│ └── hooks.json
└── .mcp.json ← 同上versionを書くか、書かないか
判断が分かれるのが version の扱いです。公式ドキュメントのVersion resolution and release channelsによると、version を書いた場合はその文字列を bump したときだけユーザーに更新が届く挙動になります。省略すると git 配布では commit SHA がそのまま version 扱いになり、コミットするたび「新バージョン」として配布されます。
- こまめに直したい開発初期 → 省略して SHA に任せる
- 安定運用フェーズ → 明示して semver で管理する
–plugin-dirでローカル検証する
marketplace に上げる前に、ローカルで挙動を確認するための専用フラグがあります。
–plugin-dirの使い方
claude --plugin-dir ./my-first-pluginLoaded 1 plugin from --plugin-dir:
- my-first-plugin v1.0.0
skills: hello
> /my-first-plugin:hello Alex
Hi Alex! How can I help you today?フラグは複数指定でき、--plugin-dir ./a --plugin-dir ./b のように同時ロードして相互作用も確認できます。
/reload-pluginsで再起動なしに反映する
SKILL.md を編集しても、Claude Code は自動でリロードしません。セッションを開いたまま /reload-plugins を打つと、skills・agents・hooks・MCP サーバ・LSP サーバまで一括でリロードされます。地味に開発体験を底上げしてくれるコマンドで、これを知らないと毎回 Claude Code を再起動する羽目になります。
同名プラグインがインストール済みでもローカルが優先される
触ってみないと気づきにくい仕様として、すでに marketplace 経由でインストール済みのプラグインと同じ name を --plugin-dir で渡すと、そのセッションだけローカル版が優先されます。配布済みのプラグインを直したいときに、いったんアンインストールしなくていいのは便利です（managed settings で強制有効化されているものだけは例外）。
marketplace.jsonでカタログを定義する
plugin 単体では「自分の手元で動く配布物」止まりで、第三者が /plugin install で入れるには marketplace という上位の概念に乗せる必要があります。
最小のmarketplace.json
marketplace は、ルートに .claude-plugin/marketplace.json を持つ git リポジトリです。中身は plugin の一覧表。
{
"name": "my-plugins",
"owner": {
"name": "Your Name"
},
"plugins": [
{
"name": "quality-review-plugin",
"source": "./plugins/quality-review-plugin",
"description": "Adds a /quality-review skill for quick code reviews"
}
]
}ディレクトリ構成はこうなります。
my-marketplace/
├── .claude-plugin/
│ └── marketplace.json
└── plugins/
└── quality-review-plugin/
├── .claude-plugin/
│ └── plugin.json
└── skills/
└── quality-review/
└── SKILL.md必須フィールドはname/owner/plugins
公式ドキュメントのMarketplace schemaによると、必須は name・owner・plugins の3つだけ。name はインストール時に /plugin install <plugin-name>@<marketplace-name> の右側に出てくる識別子で、kebab-case 推奨です。
ここで罠が一つあって、claude-plugins-official・anthropic-marketplace・agent-skills など Anthropic 公式が予約済みの名前は使えません。official-claude-plugins のように「公式っぽさ」で釣る名前もブロック対象になっています。素直に acme-tools のような自分の組織名や用途で命名するのが安全です。
plugins[].sourceで取得元を決める
各 plugin エントリの source は、plugin の実体をどこから取ってくるかを決めるフィールドです。型は string か object で、主要な選択肢はこんな感じ。
| 種類 | 書き方 | 用途 |
|---|---|---|
| 相対パス | "./plugins/foo" | marketplace と同じ repo に同梱 |
| github | {"source":"github","repo":"owner/repo"} | 別 repo の plugin を参照 |
| git URL | {"source":"url","url":"https://..."} | GitLab や自前 git サーバ |
| git-subdir | {"source":"git-subdir","url":"...","path":"plugins/foo"} | モノレポの一部だけ sparse clone |
| npm | {"source":"npm","package":"..."} | npm レジストリ経由で配布 |
相対パスの解決先は marketplace ルートであって、marketplace.json の置き場所ではありません。./plugins/foo と書けば <repo>/plugins/foo を指します。../ で marketplace ルート外を参照することは禁止です。
GitHubで公開してインストールしてもらう
marketplace.json ができたら、あとは git push して相手に URL を渡すだけ。
ユーザー側の3コマンド
/plugin marketplace add owner/marketplace-repo
/plugin install quality-review-plugin@my-plugins
/quality-review初回は marketplace add、以降は install だけで増やしていけます。更新は /plugin marketplace update。最近のリリースでは /reload-plugins やバックグラウンド自動更新が、不足している依存プラグインを add 済み marketplace から自動インストールするようになっています。
private repoもそのまま使える
社内配布なら marketplace を private な GitHub リポジトリに置けばOK。Claude Code は gh auth ログイン済みのトークンを使うので、各メンバーが gh auth login していれば追加設定なしです。extraKnownMarketplaces 設定でリポジトリの .claude/settings.json に書いて自動認識させることもできます。
公式マーケットへの提出フォーム
もう一歩進んで Anthropic 公式の claude-plugins-official マーケットに載せたい場合は、Claude.ai 側の claude.ai/settings/plugins/submit または Console 側の platform.claude.com/plugins/submit から申請する専用フォームが用意されています。要件は最新ドキュメント側で随時更新されているので、出す直前に再確認した方が安全です。
version管理のハマりどころ
plugin の運用で一番事故が起きやすいのが version 周りなので、ここはしっかり書きます。
plugin.jsonとmarketplace.jsonの両方にversionが書ける
そう、両方にあります。優先順位は marketplace.json の plugin エントリに書かれた version > plugin.json の version > 省略時は git commit SHA。同じプラグインを複数の marketplace から別バージョンとして配ることもできるので、安定版マーケットには 1.2.0 を、開発版マーケットには未指定で SHA 追従、みたいな運用も可能です。
SHA運用は「コミット＝リリース」になる
version を書かずに git 配布すると、README の typo 修正コミットでも更新通知が飛びます。SHA 運用にするなら、関係ないファイルは別ブランチで作業するか、配布リポジトリを README 用と plugin 本体で分ける切り分けが要ります。
strictモードのデフォルトはtrue
marketplace.json の plugin エントリには strict 真偽値があり、デフォルト true では plugin.json 側が正として扱われます。両方に commands や hooks を書いて差分が出てバグった時はここを疑ってください。
仕上げと検証ツール
配布前にやっておくと事故が減るチェックをまとめます。
claude plugin validateを通す
Claude Code v2 系には claude plugin validate という CLI サブコマンドがあり、plugin.json や marketplace.json の構造を静的にチェックできます。最近のリリースで $schema・version・description を marketplace.json のトップレベルに書いても通るように緩和されたので、エディタ補完を効かせるなら $schema を入れておくのが楽です。
claude plugin validate ./my-marketplace✓ marketplace.json: valid
✓ plugins/quality-review-plugin/plugin.json: valid
✓ All plugin sources resolve
Validation passed (1 plugin, 1 skill).plugin.jsonのメタ情報を埋める
/plugin メニューでの表示が貧弱だとインストール率が下がります。plugin.json の homepage・repository・license・keywords を埋めるだけでも見た目はだいぶ変わります。
名前空間を意識して短くする
呼び出しが /<plugin-name>:<skill-name> で固定される以上、my-awesome-team-tools みたいに長くすると毎回打つのが苦痛になります。10文字前後・kebab-case を目安に。
まとめ
- plugin は
.claude-plugin/plugin.json一枚を置けば成立する。skills/・agents/・hooks/は プラグインルート直下で、.claude-plugin/の中に入れない - standalone との大きな違いは 名前空間とバージョン管理。短いコマンド名で呼びたいうちは standalone、共有・配布したくなったら plugin へ昇格
- ローカル検証は
claude --plugin-dir ./xxx。編集後は/reload-pluginsで再起動なしに反映できる - 配布には
.claude-plugin/marketplace.jsonを持つ git リポジトリを用意する。name・owner・pluginsが必須で、Anthropic 公式名は予約済み sourceは相対パス・github・git URL・git-subdir・npm から選ぶ。相対パスは marketplace ルートからの解決- version は
plugin.json・marketplace.json・commit SHA の三段階。SHA 運用にすると「コミット＝リリース」になる点に注意 - 配布前に
claude plugin validateを必ず通し、strict: true前提でフィールドをplugin.json側に集約しておく
関連トピックとして、plugin の中身の主役になる Skill 設計（Claude Code Skillの作り方）や、Hook を組み合わせた自動化、permissions の設計（Claude Code permissions—allow/denyの落とし穴と評価順序）と合わせて読むと、配布物としての完成度がだいぶ上がると思います。
