プラグインリファレンス

Claude Code プラグインシステムの完全な技術リファレンス。スキーマ、CLI コマンド、コンポーネント仕様を含みます。

このリファレンスは、Claude Code プラグインシステムの完全な技術仕様を提供します。コンポーネントスキーマ、CLI コマンド、開発ツールを含みます。

プラグインは、Claude Code をカスタム機能で拡張する自己完結型のコンポーネントディレクトリです。プラグインコンポーネントには、skills、agents、hooks、MCP servers、LSP servers、monitors が含まれます。

プラグインコンポーネントリファレンス

Skills

プラグインは Claude Code に skills を追加し、/name ショートカットを作成します。これらは、あなたまたは Claude が呼び出すことができます。

場所: プラグインルートの skills/ または commands/ ディレクトリ

ファイル形式: Skills はディレクトリで SKILL.md を含みます。commands はシンプルなマークダウンファイルです。

Skill 構造:

skills/
├── pdf-processor/
│   ├── SKILL.md
│   ├── reference.md (optional)
│   └── scripts/ (optional)
└── code-reviewer/
    └── SKILL.md

統合動作:

• Skills と commands はプラグインがインストールされると自動的に検出されます
• Claude はタスクコンテキストに基づいて自動的にそれらを呼び出すことができます
• Skills は SKILL.md の横にサポートファイルを含めることができます

詳細については、Skillsを参照してください。

Agents

プラグインは、特定のタスク用の特化した subagents を提供できます。Claude は必要に応じて自動的にそれらを呼び出すことができます。

場所: プラグインルートの agents/ ディレクトリ

ファイル形式: エージェント機能を説明するマークダウンファイル

Agent 構造:

---
name: agent-name
description: このエージェントが専門とする内容と、Claude がそれを呼び出すべき時期
model: sonnet
effort: medium
maxTurns: 20
disallowedTools: Write, Edit
---

エージェントの役割、専門知識、動作を説明する詳細なシステムプロンプト。

プラグインエージェントは name、description、model、effort、maxTurns、tools、disallowedTools、skills、memory、background、isolation frontmatter フィールドをサポートしています。唯一の有効な isolation 値は "worktree" です。セキュリティ上の理由から、hooks、mcpServers、permissionMode はプラグイン提供のエージェントではサポートされていません。

統合ポイント:

• Agents は /agents インターフェイスに表示されます
• Claude はタスクコンテキストに基づいて自動的にエージェントを呼び出すことができます
• Agents はユーザーが手動で呼び出すことができます
• プラグインエージェントは組み込みの Claude エージェントと一緒に動作します

詳細については、Subagentsを参照してください。

Hooks

プラグインは Claude Code イベントに自動的に応答するイベントハンドラーを提供できます。

場所: プラグインルートの hooks/hooks.json、または plugin.json 内のインライン

形式: イベントマッチャーとアクションを含む JSON 設定

Hook 設定:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/format-code.sh"
          }
        ]
      }
    ]
  }
}

プラグイン hooks はユーザー定義 hooksと同じライフサイクルイベントに応答します:

Hook タイプ:

• command: シェルコマンドまたはスクリプトを実行
• http: イベント JSON を URL への POST リクエストとして送信
• mcp_tool: 設定されたMCP server上のツールを呼び出す
• prompt: LLM でプロンプトを評価（コンテキストの $ARGUMENTS プレースホルダーを使用）
• agent: 複雑な検証タスク用のツール付き agentic verifier を実行

MCP servers

プラグインは Model Context Protocol（MCP）servers をバンドルして、Claude Code を外部ツールおよびサービスに接続できます。

場所: プラグインルートの .mcp.json、または plugin.json 内のインライン

形式: 標準 MCP サーバー設定

MCP サーバー設定:

{
  "mcpServers": {
    "plugin-database": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
      "env": {
        "DB_PATH": "${CLAUDE_PLUGIN_ROOT}/data"
      }
    },
    "plugin-api-client": {
      "command": "npx",
      "args": ["@company/mcp-server", "--plugin-mode"],
      "cwd": "${CLAUDE_PLUGIN_ROOT}"
    }
  }
}

統合動作:

• プラグイン MCP servers はプラグインが有効になると自動的に開始されます
• Servers は Claude のツールキットに標準 MCP ツールとして表示されます
• サーバー機能は Claude の既存ツールとシームレスに統合されます
• プラグインサーバーはユーザー MCP servers とは独立して設定できます

LSP servers

プラグインは Language Server Protocol（LSP）servers を提供して、Claude がコードベースで作業する際にリアルタイムコード インテリジェンスを得ることができます。

LSP 統合は以下を提供します:

• 即座の診断: Claude は各編集後すぐにエラーと警告を確認できます
• コードナビゲーション: 定義へのジャンプ、参照の検索、ホバー情報
• 言語認識: コードシンボルの型情報とドキュメント

場所: プラグインルートの .lsp.json、または plugin.json 内のインライン

形式: 言語サーバー名をその設定にマップする JSON 設定

.lsp.json ファイル形式:

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

plugin.json 内のインライン:

{
  "name": "my-plugin",
  "lspServers": {
    "go": {
      "command": "gopls",
      "args": ["serve"],
      "extensionToLanguage": {
        ".go": "go"
      }
    }
  }
}

必須フィールド:

オプションフィールド:

利用可能な LSP プラグイン:

言語サーバーをまずインストールしてから、マーケットプレイスからプラグインをインストールしてください。

Monitors

プラグインは、プラグインがアクティブな場合に Claude Code が自動的に開始するバックグラウンド monitors を宣言できます。各 monitor はセッションの期間中シェルコマンドを実行し、すべての stdout 行を Claude に通知として配信するため、Claude は自分自身に開始するよう求められることなく、ログエントリ、ステータス変更、またはポーリングされたイベントに反応できます。

プラグイン monitors はMonitor toolと同じメカニズムを使用し、その可用性制約を共有します。これらはインタラクティブ CLI セッションでのみ実行され、hooksと同じ信頼レベルでサンドボックス化されずに実行され、Monitor tool が利用できないホストではスキップされます。

場所: プラグインルートの monitors/monitors.json、または plugin.json 内のインライン

形式: monitor エントリの JSON 配列

次の monitors/monitors.json はデプロイメントステータスエンドポイントとローカルエラーログを監視します:

[
  {
    "name": "deploy-status",
    "command": "${CLAUDE_PLUGIN_ROOT}/scripts/poll-deploy.sh ${user_config.api_endpoint}",
    "description": "Deployment status changes"
  },
  {
    "name": "error-log",
    "command": "tail -F ./logs/error.log",
    "description": "Application error log",
    "when": "on-skill-invoke:debug"
  }
]

monitors をインラインで宣言するには、plugin.json の experimental.monitors を同じ配列に設定します。デフォルト以外のパスから読み込むには、experimental.monitors を "./config/monitors.json" などの相対パス文字列に設定します。Monitors は実験的コンポーネントです。

必須フィールド:

オプションフィールド:

command 値は MCP および LSP サーバー設定と同じ変数置換をサポートします: ${CLAUDE_PLUGIN_ROOT}、${CLAUDE_PLUGIN_DATA}、${user_config.*}、および環境からの任意の ${ENV_VAR}。スクリプトがプラグイン自体のディレクトリから実行される必要がある場合は、コマンドの前に cd "${CLAUDE_PLUGIN_ROOT}" && を付けます。

セッション中にプラグインを無効にしても、既に実行中の monitors は停止しません。セッションが終了するときに停止します。

Themes

プラグインは、/theme に組み込みプリセットおよびユーザーのローカルテーマと一緒に表示される色テーマを配布できます。テーマは themes/ 内の JSON ファイルで、base プリセットと色トークンのスパース overrides マップを持ちます。Themes は実験的コンポーネントです。

{
  "name": "Dracula",
  "base": "dark",
  "overrides": {
    "claude": "#bd93f9",
    "error": "#ff5555",
    "success": "#50fa7b"
  }
}

プラグインテーマを選択すると、custom:<plugin-name>:<slug> がユーザーの設定に保持されます。プラグインテーマは読み取り専用です。/theme で Ctrl+E を押すと、それが ~/.claude/themes/ にコピーされるため、ユーザーはコピーを編集できます。

プラグインインストールスコープ

プラグインをインストールするときは、プラグインが利用可能な場所と他のユーザーが使用できるかどうかを決定するスコープを選択します。

プラグインは他の Claude Code 設定と同じスコープシステムを使用します。インストール手順とスコープフラグについては、プラグインのインストールを参照してください。スコープの完全な説明については、設定スコープを参照してください。

プラグインマニフェストスキーマ

.claude-plugin/plugin.json ファイルはプラグインのメタデータと設定を定義します。このセクションでは、サポートされているすべてのフィールドとオプションを説明しています。

マニフェストはオプションです。省略された場合、Claude Code はデフォルト場所のコンポーネントを自動検出し、ディレクトリ名からプラグイン名を導出します。メタデータを提供するか、カスタムコンポーネントパスが必要な場合はマニフェストを使用してください。

完全なスキーマ

{
  "name": "plugin-name",
  "version": "1.2.0",
  "description": "Brief plugin description",
  "author": {
    "name": "Author Name",
    "email": "author@example.com",
    "url": "https://github.com/author"
  },
  "homepage": "https://docs.example.com/plugin",
  "repository": "https://github.com/author/plugin",
  "license": "MIT",
  "keywords": ["keyword1", "keyword2"],
  "skills": "./custom/skills/",
  "commands": ["./custom/commands/special.md"],
  "agents": ["./custom/agents/reviewer.md"],
  "hooks": "./config/hooks.json",
  "mcpServers": "./mcp-config.json",
  "outputStyles": "./styles/",
  "lspServers": "./.lsp.json",
  "experimental": {
    "themes": "./themes/",
    "monitors": "./monitors.json"
  },
  "dependencies": [
    "helper-lib",
    { "name": "secrets-vault", "version": "~2.1.0" }
  ]
}

必須フィールド

マニフェストを含める場合、name は唯一の必須フィールドです。

この名前はコンポーネントの名前空間に使用されます。たとえば、UI では、名前が plugin-dev のプラグインのエージェント agent-creator は plugin-dev:agent-creator として表示されます。

メタデータフィールド

コンポーネントパスフィールド

実験的コンポーネント

experimental キーの下のコンポーネント、themes と monitors は、安定化する間にリリース間でマニフェストスキーマが変更される可能性があります。それらを宣言する場所は別の移行です。トップレベルはまだ機能し、claude plugin validate は警告を表示し、将来のリリースでは experimental.* が必要になります。

ユーザー設定

userConfig フィールドは、プラグインが有効になったときに Claude Code がユーザーにプロンプトする値を宣言します。ユーザーに settings.json を手動で編集させる代わりにこれを使用してください。

{
  "userConfig": {
    "api_endpoint": {
      "type": "string",
      "title": "API endpoint",
      "description": "Your team's API endpoint"
    },
    "api_token": {
      "type": "string",
      "title": "API token",
      "description": "API authentication token",
      "sensitive": true
    }
  }
}

キーは有効な識別子である必要があります。各オプションはこれらのフィールドをサポートします:

各値は MCP および LSP サーバー設定、hook コマンド、monitor コマンド、および skill とエージェントコンテンツ（機密でない値のみ）で ${user_config.KEY} として置換可能です。すべての値はプラグインサブプロセスに CLAUDE_PLUGIN_OPTION_<KEY> 環境変数としてエクスポートされます。

機密でない値は settings.json の pluginConfigs[<plugin-id>].options に保存されます。機密値はシステムキーチェーン（またはキーチェーンが利用できない場合は ~/.claude/.credentials.json）に移動します。キーチェーンストレージは OAuth トークンと共有され、約 2 KB の合計制限があるため、機密値は小さく保ってください。

チャネル

channels フィールドを使用すると、プラグインは 1 つ以上のメッセージチャネルを宣言して、会話にコンテンツを注入できます。各チャネルはプラグインが提供する MCP サーバーにバインドされます。

{
  "channels": [
    {
      "server": "telegram",
      "userConfig": {
        "bot_token": {
          "type": "string",
          "title": "Bot token",
          "description": "Telegram bot token",
          "sensitive": true
        },
        "owner_id": {
          "type": "string",
          "title": "Owner ID",
          "description": "Your Telegram user ID"
        }
      }
    }
  ]
}

server フィールドは必須で、プラグインの mcpServers のキーと一致する必要があります。オプションのチャネルごとの userConfig はトップレベルフィールドと同じスキーマを使用し、プラグインがプラグイン有効化時にボットトークンまたはオーナー ID をプロンプトできるようにします。

パス動作ルール

skills、commands、agents、outputStyles、experimental.themes、experimental.monitors の場合、カスタムパスはデフォルトを置き換えます。マニフェストが skills を指定する場合、デフォルト skills/ ディレクトリはスキャンされません。experimental.monitors を指定する場合、デフォルト monitors/monitors.json は読み込まれません。Hooks、MCP servers、LSP serversは複数のソースを処理するための異なるセマンティクスを持ちます。

• すべてのパスはプラグインルートに相対的で、./ で始まる必要があります
• カスタムパスからのコンポーネントは同じ命名と名前空間ルールを使用します
• 複数のパスを配列として指定できます
• skills、commands、agents、output styles のデフォルトディレクトリを保持してさらにパスを追加するには、配列にデフォルトを含めます: "skills": ["./skills/", "./extras/"]
• skill パスが SKILL.md を直接含むディレクトリを指す場合（例: "skills": ["./"] がプラグインルートを指す）、SKILL.md の frontmatter name フィールドが skill の呼び出し名を決定します。これはインストールディレクトリに関係なく安定した名前を提供します。frontmatter に name が設定されていない場合、ディレクトリ basename がフォールバックとして使用されます。

パスの例:

{
  "commands": [
    "./specialized/deploy.md",
    "./utilities/batch-process.md"
  ],
  "agents": [
    "./custom-agents/reviewer.md",
    "./custom-agents/tester.md"
  ]
}

環境変数

Claude Code は、プラグインパスを参照するための 2 つの変数を提供します。どちらも skill コンテンツ、エージェントコンテンツ、hook コマンド、monitor コマンド、MCP または LSP サーバー設定に表示される場所にインラインで置換されます。どちらも hook プロセスおよび MCP または LSP サーバーサブプロセスに環境変数としてエクスポートされます。

${CLAUDE_PLUGIN_ROOT}: プラグインのインストールディレクトリへの絶対パス。プラグインにバンドルされたスクリプト、バイナリ、設定ファイルを参照するために使用します。このパスはプラグインが更新されると変更されます。前のバージョンのディレクトリは更新後約 7 日間ディスク上に残りますが、これを一時的なものとして扱い、ここに状態を書き込まないでください。

プラグインがセッション中に更新されると、hook コマンド、monitors、MCP サーバー、LSP サーバーは前のバージョンのパスを使用し続けます。/reload-plugins を実行して、hook、MCP サーバー、LSP サーバーを新しいパスに切り替えます。monitors はセッション再起動が必要です。

${CLAUDE_PLUGIN_DATA}: 更新後も保持される永続ディレクトリ。node_modules または Python 仮想環境などのインストール済み依存関係、生成されたコード、キャッシュ、およびプラグインバージョン全体で保持する必要があるその他のファイルに使用します。このディレクトリは、この変数が最初に参照されるときに自動的に作成されます。

{
  "hooks": {
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/process.sh"
          }
        ]
      }
    ]
  }
}

永続データディレクトリ

${CLAUDE_PLUGIN_DATA} ディレクトリは ~/.claude/plugins/data/{id}/ に解決されます。ここで {id} はプラグイン識別子で、a-z、A-Z、0-9、_、- 以外の文字が - に置き換えられます。formatter@my-marketplace としてインストールされたプラグインの場合、ディレクトリは ~/.claude/plugins/data/formatter-my-marketplace/ です。

一般的な使用法は、言語依存関係を 1 回インストールしてセッションとプラグイン更新全体で再利用することです。データディレクトリは単一のプラグインバージョンより長く存在するため、ディレクトリ存在チェックだけでは、更新がプラグインの依存関係マニフェストを変更したときを検出できません。推奨パターンはバンドルされたマニフェストをデータディレクトリのコピーと比較し、異なる場合は再インストールします。

この SessionStart hook は最初の実行時に node_modules をインストールし、プラグイン更新に変更された package.json が含まれるたびに再度インストールします:

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "diff -q \"${CLAUDE_PLUGIN_ROOT}/package.json\" \"${CLAUDE_PLUGIN_DATA}/package.json\" >/dev/null 2>&1 || (cd \"${CLAUDE_PLUGIN_DATA}\" && cp \"${CLAUDE_PLUGIN_ROOT}/package.json\" . && npm install) || rm -f \"${CLAUDE_PLUGIN_DATA}/package.json\""
          }
        ]
      }
    ]
  }
}

diff は保存されたコピーが不足しているか、バンドルされたコピーと異なる場合にゼロ以外で終了し、最初の実行と依存関係変更更新の両方をカバーします。npm install が失敗した場合、末尾の rm はコピーされたマニフェストを削除して、次のセッションが再試行します。

${CLAUDE_PLUGIN_ROOT} にバンドルされたスクリプトは、永続化された node_modules に対して実行できます:

{
  "mcpServers": {
    "routines": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"],
      "env": {
        "NODE_PATH": "${CLAUDE_PLUGIN_DATA}/node_modules"
      }
    }
  }
}

データディレクトリは、インストールされている最後のスコープからプラグインをアンインストールするときに自動的に削除されます。/plugin インターフェイスはディレクトリサイズを表示し、削除前にプロンプトします。CLI はデフォルトで削除します。--keep-dataを渡して保持します。

プラグインキャッシングとファイル解決

プラグインは 2 つの方法で指定されます:

• claude --plugin-dir または claude --plugin-url を通じて、セッションの期間。
• マーケットプレイスを通じて、将来のセッション用にインストール。

セキュリティと検証の目的で、Claude Code は_マーケットプレイス_プラグインをユーザーのローカルプラグインキャッシュ（~/.claude/plugins/cache）にコピーします。これらを所定の場所で使用するのではなく。この動作を理解することは、外部ファイルを参照するプラグインを開発する際に重要です。

各インストール済みバージョンはキャッシュ内の別のディレクトリです。プラグインを更新またはアンインストールすると、前のバージョンディレクトリは孤立したものとしてマークされ、7 日後に自動的に削除されます。猶予期間により、既に古いバージョンを読み込んだ同時実行 Claude Code セッションがエラーなく実行を続けることができます。

Claude の Glob および Grep ツールは検索中に孤立したバージョンディレクトリをスキップするため、ファイル結果には古いプラグインコードが含まれません。

パストラバーサル制限

インストールされたプラグインはディレクトリの外側のファイルを参照できません。プラグインルートの外側をトラバースするパス（../shared-utils など）は、これらの外部ファイルがキャッシュにコピーされないため、インストール後は機能しません。

外部依存関係の操作

プラグインがディレクトリの外側のファイルにアクセスする必要がある場合、プラグインディレクトリ内の外部ファイルへのシンボリックリンクを作成できます。シンボリックリンクはキャッシュに保持されるのではなく逆参照され、実行時にそのターゲットに解決されます。次のコマンドはプラグインディレクトリ内から共有ユーティリティの場所へのリンクを作成します:

ln -s /path/to/shared-utils ./shared-utils

これはキャッシングシステムのセキュリティ上の利点を維持しながら柔軟性を提供します。

プラグインディレクトリ構造

標準プラグインレイアウト

完全なプラグインは次の構造に従います:

enterprise-plugin/
├── .claude-plugin/           # メタデータディレクトリ（オプション）
│   └── plugin.json             # プラグインマニフェスト
├── skills/                   # Skills
│   ├── code-reviewer/
│   │   └── SKILL.md
│   └── pdf-processor/
│       ├── SKILL.md
│       └── scripts/
├── commands/                 # フラット .md ファイルとしての Skills
│   ├── status.md
│   └── logs.md
├── agents/                   # Subagent 定義
│   ├── security-reviewer.md
│   ├── performance-tester.md
│   └── compliance-checker.md
├── output-styles/            # 出力スタイル定義
│   └── terse.md
├── themes/                   # カラーテーマ定義
│   └── dracula.json
├── monitors/                 # バックグラウンド monitor 設定
│   └── monitors.json
├── hooks/                    # Hook 設定
│   ├── hooks.json           # メイン hook 設定
│   └── security-hooks.json  # 追加 hooks
├── bin/                      # PATH に追加されるプラグイン実行可能ファイル
│   └── my-tool               # Bash tool で裸のコマンドとして呼び出し可能
├── settings.json            # プラグインのデフォルト設定
├── .mcp.json                # MCP サーバー定義
├── .lsp.json                # LSP サーバー設定
├── scripts/                 # Hook とユーティリティスクリプト
│   ├── security-scan.sh
│   ├── format-code.py
│   └── deploy.js
├── LICENSE                  # ライセンスファイル
└── CHANGELOG.md             # バージョン履歴

プラグインルートの CLAUDE.md ファイルはプロジェクトコンテキストとして読み込まれません。プラグインは CLAUDE.md ではなく、skills、agents、hooks を通じてコンテキストを提供します。Claude のコンテキストに読み込まれる命令を配布するには、skill に配置してください。

ファイル場所リファレンス

CLI コマンドリファレンス

Claude Code は非対話的なプラグイン管理用の CLI コマンドを提供します。スクリプトと自動化に役立ちます。

plugin install

利用可能なマーケットプレイスからプラグインをインストールします。

claude plugin install <plugin> [options]

引数:

• <plugin>: プラグイン名または特定のマーケットプレイス用の plugin-name@marketplace-name

オプション:

スコープはインストールされたプラグインが追加される設定ファイルを決定します。たとえば、--scope project は .claude/settings.json の enabledPlugins に書き込み、プロジェクトリポジトリをクローンした全員がプラグインを利用できるようにします。

例:

# ユーザースコープにインストール（デフォルト）
claude plugin install formatter@my-marketplace

# プロジェクトスコープにインストール（チームと共有）
claude plugin install formatter@my-marketplace --scope project

# ローカルスコープにインストール（gitignored）
claude plugin install formatter@my-marketplace --scope local

plugin uninstall

インストール済みプラグインを削除します。

claude plugin uninstall <plugin> [options]

引数:

• <plugin>: プラグイン名または plugin-name@marketplace-name

オプション:

エイリアス: remove、rm

デフォルトでは、最後に残っているスコープからアンインストールすると、プラグインの ${CLAUDE_PLUGIN_DATA} ディレクトリも削除されます。たとえば、新しいバージョンをテストした後に再インストールする場合は、--keep-data を使用して保持します。

plugin prune

インストール済みプラグインによって不要になった自動インストール プラグイン依存関係を削除します。Claude Code が別のプラグインの dependencies フィールドを満たすために取得した依存関係は削除されます。直接インストールしたプラグインは決して削除されません。

claude plugin prune [options]

オプション:

エイリアス: autoremove

このコマンドは孤立した依存関係をリストアップし、削除する前に確認を求めます。プラグインを削除し、その依存関係をクリーンアップする場合は、1 ステップで claude plugin uninstall <plugin> --prune を実行します。

plugin enable

無効なプラグインを有効にします。

claude plugin enable <plugin> [options]

引数:

• <plugin>: プラグイン名または plugin-name@marketplace-name

オプション:

plugin disable

プラグインをアンインストールせずに無効にします。

claude plugin disable <plugin> [options]

引数:

• <plugin>: プラグイン名または plugin-name@marketplace-name

オプション:

plugin update

プラグインを最新バージョンに更新します。

claude plugin update <plugin> [options]

引数:

• <plugin>: プラグイン名または plugin-name@marketplace-name

オプション:

plugin list

インストール済みプラグインをバージョン、ソースマーケットプレイス、有効状態とともにリストします。

claude plugin list [options]

オプション:

plugin tag

現在のディレクトリ内のプラグインのリリース git タグを作成します。プラグインのフォルダ内から実行してください。プラグインリリースにタグを付けるを参照してください。

claude plugin tag [options]

オプション:

デバッグと開発ツール

デバッグコマンド

claude --debug を使用してプラグイン読み込みの詳細を確認します:

これは以下を表示します:

• どのプラグインが読み込まれているか
• プラグインマニフェストのエラー
• Skill、agent、hook 登録
• MCP サーバー初期化

一般的な問題

エラーメッセージの例

マニフェスト検証エラー:

• Invalid JSON syntax: Unexpected token } in JSON at position 142: コンマの欠落、余分なコンマ、またはクォートされていない文字列を確認
• Plugin has an invalid manifest file at .claude-plugin/plugin.json. Validation errors: name: Required: 必須フィールドが不足
• Plugin has a corrupt manifest file at .claude-plugin/plugin.json. JSON parse error: ...: JSON 構文エラー

プラグイン読み込みエラー:

• Warning: No commands found in plugin my-plugin custom directory: ./cmds. Expected .md files or SKILL.md in subdirectories.: コマンドパスが存在するが有効なコマンドファイルが含まれていない
• Plugin directory not found at path: ./plugins/my-plugin. Check that the marketplace entry has the correct path.: marketplace.json の source パスが存在しないディレクトリを指している
• Plugin my-plugin has conflicting manifests: both plugin.json and marketplace entry specify components.: 重複するコンポーネント定義を削除するか、marketplace エントリから strict: false を削除

Hook トラブルシューティング

Hook スクリプトが実行されない:

1. スクリプトが実行可能であることを確認: chmod +x ./scripts/your-script.sh
2. shebang 行を確認: 最初の行は #!/bin/bash または #!/usr/bin/env bash である必要があります
3. パスが ${CLAUDE_PLUGIN_ROOT} を使用していることを確認: "command": "${CLAUDE_PLUGIN_ROOT}/scripts/your-script.sh"
4. スクリプトを手動でテスト: ./scripts/your-script.sh

Hook が予期されたイベントでトリガーされない:

1. イベント名が正しいことを確認（大文字小文字を区別）: PostToolUse、postToolUse ではない
2. マッチャーパターンがツールと一致することを確認: ファイル操作の場合 "matcher": "Write|Edit"
3. hook タイプが有効であることを確認: command、http、mcp_tool、prompt、または agent

MCP サーバートラブルシューティング

サーバーが起動しない:

1. コマンドが存在し、実行可能であることを確認
2. すべてのパスが ${CLAUDE_PLUGIN_ROOT} 変数を使用していることを確認
3. MCP サーバーログを確認: claude --debug は初期化エラーを表示
4. Claude Code の外部でサーバーを手動でテスト

サーバーツールが表示されない:

1. サーバーが .mcp.json または plugin.json で正しく設定されていることを確認
2. サーバーが MCP プロトコルを正しく実装していることを確認
3. デバッグ出力で接続タイムアウトを確認

ディレクトリ構造の間違い

症状: プラグインは読み込まれるがコンポーネント（skills、agents、hooks）が不足している。

正しい構造: コンポーネントはプラグインルートにある必要があり、.claude-plugin/ 内ではありません。.claude-plugin/ には plugin.json のみが属します。

my-plugin/
├── .claude-plugin/
│   └── plugin.json      ← マニフェストのみここ
├── commands/            ← ルートレベル
├── agents/              ← ルートレベル
└── hooks/               ← ルートレベル

コンポーネントが .claude-plugin/ 内にある場合は、プラグインルートに移動してください。

デバッグチェックリスト:

1. claude --debug を実行し、「loading plugin」メッセージを探す
2. 各コンポーネントディレクトリがデバッグ出力にリストされていることを確認
3. プラグインファイルを読み取ることができるファイルパーミッションを確認

配布とバージョン管理リファレンス

バージョン管理

Claude Code はプラグインのバージョンをキャッシュキーとして使用し、更新が利用可能かどうかを判断します。/plugin update を実行するか自動更新が実行されると、Claude Code は現在のバージョンを計算し、既にインストールされているものと一致する場合は更新をスキップします。

バージョンは、設定されている最初のものから解決されます：

1. プラグインの plugin.json の version フィールド
2. marketplace.json のプラグインのマーケットプレイスエントリの version フィールド
3. git でホストされているマーケットプレイスの github、url、git-subdir、および相対パスソースのプラグインソースの git コミット SHA
4. npm ソースまたは git リポジトリ内にないローカルディレクトリの場合は unknown

これにより、プラグインをバージョン管理する 2 つの方法が提供されます：

明示的なバージョンを使用する場合は、semantic versioning（MAJOR.MINOR.PATCH）に従ってください：破壊的変更の場合は MAJOR をバンプし、新機能の場合は MINOR をバンプし、バグ修正の場合は PATCH をバンプしてください。CHANGELOG.md で変更を文書化してください。

関連項目

• プラグイン - チュートリアルと実践的な使用法
• プラグインマーケットプレイス - マーケットプレイスの作成と管理
• Skills - Skill 開発の詳細
• Subagents - エージェント設定と機能
• Hooks - イベント処理と自動化
• MCP - 外部ツール統合
• 設定 - プラグインの設定オプション