Claude Codeプラグインを自作してチームに配る手順

01Claude Codeプラグインとは？何ができる拡張か

Claude Codeプラグインは、Claude Codeに機能を追加するための自己完結したパッケージです。1つのディレクトリに複数の部品をまとめ、コマンドで導入・共有・更新できます。公式ドキュメントによれば、プラグインに含められる部品はスキル、エージェント（サブエージェント）、フック、MCPサーバー、LSPサーバー、バックグラウンド監視の6種類です。ひとことで言えば、自分やチームの「よく使う設定一式」を配布可能な形に固めたものです。

プラグインの実体は、ディレクトリの中に .claude-plugin/plugin.json という設定ファイル（マニフェスト）を置いた構造です。マニフェストにはプラグイン名・説明・バージョンなどを書きます。スキルやエージェントは、このマニフェストの外側、プラグインの直下に skills/ や agents/ として並べます。MCPサーバーを束ねることもでき、チームに配れるMCP環境の入れ物にもなります。束ねる前提となるスキル・サブエージェント・スラッシュコマンドの違いと使い分けはClaude Code サブエージェントとスキルの違い・使い分けで整理しています。MCPサーバー自体の選び方はweb制作におすすめのMCPサーバー厳選5選で扱っています。

02プラグインと.claude直置きは何が違う？

Claude Codeでスキルやフックを足す方法は2つあり、プロジェクトの.claudeディレクトリに直接置く「直置き」と、パッケージにまとめる「プラグイン」に分かれます。1つのプロジェクトで個人的に試すだけなら直置きで十分です。チームで配る・複数プロジェクトで使い回す・バージョンで更新を管理する、といった段階に来たらプラグインに切り替えます。判断の分かれ目は「共有と再利用が要るか」です。

公式は「まず.claudeの直置きで素早く試し、共有する段になったらプラグインに変換する」という進め方を推奨しています。この順序なら、作り込む前の実験は身軽に、配る段では整った形に、と使い分けられます。

03プラグインの使い方｜追加とインストールの手順

既存のプラグインを入れるには、まずプラグインの一覧元であるマーケットプレイスを追加し、そこからインストールします。Claude Codeには初回起動時に公式マーケットプレイス（claude-plugins-official）が自動で登録されます。コミュニティ版を使う場合は自分で追加します。操作はすべて/pluginから行えます。

インストール後は、プラグインが持つスキルが/プラグイン名:スキル名の形で使えるようになります。導入したスキルの一覧は/helpのCustom commandsタブで確認できます。プラグインで配れるスラッシュコマンドの中身については非エンジニアのClaude Codeスラッシュコマンド12選もあわせて読むと、何を束ねると便利かのイメージがつかめます。

04プラグインにすると作業はどう変わる？

プラグイン化で実務がどう変わるのかを、公式の仕様からの想定として整理します。ここは筆者が断定する実測ではなく、仕組みの差からの見立てである点を先に明記します。

まず、チーム全員の設定がそろいやすくなると想定されます。直置きは各自がファイルをコピーするため、誰かのだけ古い、という食い違いが起きがちです。プラグインはマーケットプレイス経由で配り、バージョンを上げると更新が届く設計のため、「同じコマンドが全員の手元で同じように動く」状態を保ちやすくなります。レビュー基準やデプロイ手順を全員に徹底したい場面で、この差が大きくなります。

次に、名前の衝突が減ると想定されます。プラグインのスキルは/プラグイン名:スキル名と名前空間が付くため、別々のプラグインが同じhelloというスキルを持っていても混ざりません。複数のプラグインを併用する運用ほど、この名前空間の恩恵が大きくなります。逆に、1人で1プロジェクトを触るだけなら直置きの短い名前の方が身軽で、無理にプラグイン化する必要はありません。

05自作プラグインの作り方｜最小構成

自作は、マニフェストを1つ置くだけで始められます。プラグイン用のフォルダを作り、その中に.claude-plugin/plugin.jsonを置きます。注意点として、commands/やskills/などの部品は.claude-plugin/の中ではなく、プラグインの直下に置きます。これを間違えると部品が読み込まれません。まずは最小のマニフェストです。

my-plugin/
├── .claude-plugin/
│   └── plugin.json      ← マニフェストだけここ
└── skills/
    └── alt-gen/
        └── SKILL.md     ← 部品は直下に置く

plugin.jsonの中身は、名前・説明・バージョンの3つがあれば十分です。nameがスキルの名前空間になります。

{
  "name": "my-plugin",
  "description": "サイト制作の定型作業をまとめた社内プラグイン",
  "version": "1.0.0"
}

スキル本体はskills/スキル名/SKILL.mdに、YAMLの説明文と指示を書きます。テスト時はclaude --plugin-dir ./my-pluginでそのフォルダを読み込ませ、変更したら/reload-pluginsで再読み込みします。既に.claudeに置いてあるコマンドやスキルがあるなら、それらをcp -r .claude/commands my-plugin/のようにプラグイン直下へコピーするだけで移行できます。

06実践：サイト制作の定型作業をプラグイン化して配る

ここからは、実際に業務でやっている使い方に寄せて、サイト制作の定型作業を自分のプラグインにまとめ、チームに配る手順を具体的な粒度で示します。題材は「画像のalt文をまとめて下書きする」という、LP制作で毎回発生する地味な作業です。これを1つのスキルにして、プラグインとして社内のgitリポジトリから配ります。

手順1：スキルを1つ書いてプラグインに入れる

skills/alt-gen/SKILL.mdに、alt文を作る指示を書きます。$ARGUMENTSでファイル名や周辺見出しを受け取れます。

---
description: 画像のalt属性を日本語20字以内で下書きする。装飾目的なら空にする。
---

次の画像情報「$ARGUMENTS」から、日本語のalt属性を20字以内で1つ提案してください。
装飾目的の画像なら空文字を返し、その理由を1行添えてください。

これで/my-plugin:alt-gen ロゴ画像 / 見出し=会社概要のように呼び出せます。同じ要領で「レスポンシブの崩れをチェックする観点リスト」や「メタディスクリプション案を出す」スキルも足せます。

手順2：社内マーケットプレイスとして配る

チームに配るには、プラグインをgitリポジトリに置き、そのリポジトリをマーケットプレイスとして追加してもらいます。配布側はリポジトリに.claude-plugin/marketplace.jsonを用意し、受け取る側は次の2コマンドを打つだけです。社内限定にしたいなら、リポジトリを非公開にすれば同じ手順で閉じた配布ができます。

# 受け取る側の操作（社内リポジトリを指定）
/plugin marketplace add your-org/claude-plugins

# 一覧から自作プラグインを入れる
/plugin install my-plugin@your-org

この形にすると、alt文スキルを改善してversionを上げるだけで、チーム全員の手元に更新が届きます。各自が手でファイルを差し替える必要がなくなり、「担当者ごとにコマンドの挙動が違う」という事故を防げます。プラグインにMCPサーバーを同梱すれば、接続設定ごと配れるため、環境構築の手間も一度で済みます。

07プラグインが動かない・表示されない時の対処

うまく動かないときは、原因の大半が「Claude Codeのバージョン」か「ディレクトリ構造」です。ここでは公式が挙げる代表的な詰まりどころと確認手順を整理します。

/pluginコマンドが出てこないときは？

まずClaude Codeを最新版に更新してください。/pluginコマンドが表示されない場合、多くは古いバージョンが原因です。更新後に再度/pluginを開けば、マネージャーが起動します。

入れたのにスキルやフックが見当たらないのはなぜ？

この症状は、部品を.claude-plugin/の中に置いてしまっているのが典型的な原因です。commands/・agents/・skills/・hooks/は、.claude-plugin/の中ではなくプラグインの直下に置きます。.claude-plugin/に入れてよいのはplugin.jsonだけです。構造を直したら/reload-pluginsで読み直します。読み込みエラーは/pluginのErrorsタブで確認でき、詳細はclaude --debugで見られます。プラン確認や安全な実行の使い分けはClaude Codeプランモードの使い方もあわせてご覧ください。

08プラグインの料金は？セキュリティ上の注意点は？

プラグインの仕組み自体に追加料金はかかりません。Claude Codeを使えるプランの範囲で、プラグインの追加・自作・配布が行えます。ただし、プラグインが呼ぶモデルやMCP先の外部サービスに費用が発生する場合はその分がかかります。無料の範囲で試すなら、まずは自作の小さなスキルを1つ入れて挙動を見るのが安全です。

セキュリティ面では、出所の分からないプラグインを安易に入れないのが基本です。プラグインはフックやMCPサーバーを通じて端末上でコマンドを実行できるため、信頼できる配布元に限って導入します。社内配布なら非公開リポジトリで閉じ、公開マーケットプレイスから入れるときは審査済みの公式・コミュニティ版を優先します。エージェントの実行前後を安全に管理する考え方はClaude Securityとは？コミット前に脆弱性を止める使い方も参考になります。

09Claude Codeプラグインに関するよくある質問（FAQ）

10まとめ：まず1つ自作して直置きから卒業する

プラグインを使うかどうかは、「その設定をチームや複数プロジェクトで使い回すか」で決まります。1人で試す段階では.claudeの直置きで十分ですが、同じコマンドを全員にそろえたい、更新を配りたい、という段階に来たらプラグインが要になります。失敗しない進め方は、いきなり大きな配布を狙わず、まずplugin.jsonを1つ書いて自作スキルを--plugin-dirでローカル起動し、動きを確かめることです。

そのうえで、サイト制作やツール開発の定型作業をスキルにまとめ、社内リポジトリをマーケットプレイスにして配ると、チーム全体の作業がそろいます。束ねる中身の候補は非エンジニアのClaude Codeスラッシュコマンド12選やweb制作におすすめのMCPサーバー厳選5選もあわせてご覧ください。

11出典