Claude Code のプラグインを作る

プラグインは、スキル・エージェント・フック・MCP サーバーなどのカスタマイズを 1 つのディレクトリにまとめ、チームやコミュニティで共有できるようにする仕組みです。ここでは公式ドキュメントの「Create plugins」に沿って、最小構成のプラグインを作り、ローカルで動かして、配布するところまでを日本語でまとめます。

プラグインとは何か

Claude Code のプラグインは、スキル・エージェント・フック・MCP サーバー・LSP サーバーなどの拡張をひとつのディレクトリにまとめたものです。プラグインにしておくと、同じ拡張を複数のプロジェクトで使い回せ、バージョンを付けて配布でき、マーケットプレイス経由でインストールしてもらえます。

プラグインのスキルは /プラグイン名:スキル名 の形式で名前空間が付きます。複数のプラグインが同じ名前のスキルを持っていても衝突しないようにするためです。

単体設定との使い分け

スキル・エージェント・フックを足す方法は 2 つあり、公式ドキュメントは次のように使い分けを示しています。

まず .claude/ の単体設定で素早く試し、共有したくなった段階でプラグインへ変換するのが公式の推奨です。共有の予定が無いなら、名前空間の付かない短いスキル名のまま使えるぶん単体設定のほうが手軽です。

最小のプラグインを作る

マニフェストとスキルを 1 つずつ持つ、最小のプラグインを作ります。前提は Claude Code がインストール済みで認証が終わっていることだけです。

まずプラグイン用のディレクトリを作ります。この手順では最後に --plugin-dir で場所を指定するため、置き場所はどこでも構いません。

mkdir my-first-plugin

次にマニフェストを置きます。.claude-plugin/plugin.json がプラグインの名前・説明・バージョンを定義するファイルです。

mkdir my-first-plugin/.claude-plugin

my-first-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"
  }
}

スキルは skills/ ディレクトリに置きます。1 つのスキルが 1 つのフォルダで、その中に SKILL.md を置く形です。フォルダ名がスキル名になります。

mkdir -p my-first-plugin/skills/hello

my-first-plugin/skills/hello/SKILL.md:

---
description: Greet the user with a friendly message
disable-model-invocation: true
---

Greet the user warmly and ask how you can help them today.

あとは --plugin-dir を付けて起動すれば読み込まれます。

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

起動後に /my-first-plugin:hello を実行すると、スキルが動きます。/help の「Custom commands」タブにも、プラグインの名前空間の下に表示されます。

スキルに引数を渡したい場合は、SKILL.md の本文で $ARGUMENTS を使います。スキル名の後ろに書いた文字列がそこへ入ります。編集後は /reload-plugins で読み直せば、再起動せずに反映されます。

プラグインの構成

プラグインのルート直下に置けるディレクトリは次のとおりです。

スキルをちょうど 1 つだけ同梱するプラグインなら、skills/ を作らずルート直下に SKILL.md を置く書き方もできます。この場合は front-matter の name が呼び出し名になります。将来 2 つ以上に増える見込みがあるなら、最初から skills/ 形式にしておくほうが無難です。

より複雑なプラグインにする

基本形に慣れたら、スキル以外の構成要素も足せます。

スキル（Agent Skills）

プラグインの skills/ にスキルフォルダを置きます。スキルはモデル側から呼び出される（タスクの文脈に応じて Claude が自動的に使う）ため、description に「いつ使うか」を書いておくことが重要です。インストール後は /reload-plugins で読み込みます。

LSP サーバー

ルートに .lsp.json を置くと、言語サーバー経由のコード理解を追加できます。TypeScript・Python・Rust など主要言語は公式マーケットプレイスに用意があるので、自作するのは対応が無い言語のときだけで十分です。

{
  "go": {
    "command": "gopls",
    "args": ["serve"],
    "extensionToLanguage": {
      ".go": "go"
    }
  }
}

起動を確認するには、プラグインを有効にした状態で /plugin の Errors タブを見ます。言語サーバーの起動に失敗した場合はここに出ます（バイナリが未インストールなら Executable not found in $PATH など）。設定自体が不正なエントリはスキップされるので、その場合は claude --debug で理由を確認します。

バックグラウンド監視（monitors）

ログやファイル、外部の状態を監視して、イベントが起きたら Claude に通知させられます。ルートに monitors/monitors.json を置くと、プラグインが有効な間は自動的に開始されます。

[
  {
    "name": "error-log",
    "command": "tail -F ./logs/error.log",
    "description": "Application error log"
  }
]

command の標準出力の各行が、セッション中の通知として Claude に渡されます。

既定の設定を同梱する

ルートの settings.json で、プラグイン有効時の既定設定を配れます。現時点で使えるキーは agent と subagentStatusLine だけです。agent を指定すると、プラグイン内のカスタムエージェントをメインスレッドとして有効にでき、そのシステムプロンプト・ツール制限・モデルが適用されます。

{
  "agent": "security-reviewer"
}

ローカルで検証する

開発中は --plugin-dir でそのまま読み込めます。インストール作業は不要です。

claude --plugin-dir ./my-plugin

このフラグはプラグインディレクトリを固めた .zip も受け付けます（Claude Code v2.1.128 以降）。

claude --plugin-dir ./my-plugin.zip

複数を同時に読み込むときはフラグを繰り返します。

claude --plugin-dir ./plugin-one --plugin-dir ./plugin-two

すでにマーケットプレイスからインストール済みのプラグインと同名の場合、そのセッションではローカルのほうが優先されます。アンインストールせずに変更を試せるということです（管理された設定で強制的に有効化・無効化されているプラグインは例外で、上書きできません）。

CI のビルド成果物のように、URL 上に置かれた .zip を試す場合は --plugin-url を使います。起動時に取得してそのセッションだけ読み込みます。取得に失敗した場合やアーカイブが不正な場合は、プラグイン無しで起動し、読み込みエラーが /plugin マネージャの Errors タブに記録されます。信頼できるアーカイブだけを指定してください。

claude --plugin-url https://example.com/my-plugin.zip --plugin-url https://example.com/other.zip

変更を反映するには /reload-plugins を実行します。スキル・エージェント・フック・プラグインの MCP サーバー・LSP サーバーがまとめて読み直されます。検証の観点は次の3つです。

• スキルを /plugin-name:skill-name で実行してみる
• エージェントが /context の Custom Agents に出るか、スコープ付きの名前で @ メンションできるかを確認する
• 各フックが対象とするイベントを実際に起こして（PostToolUse ならファイル編集を依頼するなど）効果を確認する。どのフックが一致し、終了コードと出力がどうだったかはデバッグログに記録される

うまく動かないときは、(1) ディレクトリが .claude-plugin/ の中ではなくルート直下にあるか、(2) スキル・エージェント・フックを個別に切り分けて確認したか、の順で見ていきます。

既存の設定をプラグインに移行する

すでに .claude/ にスキルやフックを持っているなら、そのままプラグインへ移せます。

まず、既存の .claude/ と同じ階層にプラグイン用ディレクトリを作ります（この後の相対パスがそのまま通るようにするためです）。

mkdir -p my-plugin/.claude-plugin

my-plugin/.claude-plugin/plugin.json にマニフェストを作り、既存のディレクトリをコピーします。3 つ全部を持っているとは限らないので、無いものは飛ばして構いません。

cp -r .claude/commands my-plugin/

cp -r .claude/agents my-plugin/

cp -r .claude/skills my-plugin/

フックを設定に書いていた場合は my-plugin/hooks/hooks.json を作り、.claude/settings.json（または settings.local.json）の hooks オブジェクトをそのまま移します。形式は同じです。フックの入力は JSON として標準入力に渡るので、ファイルパスの取り出しには jq を使います。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [{ "type": "command", "command": "jq -r '.tool_input.file_path' | xargs npm run lint:fix" }]
      }
    ]
  }
}

移行後は元のファイルを .claude/ から消しておきます。プロジェクトやユーザーの .claude/agents/ の定義は同名のプラグインエージェントより優先されるため、元を残したままだとプラグイン側が有効になりません。一方でスキルは名前空間が付くので、元の /skill-name とプラグイン側の /plugin-name:skill-name は両方とも残ります。

配布する

共有できる状態になったら、次の順で進めます。

• ドキュメントを付ける - インストール方法と使い方を書いた README.md を同梱する
• バージョン方針を決める - version を明示するか、git のコミット SHA に任せるかを決める
• マーケットプレイスを用意する / 使う - 配布はマーケットプレイス経由で行う。チーム内に留めたい場合はプライベートリポジトリでホストする
• 他の人に試してもらう - 広く配る前にチームメンバーに検証してもらう

Anthropic は 2 つの公開マーケットプレイスを運用しています。claude-plugins-official は Anthropic が精選したもので、対話モードで初めて Claude Code を起動したときに自動登録されます。claude-community は審査を通った第三者のプラグインが載る公開マーケットプレイスで、利用者は /plugin marketplace add anthropics/claude-plugins-community で追加します。

コミュニティマーケットプレイスへ申請する前に、手元で検証コマンドを通しておきます。審査側でも同じ検査が走ります。

claude plugin validate ./your-plugin

検証に通ると Validation passed、警告がある場合は Validation passed with warnings と表示されます。警告は失敗扱いにはなりませんが、--strict を付けるとエラーとして扱えます。

なお、公式マーケットプレイス（claude-plugins-official）は別枠で、掲載は Anthropic の裁量です。申請フォームから公式マーケットプレイスへ追加されることはありません。