Claude Code のプラグインを作って配る：最小の作り方から公開まで

プラグインとは

プラグインは、次のものを一つにまとめて、インストールできる形にした単位です。

• スキル（SKILL.md の指示）
• サブエージェントの定義
• hooks の設定
• MCP サーバーの定義

同じ設定を2つ目のリポジトリでも使いたくなったら、プラグインにまとめるタイミングです。

最小のプラグインを作る

1. フォルダとマニフェストを作る

mkdir -p my-first-plugin/.claude-plugin

.claude-plugin/plugin.json を書きます。

{
  "name": "my-first-plugin",
  "description": "A greeting plugin to learn the basics",
  "version": "1.0.0",
  "author": {
    "name": "Your Name"
  }
}

• name（必須）：空白を入れないこと。スキルやエージェントの接頭辞になります。
• description：/plugin の画面に表示される説明です。
• version（任意）：入れると、変更するまでそのバージョンのままになります。
• author：name は必須、email と url は任意です。

2. スキルを足す

my-first-plugin/skills/hello/SKILL.md を作ります。プラグインのスキルは、/プラグイン名:スキル名 の形で呼び出します。この例なら /my-first-plugin:hello です。

3. 検証して試す

claude plugin validate ./my-first-plugin
claude --plugin-dir ./my-first-plugin

検証が通ると「Validation passed」と出ます。--plugin-dir で読み込んだプラグインは、そのコマンドで起動したセッションでだけ有効です。

フォルダの構成

場所	中身
.claude-plugin/plugin.json	マニフェスト。なければ、フォルダの名前がプラグインの名前になる
skills/	スキルごとに <名前>/SKILL.md のフォルダ
commands/	平たい Markdown ファイル（スキルの古い形。新しく作るなら skills/）
agents/	サブエージェントごとに Markdown ファイル1つ
hooks/hooks.json	hooks の設定。最上位に "hooks" キーを置き、中身は設定ファイルの hooks と同じ形
.mcp.json	MCP サーバーの定義

.claude-plugin/ の中に入れてよいのは plugin.json だけです。ここに置いたスキルなどは読み込まれません。

今の設定をプラグインに移す

すでに .claude/ に置いてあるものは、コピーして移せます。

cp -r .claude/commands my-plugin/
cp -r .claude/agents my-plugin/
cp -r .claude/skills my-plugin/

hooks は hooks/hooks.json に書き写します。移したあとは、呼び出す名前が /my-plugin:deploy のように変わります。hooks には接頭辞が付かないので、元の設定ファイルとプラグインの両方に書いてあると、2回実行されます。

配り方

方法	使える人	必要なもの	更新は自動で届くか
マーケットプレイスなし	フォルダや zip を渡した相手	プラグインのフォルダ	届かない（受け取ったコピーのまま）
自分のマーケットプレイス	リポジトリに届く人（非公開でもよい）	.claude-plugin/marketplace.json を置いた git リポジトリなど	既定ではオフ
Anthropic のディレクトリ	claude.ai や Cowork で追加する人	GitHub のリポジトリと、有料の claude.ai プラン	公開した版が反映されれば届く

自分のマーケットプレイスを作る

マーケットプレイスは、プラグインの一覧と取得先を書いた JSON のカタログです。リポジトリのルートに .claude-plugin/marketplace.json を置きます。

{
  "name": "your-marketplace",
  "owner": { "name": "Your Name" },
  "plugins": [
    { "name": "deploy-helper", "source": "./" }
  ]
}

使う側は、次の2つのコマンドで入れます。

claude plugin marketplace add your-org/your-marketplace
claude plugin install deploy-helper@your-marketplace

更新は claude plugin update deploy-helper@your-marketplace で行います。自動更新は、既定ではオフです。

バージョンと名前の扱い

• plugin.json に version を書いたまま、中身だけを更新して push すると、claude plugin update は更新を見つけられず、使う側は古いコピーのままになります。公開のたびに version を上げるか、git のマーケットプレイスでは version を書かずにコミットの SHA に任せます。
• 公開したプラグインの name は変えないでください。
• 公開の前に claude plugin validate --strict ./your-plugin で確認します。

インストールの範囲

範囲	内容
ユーザー	このコンピュータのすべてのプロジェクト
プロジェクト	リポジトリの .claude/settings.json で共有する
ローカル	このリポジトリだけ、自分だけ

どの範囲でも、インストールしたプラグインは、自分の権限でコードを実行できます。他人が作ったプラグインは、入れる前に中身を確かめてください。クラウドのセッション（claude.ai/code）は、ローカルの設定にあるプラグインを読み込みません。

文脈への影響

有効にしたプラグインのスキルやエージェントは、名前と説明が毎ターン文脈に入ります。全文は、使われたときにだけ読み込まれます。入れすぎると、説明文だけでも文脈を使うので、使わないものは無効にしておきましょう。

どこから始めるか

まず、自分がよく使うスキルを1つだけ入れたプラグインを作り、--plugin-dir で試してください。手元で動くことを確かめてから、チームのマーケットプレイスに載せると、失敗しても影響が小さくて済みます。