Claude Code プラグインを作成する

空のディレクトリから最初の Claude Code プラグインを構築し、マーケットプレイスなしでテストし、既存の .claude/ セットアップを変換します。

プラグインは、スキル、エージェント、フック、MCP サーバーのディレクトリと、プラグインに名前を付ける plugin.json ファイル（マニフェストと呼ばれます）です。Claude Code はディレクトリを 1 つのユニットとして読み込むため、チームメイトと共有したり、複数のプロジェクトにインストールしたり、マーケットプレイスに公開したりできます。

このページは、独自のプラグインを作成する人向けです。

既に持っているものに一致するセクションから開始してください。

• まだ何もない: 最初のプラグインを作成するに従い、次にマーケットプレイスなしで開発するとテストとデバッグに従ってください。
• 既に .claude/ の下にファイルがある: 最初のプラグインのウォークスルーを一度実行してレイアウトを学び、次に既存の .claude/ セットアップを変換するに従ってください。

プラグインを使用する時期を決定する

スキル、エージェント、フック、MCP サーバーはすべて、プロジェクトまたはホームディレクトリでスタンドアロンで機能します。1 つのプロジェクトまたは自分だけに対応している間は、そのスタンドアロンセットアップを保持してください。チームメイトと共有したい場合、複数のプロジェクトにインストールしたい場合、またはバージョン付きリリースを公開したい場合は、プラグインを作成してください。

スタンドアロンのスキル、エージェント、フック、MCP 設定をプラグインに移動すると、それらの場所と名前が変わります。

• ファイルの場所: プラグインのルートと呼ばれるプラグイン独自のディレクトリの下に、skills/、agents/、hooks/hooks.json、.mcp.json として配置されます。
• 名前の付け方: プラグインのスキルとエージェントはプラグイン名をプレフィックスとして取得します。例えば /my-plugin:hello のように、2 つのプラグインが衝突することなく各々 hello スキルを提供できます。

既存のセットアップをプラグインに移動するには、既存の .claude/ セットアップを変換するを参照してください。

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

このウォークスルーでは、唯一のコンポーネントが 1 つのスキル（グリーティング）であるプラグインを作成し、--plugin-dir で実行します。これはインストールせずに 1 つのセッションのためにプラグインを読み込みます。プラグインは、スキル、エージェント、フック、MCP サーバーなどのコンポーネントの任意の組み合わせを保持でき、どれも必須ではありません。1 つのスキルはレイアウトを示す最小限の例です。

Claude Code がインストールされてサインインしている必要があります。

プラグインを保持したいディレクトリ（例えば ~/projects）でターミナルを開き、これらのステップのコマンドをそこから実行してください。プラグインはどこにでも保持できます。セッションを開始するときにそのパスを Claude Code に渡すためです。

mkdir -p 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

---
name: 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 validate ./my-first-plugin

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

/my-first-plugin:hello

プラグインは --plugin-dir で開始したセッションでのみ読み込まれます。フラグなしで作業を続けるか、.zip ビルドをテストするには、マーケットプレイスなしで開発するを参照してください。

プラグインを共有する

最初のプラグインを作成するで構築したプラグインはマシンにのみ存在します。他の人が使用する準備ができたら、それを取得する 3 つの方法があります。

• 数人に直接送信する: プラグインのディレクトリまたはその .zip を提供し、何も公開する必要はありません。マーケットプレイスなしでプラグインを共有するを参照してください。
• 独自のマーケットプレイスにリストする: チームメイトはマーケットプレイスを一度追加し、プラグインを名前でインストールし、更新を受け取ります。独自のマーケットプレイスを通じて公開するを参照してください。
• Anthropic のコミュニティマーケットプレイスに送信する: リストされたら、そのマーケットプレイスを追加した誰もがインストールできます。コミュニティマーケットプレイスに送信するを参照してください。

プラグインレイアウト

スキル、エージェント、フック、MCP サーバーなどの各種コンポーネントは、プラグインルートの下の固定ディレクトリに入ります。プラグインルートは --plugin-dir に渡すディレクトリです。使用するディレクトリのみを追加してください。完全なプラグインディレクトリをクリックして、各ファイルが何をするかを読むには、プラグインエクスプローラーを開いてください。

テーブルはほとんどのプラグインが開始するディレクトリをリストし、完全なレイアウトは残りをリストしています。

マーケットプレイスなしで開発する

作成しているプラグインを実行するためにマーケットプレイスは必要ありません。代わりにディスクまたは URL から直接読み込んでください。

• --plugin-dir: 1 つのセッションのためにディレクトリまたは .zip アーカイブを読み込みます。
• --plugin-url: 1 つのセッションのために URL から .zip アーカイブをフェッチします。
• claude plugin init: ~/.claude/skills/ の下にプラグインをスキャフォルドし、すべてのセッションで読み込みます。

異なる方法で読み込まれた 2 つのプラグインが名前を共有する場合、名前の競合を参照して、Claude Code がどれを保持するかを確認してください。

1 つのセッションのためにプラグインを読み込む

3 つの方法で 1 つのセッションのためにプラグインを読み込むことができます。--plugin-dir でディスク上のディレクトリまたは .zip アーカイブから、--plugin-url で URL から、またはフラグを追加できない場合は環境変数から。各プラグインはそのセッションのみのために読み込まれ、設定には何も書き込まれません。セッション中にプラグインのファイルを編集する場合、/reload-plugins を実行して変更を読み込んでください。

ディレクトリまたは `.zip` から

シェルから claude を開始するときに、--plugin-dir をプラグインのルートディレクトリまたはその .zip アーカイブで渡してください。複数のプラグインを読み込むためにフラグを繰り返してください。

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

プラグインのフォルダから

複数のプラグインを 1 つの場所から読み込むには、--plugin-dir ./plugins のようにそれらを保持するフォルダを渡してください。プラグインのフォルダを読み込むには Claude Code v2.1.265 以降が必要です。

フォルダに .claude-plugin/ ディレクトリがなく、トップレベルにプラグインコンポーネントがない場合、Claude Code はそれをプラグインのフォルダとして扱います。.claude-plugin/plugin.json マニフェストを持つ各直下のサブフォルダは、別のプラグインとして読み込まれます。フォルダ内の他のすべてのものはスキップされます。マニフェストがないサブフォルダを含めて、エラーなしでスキップされます。フォルダ内のプラグインが読み込まれない場合、そのサブフォルダに .claude-plugin/plugin.json があることを確認してください。

対話型セッションでは、起動後にフォルダ内のプラグインを追加および削除することもできます。

• 追加するサブフォルダは、マニフェストが存在すると新しいプラグインとして読み込まれます。
• サブフォルダを削除すると、そのプラグインはアンロードされます。

これらの変更のそれぞれについて、セッションにメッセージが表示されます。プラグインの読み込みまたはアンロードが会話の途中でプロンプトキャッシュを無効にする場合、変更は代わりに保持され、メッセージは /reload-plugins を実行して適用するよう指示します。

URL から

シェルから claude を開始するときに、--plugin-url を .zip アーカイブのアドレス（例えば CI が公開するビルドアーティファクト）で渡してください。

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

Claude Code は起動時にアーカイブをダウンロードします。複数を読み込むには、フラグを繰り返すか、URL をスペース区切りで 1 つの引用符付き引数で渡してください。

フラグは、制御またはトラストしているアーカイブのみを指してください。

Claude Code がアーカイブをフェッチできない場合、またはアーカイブが無効な場合、プラグインなしで開始し、プラグイン読み込みエラーを記録します。これは /plugin マネージャーの Errors タブで確認できます。

環境変数から

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

マネージド設定は --plugin-dir と CLAUDE_CODE_PLUGIN_DIRS をオフにできます。1 つのセッションのためにプラグインを読み込むフラグを参照してください。プラグインとそれが依存するプラグインをテストするには、プラグインとその依存関係をローカルでテストするを参照してください。

すべてのセッションでプラグインを読み込むようにする

個人的なスキルディレクトリは ~/.claude/skills/ です。Claude Code は、.claude-plugin/plugin.json を含むそこのフォルダを、フラグなしでインストールステップなしで、すべてのセッションでプラグインとして読み込みます。claude plugin init はこれらのプラグインの 1 つをスキャフォルドします。

`claude plugin init` でプラグインをスキャフォルドする

claude plugin init は ~/.claude/skills/ の下にスタータープラグインを書き込みます。Claude Code v2.1.157 以降が必要です。シェルからスキャフォルドしてください。

claude plugin init my-tool

コマンドは .claude-plugin/plugin.json とルート SKILL.md で ~/.claude/skills/my-tool/ を作成します。✔ Created plugin "my-tool" at ~/.claude/skills/my-tool に続いて It will auto-load next session as my-tool@skills-dir. Run /reload-plugins to load it now. を出力します。

--with skills を渡して、claude plugin init に skills/ の下のスキルをスキャフォルドさせてください。他の --with 値はプラグインコマンドリファレンスにあります。

スキャフォルドされたプラグインのスキルに名前を付ける

~/.claude/skills/my-tool/SKILL.md のルートスキルは個人的なスキルでもあるため、/my-tool:my-tool ではなく /my-tool として呼び出します。プラグイン内の skills/ の下に追加するスキルはプラグイン名プレフィックスを取得します。例えば /my-tool:example のように。

プラグインの読み込みを停止する

スキャフォルドされたプラグインの読み込みを停止するには、そのディレクトリを削除するか、シェルで claude plugin disable my-tool@skills-dir を実行してください。claude plugin init が出力した my-tool@skills-dir 名を使用してください。ID my-tool@skills-dir では、skills-dir はマーケットプレイス名が入る場所に立ちます。プラグインはマーケットプレイスではなくスキルディレクトリから読み込まれるためです。

リポジトリを通じてプラグインを共有する

claude plugin init はプラグインを個人的なスキルディレクトリ ~/.claude/skills/ に書き込むため、すべてのプロジェクトであなたのために読み込まれます。1 つのリポジトリのすべての人のためにプラグインを読み込むには、.claude-plugin/plugin.json を含む同じレイアウトを <project>/.claude/skills/<name>/ で自分で作成してください。リポジトリを通じて共有されるプラグインを参照して、Claude Code がそれを読み込む条件を確認してください。

テストとデバッグ

プラグインへの変更が表示されない場合、これらのチェックを順番に実行してください。それぞれが Claude Code がプラグインで何をしたかを伝えます。

1. シェルで claude plugin validate <path> を実行してください。マニフェストとすべてのスキル、エージェント、コマンドファイルのフロントマターをチェックし、Validation passed で終了コード 0 で終了します。--strict を追加して警告でも失敗するようにしてください。終了コードとディレクトリ処理はプラグインコマンドリファレンスにあります。
2. 実行中のセッションで /reload-plugins を実行して、ディスク上で行った編集を適用してください。1 つの Reloaded: 行をカウント付きで出力します。次に、/plugin-name:skill コマンドを入力するか、/plugin Installed タブでプラグインを見つけることで、スキルが読み込まれたことを確認してください。
3. 同じセッションで /plugin を実行してください。Installed タブはプラグインをリストし、プラグインの詳細では、Claude Code が見つけたコンポーネントをリストします。Errors タブは、読み込みに失敗したものと理由（例えば、マニフェスト内のパスが存在しない）をリストします。
4. シェルに戻り、claude plugin list を実行してください。セッションのみとスキルディレクトリプラグインを独自のセクションで Status: ✔ loaded または読み込みエラーで出力します。開発中のプラグインを含めるには、plugin list の前に --plugin-dir をそのパスで渡してください。

MCP サーバーをチェックするには、セッションで /mcp を実行してサーバーのステータスを確認してください。サーバーが健全な場合、/mcp はそれを接続済みとしてリストします。そうでない場合、開始しない MCP サーバーを参照してください。

フックをチェックするには、それが一致するイベントをトリガーしてください。例えば、Claude にファイルを編集するよう求めて PostToolUse フックをトリガーしてください。次にデバッグログを読んでください。これは、どのフックが一致したか、それらの終了コード、それらの出力を示します。

次のセクションは、開発中に最も可能性の高い失敗をカバーし、トラブルシューティングページには各々の完全なエントリがあります。

コンポーネントパスが見つからない

/plugin の Errors タブは <component> path not found: <path> を表示します。例えば commands path not found。マニフェスト内のコンポーネントパス（commands、skills、agents、hooks など）は何も指していません。パスを修正するか、ディレクトリを作成し、セッションで /reload-plugins を実行してください。commands path not foundを参照してください。

`--plugin-dir` がマーケットプレイスルートにあると `plugins/` の下のプラグインが読み込まれない

--plugin-dir はプラグインのルートディレクトリを取ります。.claude-plugin/plugin.json とコンポーネントディレクトリ（skills/ など）を含むディレクトリです。代わりにマーケットプレイスルートを指すと、Claude Code は marketplace.json を読まないため、plugins/ の下のプラグインは読み込まれず、エラーは表示されません。フラグを 1 つのプラグインのフォルダに指すか、マーケットプレイスを追加してください。トラブルシューティングエントリを参照してください。

プラグインが読み込まれるがそのスキルが見つからない

skills/ ディレクトリが .claude-plugin/ の内部にあるか、マニフェスト内の skills エントリがファイルを指しています。skills/ をプラグインルートに移動し、各 skills エントリを SKILL.md を含むディレクトリを指すようにし、セッションで /reload-plugins を実行してください。プラグインが読み込まれるがそのスキルが見つからないを参照してください。

`userConfig` ダイアログが表示されない

プラグインの userConfig オプションのダイアログはセッションで /plugin を通じてインストールの一部です。--plugin-dir での読み込みはそれを表示しません。シェルの claude plugin install でもそうです。プラグインが読み込まれたら、セッションで /plugin configure <plugin-name> を実行してそれを開いてください。userConfig ダイアログが表示されないを参照してください。

プラグインが Claude の動作を変更することを確認する

エラーなしで読み込まれるプラグインは、意図した方法で Claude を操舵できない場合があります。claude plugin eval はシェルで実行し、プラグインの有無でテストケースを実行し、差を採点します。プラグインで evals をテストするを参照してください。最初の eval スイートを作成するから開始してください。

既存の `.claude/` セットアップを変換する

既にプロジェクトの .claude/ ディレクトリの下にスキル、エージェント、またはフックがある場合、それらを書き直さずにプラグインに移動できます。

.claude/ を含むディレクトリであるプロジェクトルートからこれらのステップのコマンドを実行してください。cp パスはそれに対して相対的であるためです。

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 -p 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/ の下にある間、それらはプラグインのコピーと一緒に読み込まれたままです。

• スキルとエージェント: 2 つのセットは衝突しません。プラグインのスキルとエージェントは my-plugin: プレフィックスを持つためです。/deploy と /my-plugin:deploy の両方が機能し、Claude は reviewer と my-plugin:reviewer を 2 つのサブエージェントとして見ます。
• フック: フックにはプレフィックスがないため、設定ファイルと hooks/hooks.json の両方にあるフックは、そのイベントが発火するたびに 2 回実行されます。

プラグインが機能することを確認した後、.claude/ からオリジナルを削除し、設定ファイルから hooks オブジェクトを削除してください。

次のステップ

• プラグインコンポーネント: エージェント、フック、MCP サーバー、LSP サーバー、ユーザー設定をプラグインに追加する
• プラグインで evals をテストする: eval ケースを書き込み、claude plugin eval で実行してプラグインが Claude の動作をどの程度確実に導くかをチェックする
• プラグインを公開する: バージョン管理し、マーケットプレイスに入れ、コミュニティマーケットプレイスに送信する
• claude.ai と Cowork のプラグイン: 同じプラグインフォルダが claude.ai と Cowork にインストールされます。一部のコンポーネントは Claude Code のみです
• プラグインマニフェストリファレンス: すべての plugin.json フィールド、パスルール、ディレクトリ
• スキル: プラグインが提供するスキルを書く
• Anthropic の claude-code リポジトリのプラグイン: このページのレイアウトの完全な実装例。feature-dev と code-review など