プラグインを作成する

スキル、エージェント、フック、MCP サーバーで Claude Code を拡張するカスタムプラグインを作成します。

プラグインを使用すると、Claude Code をカスタム機能で拡張でき、プロジェクトとチーム全体で共有できます。このガイドでは、スキル、エージェント、フック、MCP サーバーを使用して独自のプラグインを作成する方法について説明します。

既存のプラグインをインストールしたいですか？プラグインを検出してインストールするを参照してください。完全な技術仕様については、プラグインリファレンスを参照してください。

プラグインとスタンドアロン設定を使い分ける

Claude Code では、カスタムスキル、エージェント、フックを追加する 2 つの方法をサポートしています。

クイックスタート

このクイックスタートでは、カスタムスキルを使用してプラグインを作成する手順を説明します。マニフェスト（プラグインを定義する設定ファイル）を作成し、スキルを追加して、--plugin-dir フラグを使用してローカルでテストします。

前提条件

• Claude Code インストール済みで認証済み

最初のプラグインを作成する

mkdir my-first-plugin

mkdir my-first-plugin/.claude-plugin

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

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

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

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

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

/my-first-plugin:hello

---
description: Greet the user with a personalized message
---

# Hello Skill

Greet the user named "$ARGUMENTS" warmly and ask how you can help them today. Make the greeting personal and encouraging.

/my-first-plugin:hello Alex

スキルディレクトリでプラグインを開発する

毎回起動時に --plugin-dir を渡す代わりに、スキルディレクトリにプラグインを保持して、Claude Code に自動的に読み込ませることができます。claude plugin init がスキャフォルドします。

claude plugin init my-tool

これにより、.claude-plugin/plugin.json マニフェストとスターター SKILL.md を含む ~/.claude/skills/my-tool/ が作成されます。次のセッションでは、マーケットプレイスやインストール手順なしで my-tool@skills-dir として読み込まれます。

自動読み込みルール、個人スコープ対プロジェクトスコープ、ワークスペース信頼要件、および更新または削除方法については、スキルディレクトリプラグインを参照してください。

プラグイン構造の概要

スキルを使用してプラグインを作成しましたが、プラグインにはさらに多くの機能を含めることができます。カスタムエージェント、フック、MCP サーバー、LSP サーバー、バックグラウンドモニターです。

正確に 1 つのスキルを含むプラグインは、skills/ ディレクトリを作成する代わりに、SKILL.md をプラグインルートに直接配置できます。Claude Code はそれを単一のスキルとして読み込み、フロントマター name フィールドを呼び出し名として使用します。複数のスキルに成長する可能性があるプラグインには、skills/ レイアウトを使用してください。

より複雑なプラグインを開発する

基本的なプラグインに慣れたら、より高度な拡張機能を作成できます。

プラグインに Skills を追加する

プラグインは Agent Skills を含めることで、Claude の機能を拡張できます。Skills はモデルが呼び出すもので、Claude はタスクのコンテキストに基づいて自動的に使用します。

プラグインのルートに skills/ ディレクトリを追加し、SKILL.md ファイルを含む Skill フォルダを配置します。

my-plugin/
├── .claude-plugin/
│   └── plugin.json
└── skills/
    └── code-review/
        └── SKILL.md

各 SKILL.md には YAML フロントマターと説明が含まれます。Claude がいつ Skill を使用するかを知るために description を含めます。

---
description: Reviews code for best practices and potential issues. Use when reviewing code, checking PRs, or analyzing code quality.
---

When reviewing code, check for:
1. Code organization and structure
2. Error handling
3. Security concerns
4. Test coverage

プラグインをインストール後、インストール概要を確認します。Run /reload-plugins to activate. と表示される場合は、プラグインの変更を再起動なしで適用する を参照して、現在のセッションで Skills を読み込みます。段階的な情報開示とツール制限を含む完全な Skill 作成ガイダンスについては、Agent Skills を参照してください。

プラグインに LSP サーバーを追加する

LSP（Language Server Protocol）プラグインは Claude にリアルタイムのコード インテリジェンスを提供します。公式 LSP プラグインがない言語をサポートする必要がある場合は、プラグインに .lsp.json ファイルを追加することで、独自のプラグインを作成できます。

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

プラグインをインストールするユーザーは、言語サーバーのバイナリをマシンにインストールしておく必要があります。

サーバーが起動することを確認するには、プラグインを有効にして Claude Code を起動し、/plugin Errors タブを確認します。起動に失敗した言語サーバーはそこに表示されます。例えば、バイナリがインストールされていない場合は Executable not found in $PATH と表示されます。無効な設定を持つエントリはスキップされます。理由を確認するには claude --debug を実行してください。

完全な LSP 設定オプションについては、LSP servers を参照してください。

プラグインにバックグラウンド モニターを追加する

バックグラウンド モニターを使用すると、プラグインはログ、ファイル、または外部ステータスをバックグラウンドで監視し、イベントが到着したときに Claude に通知できます。Claude Code はプラグインがアクティブな場合、各モニターを自動的に起動するため、Claude にウォッチを開始するよう指示する必要はありません。

プラグインのルートに monitors/monitors.json ファイルを追加し、モニター エントリの配列を含めます。

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

command からの各 stdout 行は、セッション中に Claude への通知として配信されます。when トリガーと変数置換を含む完全なスキーマについては、Monitors を参照してください。

プラグインでデフォルト設定を配布する

プラグインはプラグインのルートに settings.json ファイルを含めて、プラグインが有効になったときにデフォルト設定を適用できます。現在、agent と subagentStatusLine キーのみがサポートされています。

agent を設定すると、プラグインの custom agents の 1 つがメイン スレッドとしてアクティブになり、そのシステム プロンプト、ツール制限、およびモデルが適用されます。これにより、プラグインは有効になったときに Claude Code のデフォルトの動作を変更できます。

{
  "agent": "security-reviewer"
}

この例は、プラグインの agents/ ディレクトリで定義された security-reviewer エージェントをアクティブにします。settings.json の設定は、plugin.json で宣言された settings よりも優先されます。不明なキーは無視されます。

複雑なプラグインを整理する

多くのコンポーネントを持つプラグインの場合、機能別にディレクトリ構造を整理します。完全なディレクトリ レイアウトと整理パターンについては、Plugin directory structure を参照してください。

プラグインをローカルでテストする

--plugin-dir フラグを使用して、開発中にプラグインをテストします。これにより、インストールを必要とせずにプラグインを直接読み込みます。

claude --plugin-dir ./my-plugin

このフラグはプラグイン ディレクトリの .zip アーカイブも受け入れます。

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

--plugin-dir プラグインがインストール済みのマーケットプレイス プラグインと同じ名前を持つ場合、そのセッションではローカル コピーが優先されます。これにより、最初にアンインストールしなくても、既にインストール済みのプラグインへの変更をテストできます。例外は、管理設定によって強制的に有効にされたまたは強制的に無効にされたプラグインです。--plugin-dir はそれらをオーバーライドできません。

プラグインに変更を加えると、/reload-plugins を実行して、再起動せずに更新を取得します。これにより、プラグイン、Skills、エージェント、hooks、プラグイン MCP サーバー、およびプラグイン LSP サーバーが再読み込みされます。インタラクティブ ターミナルのないセッションでは、プラグイン MCP サーバーの変更は 次のセッションまで待機 します。プラグイン コンポーネントをテストします。

• /plugin-name:skill-name で Skills を試す
• エージェントが /context の Custom Agents に表示されるか、またはスコープ付き名で @-mention できるかを確認する
• PostToolUse hook の場合は Claude にファイルを編集するよう求めるなど、各 hook が一致するイベントをトリガーし、その効果を確認する。Claude Code は、一致した hooks、終了コード、および出力を debug log に記録します。

フラグを追加できないセッションでプラグインを読み込むには、CLAUDE_CODE_PLUGIN_DIRS 環境変数にそれらの絶対パスをリストします。Claude Code は各パスを --plugin-dir パスとして読み込みます。これらのプラグインは、--plugin-dir で渡したものに加えて読み込まれます。プロジェクトとローカル設定はこの変数を設定できません。CLAUDE_CODE_PLUGIN_DIRS には Claude Code v2.1.280 以降が必要です。

--plugin-dir でプラグインを試すことで、それが機能することがわかります。Claude が実際にどのくらいの頻度でそれに到達し、正しい結果を得るかを確認するには、claude plugin eval を使用してテスト プロンプトのセットに対して実行します。各プロンプトはプラグインが読み込まれた状態と読み込まれていない状態で複数回実行されるため、プラグインが何を貢献しているかを確認し、プラグインを変更したときまたは新しいモデルがリリースされたときの回帰を検出できます。

複数のプラグインを 1 つの場所から読み込むには、それらを保持するフォルダを渡します（例：--plugin-dir ./plugins）。フォルダからプラグインを読み込むには Claude Code v2.1.265 以降が必要です。Claude Code はフォルダのトップ レベルを読み取り、どのプラグインを読み込むかを決定し、インタラクティブ セッションではフォルダの後の変更も監視します。

• 読み込まれるもの: フォルダにマニフェストまたはプラグイン コンポーネントがトップ レベルにない場合、Claude Code はそれをプラグインのフォルダとして扱います。.claude-plugin/plugin.json マニフェストを持つ各直下のサブフォルダは、別のプラグインとして読み込まれます。Claude Code はフォルダ内の他のすべてをスキップします。マニフェストのないプラグインを含め、エラーを報告せずにスキップします。
• インタラクティブ セッション中の変更: 追加したサブフォルダは、マニフェストが配置されると新しいプラグインとして読み込まれ、サブフォルダを削除するとそのプラグインがアンロードされます。Claude Code は各変更についてセッションに行を出力します。変更を会話の途中で適用すると プロンプト キャッシュが無効になる 場合、Claude Code はそれを保持し、行は /reload-plugins を実行して適用するよう指示します。

既に .zip アーカイブとしてパッケージ化され、CI ビルド アーティファクトなどの URL でホストされているプラグインをテストするには、代わりに --plugin-url を使用します。Claude Code は起動時にアーカイブをフェッチし、そのセッションのみ読み込みます。Claude Code がアーカイブをフェッチできない場合、またはアーカイブが無効な場合、プラグインなしで起動し、/plugin マネージャーの Errors タブで確認できるプラグイン読み込みエラーを記録します。同じ 信頼に関する考慮事項 が、任意のプラグイン ソースに適用されます。このフラグは、制御または信頼するアーカイブのみを指します。

複数のプラグインを読み込むには、各 URL に対してフラグを繰り返します。

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

または、スペース区切りの URL を 1 つの引用符付き引数として渡します。

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

プラグインの問題をデバッグする

プラグインが期待どおりに機能していない場合：

1. 構造を確認する: ディレクトリが .claude-plugin/ 内ではなく、プラグイン ルートにあることを確認します。
2. コンポーネントを個別にテストする: 各 Skill、エージェント、および hook を個別に確認します。
3. 検証とデバッグ ツールを使用する: CLI コマンドとトラブルシューティング技術については、Debugging and development tools を参照してください。

プラグインを共有する

プラグインを共有する準備ができたら：

1. ドキュメントを追加する: インストールと使用方法の説明を含む README.md を含めます。
2. バージョン管理戦略を選択する: 明示的な version を設定するか、version management で説明されているフォールバックに依存するかを決定します。
3. マーケットプレイスを作成または使用する: plugin marketplaces を通じて配布してインストールします。
4. 他の人でテストする: より広い配布の前に、チーム メンバーにプラグインをテストしてもらいます。

プラグインがマーケットプレイスに登録されたら、他のユーザーは Discover and install plugins の説明を使用してインストールできます。プラグインをチーム内に保つには、private repository でマーケットプレイスをホストします。

プラグインをコミュニティ マーケットプレイスに送信する

Anthropic は Claude Code プラグイン用に 2 つの公開マーケットプレイスを管理しています。

• claude-plugins-official: Anthropic によって管理されるキュレーションされたプラグイン セット。Claude Code は初めて対話的に Claude Code を起動するときに自動的に登録します。初回の対話的な起動の前に Claude Code を非対話的に実行した場合、または marketplace policy が以前の試行をブロックした場合は、claude plugin marketplace add anthropics/claude-plugins-official で自分で登録します。
• claude-community: レビュー後にサードパーティの送信が行われる公開コミュニティ マーケットプレイス。ユーザーは /plugin marketplace add anthropics/claude-plugins-community で追加し、@claude-community としてインストールします。

コミュニティ マーケットプレイスのレビューのためにプラグインを送信するには、アプリ内フォームの 1 つを使用します。

• claude.ai: claude.ai/admin-settings/directory/submissions/plugins/new
• Console: platform.claude.com/plugins/submit

claude.ai フォームには Team または Enterprise 組織とディレクトリ管理アクセスが必要です。組織の所有者はデフォルトでこのアクセス権を持っています。Team または Enterprise 組織に属していない個別の作成者は、代わりに Console フォームを使用できます。

送信する前に、claude plugin validate ./your-plugin をローカルで実行します。./your-plugin をプラグイン ディレクトリへのパスに置き換えます。レビュー パイプラインはすべての送信に対して同じチェックを実行し、自動化されたセーフティ スクリーニングも実行します。検証が成功すると、Claude Code は ✔ Validation passed を出力するか、警告がある場合は ✔ Validation passed with warnings を出力します。警告は検証を失敗させません。警告をエラーとして扱うには --strict を追加します。

承認されたプラグインは anthropics/claude-plugins-community カタログの特定のコミット SHA にピン留めされ、CI はリポジトリに新しいコミットをプッシュするときに自動的にピンをバンプします。公開カタログは毎晩レビュー パイプラインから同期されるため、承認と marketplace.json にプラグインが表示されるまでの間に遅延が生じる可能性があります。プラグインがインストール可能かどうかを確認するには、community catalog でその名前を検索します。

公式マーケットプレイス claude-plugins-official は別途キュレーションされています。Anthropic は、どのプラグインを含めるかを裁量で決定します。申請プロセスはなく、送信フォームは公式マーケットプレイスにプラグインを追加しません。

Anthropic がプラグインを公式マーケットプレイスにリストしている場合、CLI は Claude Code ユーザーにインストールを促すことができます。CLI からプラグインを推奨する を参照してください。

既存の設定をプラグインに変換する

.claude/ ディレクトリにスキルまたはフックが既にある場合は、それらをプラグインに変換して、より簡単に共有および配布できます。

移行手順

mkdir -p my-plugin/.claude-plugin

{
"name": "my-plugin",
"description": "Migrated from standalone configuration",
"version": "1.0.0"
}

cp -r .claude/commands my-plugin/

cp -r .claude/agents my-plugin/

cp -r .claude/skills my-plugin/

mkdir my-plugin/hooks

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

claude --plugin-dir ./my-plugin

移行時の変更点

次のステップ

Claude Code のプラグインシステムを理解したので、異なる目標のための推奨パスを以下に示します。

プラグインユーザー向け

• プラグインを検出してインストールする：マーケットプレイスを参照してプラグインをインストール
• チームマーケットプレイスを設定する：チーム用のリポジトリレベルプラグインを設定

プラグイン開発者向け

• evals でプラグインをテストする：プラグインが何を変更するかを測定し、CI でゲートする
• マーケットプレイスを作成して配布する：プラグインをパッケージ化して共有
• プラグインリファレンス：完全な技術仕様
• 特定のプラグインコンポーネントをさらに詳しく調べる：
  • Skills：スキル開発の詳細
  • Subagents：エージェント設定と機能
  • Hooks：イベント処理と自動化
  • MCP：外部ツール統合