SpyBara
Go Premium

plugins/create.md 2026-10-19 23:58 UTC to 2026-10-20 23:00 UTC

This page contains 136 additions and 192 deletions.

2026
Sun 4 23:58 Mon 5 23:58 Fri 9 23:02 Tue 20 23:00 Thu 22 22:58 Fri 23 22:59 Wed 28 23:57

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

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

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

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

[!NOTE]

これらのケースは他のページで説明されています。

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

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

スキル、エージェント、フック、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 に渡すためです。

1. プラグインディレクトリを作成する

プラグインディレクトリを作成し、マニフェストを保持するための .claude-plugin/ フォルダをその中に作成します。

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

2. マニフェストを書く

マニフェストは plugin.json という名前の JSON ファイルで、Claude Code にプラグインの名前を伝え、それを説明します。これを 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"
  }
}

4 つのフィールドは以下のことを行います。

  • name: 必須。プラグインを識別し、プラグインが提供するすべてのスキルとエージェントのプレフィックスになります。スペースを入れないでください。
  • description: ユーザーが /plugin でプラグインに対して見るテキスト。
  • version: オプション。これを設定すると、ユーザーはそれを変更するまでそのバージョンに留まります。新しいバージョンをリリースするは、いつそれを設定または省略するかを説明しています。
  • author: クレジットする人。その中の name は必須です。email と url はオプションです。

他のすべてのフィールドはマニフェストリファレンスにあります。

.claude-plugin/ の中には plugin.json だけが入ります。次に追加するスキルは my-first-plugin/ の直下に、そのフォルダの隣に入ります。

3. スキルを追加する

このプラグインの唯一のコンポーネントはスキルです。各スキルは skills/ の下のディレクトリで、SKILL.md ファイルを含みます。スキルのディレクトリを作成してください。

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

次に、このコンテンツで my-first-plugin/skills/hello/SKILL.md を作成してください。

---
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.

disable-model-invocation: true の行は、Claude がスキルを独自に実行しないことを意味します。Claude が独自に実行したいスキルからはその行を削除してください。スキルのコマンドはプラグイン名とスキルの名前を組み合わせるため、これを /my-first-plugin:hello として実行します。他のフロントマターフィールドについては、スキルフロントマターリファレンスを参照してください。

4. プラグインを検証する

何かを実行する前に、マニフェストとスキルのフロントマターをチェックしてください。

claude plugin validate ./my-first-plugin

コマンドはチェックしたマニフェストパスと ✔ Validation passed を出力します。代わりに ✘ Validation failed を出力する場合、その結果行の上の各行は修正するフィールドに名前を付けます。claude plugin validate がエラーを報告するの下で各メッセージを調べてください。

5. プラグインで Claude Code を実行する

プラグインが読み込まれたセッションを開始してください。

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

Claude Code が開始したら、スキルを実行してください。

/my-first-plugin:hello

Claude はグリーティングで返信します。

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

Claude が大規模なプラグインをスキャフォールドしてチェックするのを支援してもらうには、claude-plugins-official マーケットプレイスから Anthropic の plugin-dev プラグインをインストールしてください。これはスキル、フック、MCP サーバーなどのコンポーネントを書くためのスキルとエージェント、および完成したプラグインを検証するためのスキルとエージェントを追加します。インストール後、/plugin-dev:create-plugin に続けて、作成したいプラグインの説明を実行すると、Claude が設計、作成、検証を通じてあなたをガイドします。

プラグインを共有する

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

プラグインレイアウト

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

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

場所 内容
.claude-plugin/plugin.json マニフェスト。--plugin-dir でプラグインを読み込み、マニフェストがない場合、Claude Code はプラグインをディレクトリの後に名前を付けます
skills/ スキルごとに 1 つの <name>/SKILL.md ディレクトリ
commands/ フラットな Markdown ファイル、スキルの古い形式。新しいプラグインには skills/ を使用してください
agents/ サブエージェントごとに 1 つの Markdown ファイル
hooks/hooks.json フック設定: トップレベルの "hooks" キーで、設定ファイルの hooks と同じ形状の値を持つ
.mcp.json MCP サーバー定義

[!WARNING]

.claude-plugin/ の中には plugin.json だけが入ります。そこに保存されたコンポーネントは読み込まれません。

プラグインルートはプラグイン独自のディレクトリで、~/.claude/ 自体ではありません。~/.claude/.mcp.json に保存された .mcp.json は読み込まれません。

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

作成しているプラグインを実行するためにマーケットプレイスは必要ありません。代わりにディスクまたは 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 があることを確認してください。

また、プラグインフォルダの横に .claude-plugin/marketplace.json を保持するフォルダを渡すこともできます。その .claude-plugin/ ディレクトリに plugin.json がない限り、プラグインフォルダは引き続き読み込まれます。マーケットプレイスファイルからは何もインストールまたは有効化されません。Claude Code がそれを読み込まないためです。このようなフォルダからプラグインを読み込むには Claude Code v2.1.281 以降が必要です。

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

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

これらの変更のそれぞれについて、セッションにメッセージが表示されます。プラグインの読み込みまたはアンロードが会話の途中でプロンプトキャッシュを無効にする場合、変更は代わりに保持され、メッセージは /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 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 パスはそれに対して相対的であるためです。

1. プラグイン構造を作成する

プラグインディレクトリとその .claude-plugin/ フォルダを .claude/ の隣に作成してください。その後、プラグインをどこにでも移動できます。

mkdir -p my-plugin/.claude-plugin

my-plugin/.claude-plugin/plugin.json を作成してください。

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

2. 既存のファイルをコピーする

持っている各設定ディレクトリをプラグインルートにコピーし、持っていないディレクトリのコマンドをスキップしてください。

cp -r .claude/commands my-plugin/

cp -r .claude/agents my-plugin/

cp -r .claude/skills my-plugin/

ls -a my-plugin を実行して、コピーした各ディレクトリが .claude-plugin の隣に表示されることを確認してください。

3. フックを移動する

.claude/settings.json または .claude/settings.local.json にフックがある場合、フックディレクトリを作成してください。

mkdir -p my-plugin/hooks

my-plugin/hooks/hooks.json を作成し、設定ファイルから hooks オブジェクトをそこにコピーしてください。形式は同じです。

この例は、Claude が書き込むまたは編集する各ファイルでリンターを実行する 1 つのフックを持つ形状を示しています。例を独自の hooks オブジェクトで置き換えてください。

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

4. 移行されたプラグインをテストする

セッションのためにプラグインを読み込んでください。

claude --plugin-dir ./my-plugin

新しい名前の下で各コンポーネントをチェックしてください。

  • スキル: /deploy だったスキルのために /my-plugin:deploy を実行してください。
  • サブエージェント: reviewer だったエージェントのために Claude に my-plugin:reviewer エージェントを使用するよう求めてください。
  • フック: 各フックが一致するイベントをトリガーしてください。

何かが見つからない場合、テストとデバッグを実行してください。

オリジナルがまだ .claude/ の下にある間、それらはプラグインのコピーと一緒に読み込まれたままです。

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

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

次のステップ