プラグインのリファレンス

プラグインを作る・配る・調べるときに、フィールド名やコマンドを引くためのページです。作り方はプラグインを作って配る、使う側の手順はプラグインを使うにあります。表のあとに、読み込みの規則と、エラーメッセージごとの対処をまとめています。

このページで分かること#

• plugin.json（マニフェスト）の全フィールドとパスの書き方、userConfig・channels、環境変数、標準の配置
• marketplace.json の全フィールド、プラグインの取得元とマーケットプレイスの取得元、検証メッセージ
• claude plugin の全サブコマンドとフラグ、/plugin と /reload-plugins
• 読み込みの規則（ID の読み方、スコープの優先順位、ディスク上の場所、版の計算、名前の衝突）
• エラーメッセージの索引

マニフェスト（plugin.json）#

マニフェストは、プラグインの .claude-plugin/ に置く plugin.json で、メタデータと、ユーザーに尋ねる userConfig の値を持ちます。標準の場所の外にあるコンポーネントや、インラインで定義するコンポーネントもここで宣言します。

• マニフェストは省略できます。無ければ、標準の配置から見つかるコンポーネントを読み込み、プラグイン名はマーケットプレイスの項目から（--plugin-dir で読み込むときはディレクトリ名から）取られます
• メタデータ、標準の場所の外のコンポーネント、userConfig、インラインのコンポーネント定義が要るときに書きます
• .claude-plugin/plugin.json に置き、他のファイル（skills/・commands/・hooks/ など）は .claude-plugin/ の中ではなくプラグインのルートに置きます

書き方の例#

{
  "name": "deploy-tools",
  "displayName": "Deploy Tools",
  "version": "1.2.0",
  "description": "Deployment commands, a review agent, and a status monitor",
  "author": {
    "name": "Example Team",
    "email": "dev@example.com",
    "url": "https://example.com"
  },
  "homepage": "https://example.com/docs/deploy-tools",
  "repository": "https://github.com/example/deploy-tools",
  "license": "MIT",
  "keywords": ["deployment", "ci"],
  "defaultEnabled": true,
  "dependencies": ["secrets-vault"],
  "metadata": { "catalogId": "cat-123" },
  "skills": ["./extra-skills/"],
  "commands": {
    "status": {
      "source": "./commands/status.md",
      "description": "Show the current deployment status"
    },
    "about": {
      "content": "Explain what the deploy-tools plugin provides.",
      "description": "Describe this plugin"
    }
  },
  "agents": ["./agents/reviewer.md"],
  "hooks": "./config/extra-hooks.json",
  "mcpServers": {
    "deploy-api": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"]
    }
  },
  "lspServers": "./.lsp.json",
  "outputStyles": "./styles/",
  "experimental": {
    "themes": "./themes/",
    "monitors": "./config/monitors.json"
  },
  "userConfig": {
    "api_token": {
      "type": "string",
      "title": "API token",
      "description": "Token for the deployment API",
      "sensitive": true
    }
  }
}

未知のトップレベルのキーは取り除かれ、プラグインは読み込まれます（claude plugin validate は警告として報告します）。一方、userConfig のオプション・channels の項目・lspServers の設定・monitors の項目は厳格なオブジェクトで、中の未知のキーはエラーになり、プラグインは読み込まれません。

検証する#

claude plugin validate が、マニフェストの権威ある確認です。プラグインのディレクトリに対してシェルで実行します。

claude plugin validate ./my-plugin

.mcp.json、mcpServers が名指す .json ファイル、plugin.json の中のインラインで宣言した各 MCP サーバーの項目も検査されます（v2.1.281 以降）。エラーは、読み込み時に捨てられる項目、マニフェストが宣言していないオプションへの ${user_config.KEY} の参照、有効な絶対 URL でないリモートの url です。警告は、ループバックでないホストへの http:// か ws:// の URL、資格情報そのままに見えるヘッダーの値です。

フィールド#

トップレベルのキーは次のとおりです。必須は name だけです。

型の欄の「パス」は、"./custom/commands" のようにプラグインのルートからの相対の文字列です。

• name：空でなく、空白・@・:・パスの区切り・制御文字・双方向の書式文字を含まない。kebab-case を使う。Claude Code がすべてのコンポーネントをこの下に置くので、プラグイン deploy-tools のエージェント reviewer は deploy-tools:reviewer と出る

claude plugin validate は、名前が Anthropic 自身のプラグインに見えないかも検査します。大文字小文字は無視し、区切りの連続は1つとして扱います。

エラーは Plugin name "<name>" is reserved: it passes as one of Anthropic's own、警告は Plugin name "<name>" reads as one of Anthropic's own と出ます。claude plugin init と claude plugin tag は、エラーになる名前を拒みます。名前を検査するのはこれらのコマンドだけで、拒まれる名前のプラグインでも、Claude Code はインストールして読み込みます。

• displayName：空白や任意の大文字小文字を含められ、名前空間や検索には使われない。マーケットプレイスから入れたプラグインでは、マーケットプレイスの項目の displayName が優先される
• version：semver として検査されない。設定すると、変えるまでその版に固定される。command の取得元のプラグイン、claude.ai がホストするマーケットプレイスのプラグイン、ローカルのパスから追加したマーケットプレイスからその場で読み込むプラグインは、このフィールドに固定されない
• defaultEnabled：ユーザーが enabledPlugins で設定していないときに有効で始めるか。既定は true。有効なプラグインが依存するプラグインは、この値にかかわらず有効で始まる。マーケットプレイスの項目の同じフィールドが、これを上書きする。ユーザーの enabledPlugins の項目は一度書かれると、更新をまたいで残るので、あとのリリースで defaultEnabled を変えても、既存のユーザーの設定は変わらない
• dependencies：各項目は "name"、"name@marketplace"、または { "name": "...", "marketplace": "...", "version": "..." }。名前だけのものは、このプラグイン自身のマーケットプレイスで解決される（プラグインを作って配る）
• settings：agent と subagentStatusLine だけが効き、他のキーは読み込み時に捨てられる。プラグインのルートの settings.json が、このキーに優先する

ディレクトリ掲載用のフィールド#

Anthropic のディレクトリは、プラグインを申請すると、plugin.json の icon・documentationUrl・supportUrl・privacyPolicyUrl・termsOfServiceUrl を掲載に使います。Claude Code は読み込み時にこれらを無視します。書くのは plugin.json だけにします。マーケットプレイスの項目に書くと、claude plugin validate が、それぞれを未知のフィールドとして報告します。

icon にはプラグインの中の画像ファイルのパス（./logo.png など）を、4つの URL のフィールドには https:// の URL を書きます。

claude plugin validate は、Claude Code v2.1.281 以降でこれらのフィールドを警告なしで受け付けます。それより前の版は、それぞれに Unknown field の警告を出すので、--strict の実行はその版で失敗します。

コンポーネントのパスの形#

どのコンポーネントのキーも、プラグインのルートからの相対パスを受けます。hooks・mcpServers・lspServers・experimental.monitors はインラインの設定も、commands はオブジェクトの対応づけも、mcpServers は MCP バンドルのパスと URL も受けます。

agents・skills・outputStyles・workflows・experimental.themes は、1つのパスかパスの配列を取ります。agents の項目は .md ファイル、skills の項目はディレクトリで、残りの3つはディレクトリかファイルです。

{
  "agents": ["./custom-agents/reviewer.md", "./custom-agents/tester.md"],
  "skills": ["./extra-skills/", "."],
  "outputStyles": "./styles/"
}

commands#

commands は、パス、パスの配列、またはオブジェクトの対応づけを取ります。パスは平らな .md のコマンドファイルかディレクトリです。対応づけでは、各キーがプラグインの接頭辞のあとのコマンド名になります（プラグイン deploy-tools の "about" は /deploy-tools:about で動く）。各値は source か content のちょうど1つを設定し、両方か両方なしの項目は検証に失敗します。

{
  "commands": {
    "status": { "source": "./commands/status.md", "argumentHint": "[env]" },
    "about": { "content": "Explain what this plugin provides." }
  }
}

hooks#

hooks は、.json ファイルのパス、settings.json の hooks と同じ形のインラインのフックオブジェクト、または両方を混ぜた配列を取ります（イベントとハンドラのフィールドはフックのリファレンス）。フックのファイルは、イベントの対応づけを、最上位の "hooks" キーで包みます（hooks/hooks.json と同じ形）。包みのない、イベントの対応づけだけのファイルは、読み込みに失敗します。インラインのオブジェクトは、包みのない、イベントの対応づけそのものです。

宣言したものは、hooks/hooks.json があればそれとマージされます。次の配列は、フックのファイルを1つ読み込み、インラインの PostToolUse のフックを1つ宣言します。

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

その配列が指すファイルは、自分のイベントの対応づけを "hooks" で包みます。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/check-command.sh" }
        ]
      }
    ]
  }
}

mcpServers#

mcpServers は、.json ファイルのパス、MCP バンドルのパスか URL、インラインの対応づけ、またはそれらを混ぜた配列を取ります。サーバー設定のフィールドはMCP サーバーをつなぐにあります。Claude Code は、プラグインのルートの .mcp.json を先に読み、宣言した各形を順に読みます。あとで宣言した同名のサーバーが、前のものを置き換えます。

バンドルのパスか URL は .mcpb か .dxt で終わる必要があり、他の拡張子は検証に失敗します。

lspServers#

lspServers は、.json ファイルのパス、サーバー名を設定に対応づけるインラインの対応づけ、またはそのどちらかの配列を取ります。プラグインのルートの .lsp.json を先に読み、宣言した各設定を順に読みます。あとで宣言した同名のサーバーが前のものを置き換えます。各サーバー設定は厳格なオブジェクトで、未知のキーは検証に失敗します。

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

Anthropic がプラグインとして出している言語サーバーと実行時の挙動はプラグインを使うのコードインテリジェンスの節にあります。

monitors#

experimental.monitors は、.json ファイルのパスかインラインの配列を取ります。キーを省くと、あれば monitors/monitors.json が読み込まれます。各項目は、次のフィールドを持つ厳格なオブジェクトです。

{
  "experimental": {
    "monitors": [
      {
        "name": "deploy-status",
        "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/poll-deploy.sh",
        "description": "Deployment status changes",
        "when": "on-skill-invoke:deploy"
      }
    ]
  }
}

モニターの command は ${user_config.*} を参照できません（下の「シェルを通るフィールド」）。

パスの規則#

マニフェストのコンポーネントのパスは、プラグインのルートからの相対で、./ で始める必要があります。commands/foo.md のようなパスは検証に失敗します。skills と mcpServers には、この規則の外の形が1つずつあります。

• skills："." も受ける。"." と "./" はどちらもプラグインのルートを指す。v2.1.221 より前は "." が検証に失敗したので、それより前の版でも読み込ませるなら "./" を使う
• mcpServers：https:// のバンドルの URL も受ける

どのコンポーネントのパスも、プラグインのルートの内側に解決され、存在する必要があります。claude plugin validate が、各コンポーネントのキーのパスを検査します。

• ルートの内側であること：外へ解決されるパスは読み込まれず、/plugin の「Errors」タブに <component> path escapes plugin directory: <path> と出る。たいていは .. を含むパスで、claude plugin validate は Path contains ".." which could be a path traversal attempt というエラーを出す
• 存在すること：存在しないパスは読み込まれず、「Errors」タブに <component> path not found: <path> と出る。claude plugin validate は Path not found を報告する
• outputStyles・lspServers・monitors・themes のパスの検査は、v2.1.283 以降

experimental.evals はコンポーネントのパスではないので、この節の規則は当たらず、claude plugin eval が実行時に値を検査します。値は、プラグインのルートの下のディレクトリの名前（"quality/evals" など。先頭の ./ はあってもなくてもよい）です。配列のときは最初の項目だけが使われます。値が受け付けるものと、使えない値のときの動きは、プラグインの評価（evals）にあります。

キーごとに、既定の場所との関係が違います。

commands を設定すると、既定の commands/ は走査されません。既定を残して足すには、"commands": ["./commands/", "./extras/"] のように明示します。commands/ のような既定のフォルダがあるのに、それを置き換えるマニフェストのキーも設定すると、マニフェストのパスだけが読み込まれ、claude plugin list と /plugin に Default <folder>/ folder is ignored because the manifest sets "<key>" という警告が出ます。警告を避けるには、そのフォルダ内のパスを指定します（"commands": ["./commands/deploy.md"] は、既定のフォルダ内のファイルを指すので警告が出ません）。

userConfig#

userConfig は、プラグインを有効にするときに Claude Code がユーザーへ尋ねる値を宣言します。キーは、英数字とアンダースコアからなる識別子で、数字で始められません。各値は、次のフィールドを持つ厳格なオブジェクトで、未知のキーは検証に失敗します。

有効な各プラグインの各オプションは、sensitive のものと multiple の一覧を除き、/config パネルにも行として出ます（v2.1.269 以降）。

{
  "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
    }
  }
}

options で値を固定の一覧から選ばせられます。default は一覧の値の1つにするか、required: true にして選ばせます。

{
  "userConfig": {
    "tone": {
      "type": "string",
      "title": "Tone",
      "description": "Voice for generated replies",
      "options": ["neutral", "warm", "formal"],
      "default": "neutral"
    }
  }
}

• options を宣言したフィールドが1つでもあると、v2.1.271 より前の Claude Code ではプラグインが読み込めない
• options は、multiple でも sensitive でもない string に適用される。各選択肢は1〜64文字のただのラベルで、他は claude plugin validate が報告する。この規則に反する options のプラグインは読み込みに失敗する
• 保存先：sensitive でない値は、ユーザーの settings.json の pluginConfigs に保存され、sensitive の値は、プラットフォームの安全な資格情報の保管場所に入る（pluginConfigs を読む設定ファイルは設定キー一覧）
• 参照の仕方：${user_config.KEY} は、MCP サーバーの設定・LSP サーバーの設定・フックの exec 形式の args・スキルとエージェントの本文で置換される（スキルとエージェントの本文では、sensitive でない値だけが置換され、sensitive の値はプレースホルダーになる）。CLAUDE_PLUGIN_OPTION_<KEY> は、すべてのオプションについてフックのプロセスに渡される（<KEY> は大文字。api_token を、シェル形式のフックは $CLAUDE_PLUGIN_OPTION_API_TOKEN で読む）

シェルを通るフィールド#

シェル形式のフックのコマンド、モニターのコマンド、MCP の headersHelper は、${user_config.*} を拒否します。置換した値をシェルが解析し直してしまうので、これらのフィールドで参照するコンポーネントは、実行されずエラーになります。値を届ける別の方法は次のとおりです。

channels#

channels は、チャットアプリへの橋渡しのような、プラグインが提供するメッセージのチャネルを宣言します。宣言すると、プラグインを有効にするときにチャネルの設定を尋ねられます（サーバーがメッセージを注入する方法はチャネル）。各項目は、プラグインの MCP サーバーの1つに結び付く厳格なオブジェクトです。

{
  "mcpServers": {
    "telegram": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"],
      "env": { "BOT_TOKEN": "${user_config.bot_token}" }
    }
  },
  "channels": [
    {
      "server": "telegram",
      "displayName": "Telegram",
      "userConfig": {
        "bot_token": {
          "type": "string",
          "title": "Bot token",
          "description": "Telegram bot token",
          "sensitive": true
        }
      }
    }
  ]
}

環境変数#

Claude Code は、プラグインのコンポーネントに3つのパス変数を渡します。次の表のフィールドで ${NAME} として参照し、受け取るプロセスでは環境変数として読みます。

${CLAUDE_PLUGIN_ROOT} はプラグインの更新で変わるので、そこに状態を書きません。${CLAUDE_PLUGIN_DATA} のディレクトリは、既定では、プラグインを最後のインストール先から削除するときに消えます（--keep-data などで残る場合は下の plugin uninstall）。

この変数は、メインのセッションでもサブエージェントでも、Claude が Bash ツールで動かすコマンドの環境には入っていません。スキル・コマンド・エージェントの本文では、Markdown の本文に ${...} の参照を書くと、内容を読み込むときに Claude Code がパスをその場で置換します。

置換したパスは1つの引数に保ちます。フックのコマンドは、args を使う exec 形式にすると、各パスが引用符なしで1つの引数になります。シェル形式のフックとモニターのコマンドは、変数を二重引用符で囲み、空白を含むパスを1語にします。フックのファイルのシェル形式のコマンドで、これらの変数を引用符の外に置くと、フックの shell が "powershell" でない限り、claude plugin validate が警告します。Windows では、置換したパスは、シェルがバックスラッシュをエスケープと読まないように、スラッシュを使います。

標準の配置#

マニフェストが別の場所を指さないとき、各コンポーネントの種類は、プラグインのルートの下の既定の場所を使います。

deploy-tools/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   └── deploy/
│       └── SKILL.md
├── commands/
│   └── status.md
├── agents/
│   └── reviewer.md
├── hooks/
│   └── hooks.json
├── monitors/
│   └── monitors.json
├── output-styles/
│   └── terse.md
├── themes/
│   └── dracula.json
├── workflows/
│   └── release-audit.js
├── bin/
│   └── deploy-tool
├── scripts/
│   └── format.sh
├── settings.json
├── .mcp.json
└── .lsp.json

プラグインのルートの CLAUDE.md はコンテキストとして読み込まれず、claude plugin validate が見つけると警告します。Claude のコンテキストに入る指示を入れるには、スキルに書きます。

マーケットプレイスの項目とマニフェスト#

マーケットプレイスの項目は、項目自身のフィールドと、ディレクトリ掲載用のフィールドを除くこのページのすべてのフィールドを、並べて受け付けます（strict を含む）。strict は、項目が、自分の plugin.json を持つプラグインにコンポーネントを足せるかを決めます。既定は true です。項目は、マニフェストとして働くか、それに足すか、衝突します。

• plugin.json が無い：strict にかかわらず、項目がマニフェストになる。項目の hooks はインラインのオブジェクトの形でだけ読み込まれる。ファイルパスや配列だと、「Errors」タブに not yet supported in a marketplace entry というエラーが出る
• plugin.json があり、strict が未設定か true：マニフェストを読み込み、項目の commands・agents・skills・outputStyles・themes をそれに足す。hooks は、項目のイベントごとのマッチャーが、マニフェストの同じイベントのマッチャーを置き換え、マニフェストだけが宣言するイベントはそのまま残る
• plugin.json があり、strict: false：項目が commands・agents・skills・hooks・outputStyles・themes のどれかを宣言すると衝突で、プラグインは Plugin <name> has conflicting manifests で読み込みに失敗する

マーケットプレイスの項目のルートを source にして特定の skills サブディレクトリを並べると、そのサブディレクトリだけが読み込まれ、プラグインの既定の skills/ は走査されません（マニフェストの skills キーは、既定に足される）。メタデータの優先順位は、strict にかかわらず固定です。

• defaultEnabled と表示用のフィールド：項目の defaultEnabled と displayName などの表示用フィールドが、マニフェストのものを上書きする
• version：マニフェストの version が、項目の version を上書きする
• name：項目がマニフェストと別の name でプラグインを載せているとき、enabledPlugins は項目の名前を使い、コンポーネントはマニフェストの名前の下に置かれる

マーケットプレイス（marketplace.json）#

marketplace.json は、マーケットプレイスを定義するファイルで、名前・所有者・プラグインごとの項目を持ちます。各項目のプラグインの取得元が、そのプラグインを Claude Code が取得する場所を示します。マーケットプレイスの取得元は別のオブジェクトで、marketplace.json 自体を取得する場所を示します（設定に書くか、claude plugin marketplace add が作ります）。

ファイルはマーケットプレイスのディレクトリの .claude-plugin/marketplace.json に置きます。リポジトリ内の別の場所に置くときは、ユーザーが extraKnownMarketplaces で取得元の path を指定してマーケットプレイスを宣言する必要があります（claude plugin marketplace add にはその指定がありません）。.claude-plugin/ を含むディレクトリがマーケットプレイスのルートで、相対のプラグインの取得元はすべてそこから解決されます。ユーザーは name ごとに1つのマーケットプレイスを登録するので、同じ名前の2つは同時に登録できません。未知のトップレベルのキーや項目のキーは拒否されず無視され、打ち間違いが静かに読み込まれます（claude plugin validate が各未知のキーを警告します）。

予約された名前#

マーケットプレイスに、次の名前は付けられません。

登録済みのマーケットプレイスが公式を装う名前のために読み込まれなくなると、claude plugin list と /plugin が Claude Code refuses the marketplace name "<name>" と報告し、マーケットプレイスを削除するよう案内します（削除すると、そのプラグインもアンインストールされ、保存データも消えます。この表示は v2.1.282 以降）。

トップレベルのフィールド#

marketplace.json から Claude Code が読むキーは次のとおりです。name・owner・plugins が必須です。

プラグインの項目#

plugins 配列の各オブジェクトが、プラグインの名前と取得場所を示します。name と source が必須です。項目は、ディレクトリ掲載用のフィールドを除く plugin.json の全フィールド（description・version・author・commands・hooks など）も受け付けます。次の表は、項目自身のフィールドと、項目の中では意味が変わるマニフェストのフィールドです。

項目のフィールドが、自分の .claude-plugin/plugin.json を持つ取得したプラグインと、持たないものとで、どう適用されるかが違います。plugin.json が無ければ、項目がマニフェストで、項目の mcpServers・lspServers・userConfig・channels も含め、項目が受け付けるすべてのマニフェストのフィールドが適用されます。plugin.json があれば、plugin.json がマニフェストで、strict が、項目の6つのコンポーネントのフィールド（commands・agents・skills・hooks・outputStyles・themes）をそれに合成するか、衝突として拒否するかを決めます。項目の mcpServers・lspServers・userConfig・channels は適用されないので、plugin.json に宣言します。

項目の hooks は、イベント名をマッチャーの配列に対応づけるインラインのオブジェクトで書きます。ファイルパスか配列で書くと、claude plugin validate は通しますが、そのフックは動かず、Claude Code がプラグインについて not yet supported in a marketplace entry というエラーを報告します。ファイルベースのフックは、プラグイン自身の hooks/hooks.json か plugin.json に置きます。

表示用のフィールド（displayName・description・author・homepage・repository・license・keywords）は、項目と plugin.json のどちらにも設定できます。項目に設定したフィールドは、plugin.json が別の値を設定していても項目の値が、項目が未設定のものは plugin.json の値が、インストールの前後の一覧と詳細で見えます。インストールの前に Claude Code が plugin.json を読めるのは、プラグインのファイルがマーケットプレイスの中にある相対パスの取得元の項目だけです。それ以外の取得元では、インストールするまで項目自身のフィールドだけが見えます。

strict モード#

strict は、取得したプラグインが自分の plugin.json を持ち、項目もコンポーネントのフィールドのどれかを宣言しているときの動作を決めます。

プラグインの取得元#

項目の source は、そのプラグインを Claude Code がどこから取得するかを示します。相対パスの文字列か、source キーが種類を示すオブジェクトです（"source": { "source": "github", "repo": "your-org/formatter" }）。

url と github は、マーケットプレイスの取得元の種類でもあり、そこでの url は git リポジトリではなく marketplace.json への直接のリンクです。git はマーケットプレイスの取得元だけ、npm は両方にあり、git-subdir・archive・command はプラグインの取得元だけです。マーケットプレイスのリポジトリ自体のサブディレクトリにあるプラグインには相対パスを、他のリポジトリのサブディレクトリには git-subdir を使います。github・url・git-subdir は、ref と sha を共有します。

• ref：ブランチかタグ。既定はリポジトリの既定ブランチ
• sha：40文字の小文字のコミット SHA。ref と sha の両方があると、sha をチェックアウトする。GitHub・GitLab・Bitbucket など多くの git ホストでは、ref が指すブランチやタグが上流で削除されていても、コミットがリポジトリから到達できる限り、インストールは成功する。AWS CodeCommit のように SHA でのコミットの取得に対応しないサーバーでは、ref が存在し、固定したコミットがそこから到達できる必要がある

取得、キャッシュ、版の付き方は、下の「読み込みの規則」にあります。

相対パス：パスはマーケットプレイスのルートから解決されます（./plugins/formatter は、マーケットプレイスのファイルが <root>/.claude-plugin/ にあっても <root>/plugins/formatter）。.. を含むパスは検証に失敗します。macOS と Linux では、先頭の ./ の後ろのどこかにバックスラッシュを含む項目のパスを拒否するので、スラッシュで書きます。

{ "name": "formatter", "source": "./plugins/formatter" }

相対パスが解決できるのは、Claude Code がマーケットプレイスのファイルを持っているときだけです。取得元の種類によって違います。

• github・git・file・directory：マーケットプレイスのファイルを持っている
• url：marketplace.json だけを取得するので、相対パスは解決できない。各プラグインに、github や git-subdir のようなオブジェクトの取得元を与える
• settings：相対パスは丸ごと拒否される

名前だけ（/ を含まない1つのディレクトリ名。"formatter"）で書くには、metadata.pluginRoot に、それらが解決されるディレクトリを設定します（"pluginRoot": "./plugins" なら "source": "formatter" は ./plugins/formatter。v2.1.239 以降）。metadata.pluginRoot はマーケットプレイス内の相対パスである必要があり、すでに ./ で始まる取得元には影響せず、team-a/formatter のように / を含む取得元は名前だけではないので、metadata.pluginRoot があっても ./ の接頭辞が要ります。

github：repo は owner/repo、ref と sha は任意です。

{
  "name": "formatter",
  "source": {
    "source": "github",
    "repo": "your-org/formatter",
    "ref": "v2.0.0",
    "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
  }
}

url：url は完全な git の URL（https://・http://・file://・git@）です。.git の接尾辞は不要なので、Azure DevOps と AWS CodeCommit の URL もそのまま使えます。owner/repo の略記は受け付けません。

{
  "name": "formatter",
  "source": {
    "source": "url",
    "url": "https://gitlab.example.com/your-group/formatter.git",
    "ref": "main"
  }
}

git-subdir：url は完全な git の URL か、GitHub の owner/repo の略記を受けます。path がプラグインを持つサブディレクトリで、Claude Code はそのサブディレクトリだけをチェックアウトします。https か SSH の URL では、Claude Code がサーバーに部分クローンを求めるので、部分クローンに対応するホストなら、大きなモノレポの中のプラグインを、リポジトリの残りをダウンロードせずに入れられます。

{
  "name": "formatter",
  "source": {
    "source": "git-subdir",
    "url": "https://github.com/your-org/monorepo.git",
    "path": "tools/formatter"
  }
}

npm：フィールドは、package（レジストリのパッケージ名（@your-org/formatter など）、版を付けた名前（@your-org/formatter@2.0.0 など）、またはパッケージの tarball ファイルへの https のリンク）、version（package が版なしの名前のときに使う、版・semver の範囲・dist-tag。省くと latest を取る）、registry（既定のレジストリに無いパッケージのレジストリの URL）です。パッケージのインストールスクリプト（preinstall・postinstall など）は動かず、取得中に依存もインストールされません。パッケージの package.json の隣に対応するロックファイルがあれば、別の段で、同じくスクリプトを無効にして、Node.js のパッケージ依存を入れます。

Claude Code は、取得の前に package の値を検査します。拒否された値は、値と理由を示すメッセージでインストールが失敗します。拒否されるものには次があります。

• git のアドレス、フォルダか file: のパス、npm: のエイリアス：git リポジトリには github・url・git-subdir の取得元を、マーケットプレイスの中のフォルダには相対パスを、エイリアスにはパッケージ自身の名前を使う
• github.com・gist.github.com・gitlab.com・bitbucket.org・git.sr.ht の tarball のリンク：GitHub のリリースのダウンロードでも拒否される。ただし gitlab.com/api/v4/ の下の GitLab の npm レジストリのリンクは除く
• http の tarball のリンク：インストールするユーザー自身の既定の npm レジストリを指すときを除き、拒否される

registry の URL は、インストールするユーザー自身の既定の npm レジストリでない限り https でなければなりません。ほかの http のレジストリでは、npm が接続する前にインストールが失敗します。

{
  "name": "formatter",
  "source": {
    "source": "npm",
    "package": "@your-org/formatter",
    "version": "^2.0.0",
    "registry": "https://npm.example.com"
  }
}

archive：url は https:// で、ループバック・リンクローカル・クラウドメタデータのホストを指せません（サイズ・タイムアウト・リダイレクト・展開の上限はプラグインを作って配る）。プラグインのルートは、zip の先頭か、1階層下にあってかまいません。sha256 はアーカイブのダイジェストを、大文字でも小文字でもよい64桁の16進数で書いたもので、設定すると、一致しないダウンロードを拒否します。

{
  "name": "formatter",
  "source": {
    "source": "archive",
    "url": "https://artifacts.example.com/formatter-2.0.0.zip",
    "sha256": "6bfa50e3d2e00c052b46abe51fff89346ac803e45771f76dcf6df1ab74cca5e1"
  }
}

command：IDE がユーザーの選んだツールチェーンのためにプラグインを出力する場合のように、ユーザーのマシンにインストールされたツールがプラグインのディレクトリを作るときに使います。Claude Code は、ユーザーがインストールか更新するときと、セッションごとに1回、そのコマンドを動かします。フィールドは次のとおりです。

{
  "name": "formatter",
  "source": {
    "source": "command",
    "command": "my-tool claude-plugin-path",
    "timeout": 120
  }
}

コマンドの要件は次のとおりです。

• シェルと作業ディレクトリ：sh（Windows では cmd.exe）で、ユーザーのホームディレクトリから動く。絶対パスか PATH 上のコマンドにする
• 出力：標準出力にプラグインのディレクトリの絶対パスをちょうど1行出し、timeout 秒以内に 0 で終了する
• ディレクトリの中身：コマンドの終了までに、プラグインが完全にそろっている。パスは実行ごとに違ってよい

コマンドが 0 以外で終了する、timeout を超える、1つの絶対パス以外を出力する、のときはインストールか更新が失敗します。出力したディレクトリが次のどれかのときも失敗します。

• プラグインの中身が無い：トップレベルに .claude-plugin/ も skills/・commands/・agents/・hooks/ も無い
• セッション自身のディレクトリ：Claude Code を起動したディレクトリ、またはその親
• ネットワークのパス：Windows で、出力したパスが UNC パス
• コピーするには大きすぎる：copy モードで、ディレクトリが256 MiB を超えるか、項目が20,000を超える

mode は、出力されたディレクトリをコピーするか、その場で使うかを決めます。

• copy：ディレクトリをプラグインのキャッシュへコピーし、プラグインの版をコピーしたファイルのハッシュから導く。コマンドの終了後に、ツールがディレクトリを削除や書き換えしてもよい。同一のファイルを出す再実行は最新とみなされる
• link：プラグインのキャッシュの項目に、出力されたディレクトリの各トップレベルの項目へのリンクを置き、その場でファイルを読み込む。コピーも内容のハッシュもなく、サイズの上限も当てはまらない。レンダリングした SDK のエクスポートのような、コピーするには大きすぎるディレクトリに使う

link モードのプラグインには、次の要件があります。

• ディレクトリをその場に置く：Claude Code は起動のたびにリンク経由でプラグインを読み込むので、プラグインがインストールされているあいだ、出力したディレクトリはそこに残す
• 新しい内容を伝えるには別のパスを出力する：版はファイルの中身ではなく、出力したディレクトリの実パスとトップレベルの項目から決まる
• トップレベルのシンボリックリンクはディレクトリの内側に保つ：トップレベルの項目が出力したディレクトリの外を指すシンボリックリンクだと、インストールは失敗する
• node_modules を含める：link モードでは Node.js のパッケージ依存のインストールを行わないので、必要なパッケージをすでに含むディレクトリを出力する
• ディレクトリの中で始めたセッション：出力したディレクトリかその下で始めたセッションは、プラグインを読み込まない
• Windows では使えない：link モードのプラグインのインストールを拒否する。そこでは "mode": "copy" を宣言する

ユーザーがコマンドを承認する方法はプラグインを使う、変更後にユーザーに見えるものはプラグインを作って配るにあります。管理者は、disableCommandPluginSources で command の取得元を止められます。

マーケットプレイスの取得元#

マーケットプレイスの取得元は、marketplace.json を取得する場所を示します。CLI でマーケットプレイスを追加するときは Claude Code が文字列から作り、設定では自分で書きます。

• claude plugin marketplace add：渡した文字列から Claude Code が取得元を作る
• extraKnownMarketplaces：source オブジェクトとして自分で書く
• strictKnownMarketplaces と blockedMarketplaces：管理者が、この2つのポリシーのリストに取得元を書く（前者が許可リスト、後者がブロックリスト）

url・git・github の名前は、マーケットプレイスの取得元では、プラグインの取得元と意味が違います。

マーケットプレイスの取得元の全種類を、フィールド、それを作る claude plugin marketplace add の入力、3つの設定キーでの扱いとともに示します。

デフォルト・制約・種類ごとの意味を持つフィールドは次のとおりです。

hostPattern・pathPattern・skills-dir・github の repo の owner/* の形は、2つのポリシーのリスト（strictKnownMarketplaces と blockedMarketplaces）でだけ有効です。

• hostPattern と pathPattern：Claude Code が取得元から取得する前に、取得元に対して試す正規表現
• skills-dir：取得元ではない。strictKnownMarketplaces を設定すると、このリストに {"source": "skills-dir"} を足すまで、スキルのディレクトリのプラグインは読み込まれなくなる
• owner/*：github の repo の値として、その GitHub のオーナーの下のすべてのリポジトリに合う。v2.1.223 以降

設定では、extraKnownMarketplaces はマーケットプレイス名から、source を持つオブジェクトへの対応づけです。strictKnownMarketplaces と blockedMarketplaces は取得元オブジェクトの配列です（許可リストとブロックリストの照合の規則と記述例はプラグインを作って配る）。

{
  "extraKnownMarketplaces": {
    "your-marketplace": {
      "source": {
        "source": "git",
        "url": "https://git.example.com/your-org/your-marketplace.git",
        "ref": "main"
      }
    }
  }
}

{
  "strictKnownMarketplaces": [
    { "source": "github", "repo": "your-org/*" },
    { "source": "hostPattern", "hostPattern": "^git\\.example\\.com$" }
  ]
}

検証メッセージ#

claude plugin validate <path> は、マーケットプレイスのルートかマーケットプレイスのファイルそのものを受けます。エントリは plugins.1.source か plugins[1].source のように、インデックスで名指しされます。plugins[2] plugin.json → のように項目のインデックスと plugin.json → が付いたメッセージは、そのプラグイン自身のファイルについてのものです。Claude Desktop のフラグ名に触れる警告は、Claude Desktop が拒否する名前を指します。マーケットプレイスの階層のメッセージと、それが指すフィールドは次のとおりです。

source の Invalid input は、オブジェクトがどの取得元の種類にも合わないことを意味します。次の原因を確かめます。

• "." か metadata.pluginRoot の下の名前だけの形以外で、./ で始まらない相対パス
• .. を含む npm の package
• プラグインの取得元の種類でない source の種類
• 必須のフィールドが欠けているか型が違う既知の種類（repo の無い github など）

検証がすべての失敗を見つけるわけではありません。ファイルパスや配列で書いた項目の hooks は検証を通り、プラグインの読み込み時にだけエラーが出ます。source の取得エラーも、検証ではなくインストールのあとにだけ出ます。読み込めなかったプラグインは claude plugin list がエラーつきで示します。

claude plugin コマンド#

claude plugin <subcommand> を、シェルかスクリプトから、Claude Code のセッションの外で実行します。/plugin のパネルを開かずに、プラグインを入れて管理できます。claude plugins は claude plugin の別名です。claude plugin --help で、お使いの版にあるサブコマンドを確かめられます。

• 終了コード：成功は 0、失敗は 1。validate は予期しないエラーで 2 も返し、eval は専用のコードを加える
• プラグインの引数：<plugin> は、プラグインの name か name@marketplace。2つのマーケットプレイスが同じ名前を出しているときは、修飾した形を使う。configure は修飾した形だけを取る
• スコープ：--scope は user・project・local を取り、コマンドが書く設定ファイルを示す。update は managed も取る

plugin init#

~/.claude/skills/<name>/ に、新しいプラグインの雛形を作ります。次のセッションから、インストールなしで <name>@skills-dir として読み込まれます。<name> は、~/.claude/skills/ の下のディレクトリ名と、そのマニフェストのプラグインの name になります。別の場所を指定するフラグはありません（プロジェクトの中に作るならプラグインを作って配る）。

claude plugin init <name> [options]
claude plugin init my-helper --with skills hooks

Claude Code は書いたものを検証し、Created plugin "my-helper" at ~/.claude/skills/my-helper と、読み込まれる ID と、無効にする claude plugin disable のコマンドを出します。安全に雛形を作れないときは、何も書かずに 1 で終了し、メッセージが理由を示します。一般的な理由は、未知の --with の値、--force なしでの対象の既存の雛形、スキルのディレクトリのプラグインを止める管理設定です。

plugin install#

追加済みのマーケットプレイスからプラグインを入れます。

claude plugin install <plugin> [options]
claude plugin install formatter@my-marketplace --scope project

ほとんどのプラグインはプロンプトなしで入ります。マーケットプレイスの項目がコマンドを実行して入れるプラグインや、ダウンロードに headersHelper を設定するプラグインでは、Claude Code が先にコマンドを出して Run this command now? [y/N] と尋ねます。自分の端末から -y を渡すと、プロンプトなしでそのコマンドを承認します。

• 標準入力か標準出力が TTY でなく、-y も --accept-command も渡さないとき：インストールは拒否される。出力は、コマンドが表示されただけだと述べ、終了コードは 1
• Claude が Bash ツールでコマンドを実行するとき：-y は無視される。自分の端末から実行する

成功すると Successfully installed plugin: formatter@my-marketplace (scope: project) と出ます。新しく入らなかったときは、理由が出ます。

--json では、標準出力の最後の行が1つの JSON オブジェクトです。マーケットプレイスが宣言するコマンドは、その前に出るので、その最後の行だけを解析します。次の3つのフィールドは常にあります。

• command：実行したサブコマンド（install など）
• outcome：ok か failed
• message：人向けの結果の説明

pluginId・scope・failureCode などは、当てはまるときだけ出ます。plugin uninstall・plugin update・plugin enable・plugin disable の --json も、そのサブコマンド固有のフィールドを持つ同じオブジェクトを出します。--scope が不正といった使い方の誤りは、結果の行を出さず、理由を標準エラーへ出して 1 で終了します。

--json の実行が、マーケットプレイスの宣言したコマンドを表示して実行しなかったときは、failed の結果に shownCommand オブジェクト（表示したコマンド、そのプラグイン、コマンドの sha256 など）も付きます。そのコマンドだけを承認するには、その sha256 を --accept-command に渡して、自分の端末から再実行します（このフラグは Claude Code のセッションの中では効きません）。sha256 は、そのコマンド・プラグイン・マーケットプレイスのカタログに対する承認としてだけ数えられ、表示後にどれかが変わっていると、Claude Code は sha256 を受け付けず、コマンドをもう一度表示します（実行自身のマーケットプレイスの更新が取り込んだ変更も数えます）。shownCommand.acceptCommandMatched が false なら、渡した sha256 は、いま表示されているコマンドと一致していません。そのコマンドを確認してから、その sha256 で再実行します。

plugin uninstall#

1つのスコープから、入れたプラグインを外します。

claude plugin uninstall <plugin> [options]
claude plugin uninstall formatter@my-marketplace --scope project

成功すると Successfully uninstalled plugin: formatter (scope: project) と出ます。そのスコープに入っていないと、Failed to uninstall plugin "formatter@my-marketplace": で始まる行を出して 1 で終了します。失敗の行が "formatter" was not uninstalled: と設定ファイルを名指しして続くときは、そのスコープの設定がまだプラグインを有効にしていないと確認できなかったので、プラグインは保存したものとともに入ったままです（--json では failureCode: "settings_still_on"。この確認は v2.1.282 以降）。

プラグインを、入っている最後のスコープから外すと、保存済みのオプションとシークレットと、データのディレクトリ ~/.claude/plugins/data/<id>/ も消えます。例外は3つです。

• --keep-data：データのディレクトリが残る
• 同じフォルダを別のインストール済みプラグインが使っている（このプラグインの ID と大文字小文字だけが違うもの）：データのディレクトリが残る
• そのスコープからプラグインを外したあと、インストール済みのプラグインの一覧を読み戻せない：プラグインが別のスコープにまだ入っているかもしれないので、オプション・シークレット・データのディレクトリがすべて残る。アンインストールは成功し、メッセージが、残ったものとその消し方を示す。--json では、結果に savedKept: "install_records_unreadable" が付く

--json では keptData が、ディレクトリが残ったかを報告し、/plugin は残ったとき · data preserved と表示します。--keep-data なしでディレクトリが残る場合の報告は v2.1.281 以降、savedKept は v2.1.282 以降です。

plugin enable と plugin disable#

無効なプラグインを有効にします（enable）。プラグインを、アンインストールせずに無効にします（disable）。claude.ai から同期されたプラグインには、<name>@synced を渡します。

claude plugin enable <plugin> [options]
claude plugin disable [plugin] [options]

--scope なしでは、local・project・user の順に設定ファイルを調べ、そのプラグインに言及する最初のスコープを使います。プラグインが宣言されていないスコープを --scope で渡すと、上書きを書くか、失敗します。

• 宣言しているスコープより優先するスコープ：渡したスコープに上書きを書く（claude plugin disable formatter --scope local は、project で有効なプラグインを自分だけ無効にする）
• それ以外のスコープ：Plugin "formatter" is installed at project scope, not user. Use --scope project or omit --scope to auto-detect. で失敗する

すでに有効（無効）なとき、Plugin "formatter" is already enabled（is already disabled）と出て 1 で終了します。--json では、結果が "failureCode": "already_in_goal_state" と "alreadyInGoalState": true を持つので、スクリプトはこの場合を成功として扱えます。disable にプラグイン名も --all も渡さないと、Please specify a plugin name or use --all to disable all plugins と出て 1 で終了します。

• enable：プラグインが依存を宣言していれば、それも有効にする。依存が入っていない（各依存の claude plugin install コマンドを出して失敗する）、依存が組織のプラグインのポリシーでブロックされている（ブロックされた依存を名指しして失敗する）、依存が対象のスコープより優先するスコープで false になっている（そのスコープで依存を有効にするか、--scope でそこへ書く）ときは失敗する
• disable：他の有効なプラグインがそれに依存している（名指しされた依存元を先に無効にするよう案内して失敗する）、組織が同期されたプラグインとして必須にしている（失敗し、何も保存しない）ときは、まだ要るプラグインなので失敗する

成功すると Successfully enabled plugin: formatter (scope: project)（判定したスコープを名指しする）、Successfully disabled plugin: formatter (scope: project) と出ます。

plugin update#

プラグインを、マーケットプレイスが出す最新の版に更新します。新しい版は、次のセッションか、開いているセッションで /reload-plugins を実行したあとに読み込まれます。

claude plugin update <plugin> [options]
claude plugin update formatter@my-marketplace

--scope を省略すると、現在のプロジェクトでプラグインが入っている、最も具体的なスコープ（local・project・user・managed の順に確認）で更新します。v2.1.281 より前は、--scope を省略すると user を使ったので、project か local だけに入っているプラグインの更新は Plugin "<name>" is not installed at scope user で失敗しました。その版では --scope を渡します。managed は、更新はできるがインストール先にはできない唯一のスコープです（管理者が入れたプラグインについてはプラグインを作って配る）。

Checking for updates for plugin "formatter@my-marketplace"… と出て、結果が続きます。新しいものが無いと formatter is already at the latest version (1.0.0). と出て 0 で終了します（依存のインストールを再試行して、それが失敗したときを除く）。名前だけも渡せ、Claude Code が入れたプラグインと照合します。別のマーケットプレイスの入れたプラグインが同じ名前のときは、更新を拒否し、実行すべき修飾した plugin-name@marketplace-name のコマンドを並べます（名前だけでの更新は v2.1.246 以降）。

すでに最新の版のときは、キャッシュのコピーにある、終わっていない依存のインストールを再試行することもあります。再試行が動く場合と飛ばす場合は、トラブルシューティングの「The packages it lists are not installed」にあります。再試行が失敗すると、出力は Failed to update plugin "formatter@my-marketplace" と理由になり、終了コードは 1 です。v2.1.287 より前は、インストールを再試行せずに、プラグインが最新の版だと報告しました。

plugin list#

入れたプラグインを、版・スコープ・状態とともに一覧にします。

claude plugin list [options]

人向けの出力は、プラグインの読み込まれ方でグループ分けされます。

どのグループにも無いと、No plugins installed. Use `claude plugin install` to install a plugin. と出ます。--json では、インストールごとに1つのオブジェクトの配列を出します。id・version・scope・enabled・installPath は常にあり、他は当てはまるときだけ出ます。

--json --available では、配列の代わりに1つのオブジェクトを出します。installed が入れたプラグインのオブジェクトの配列、available が、入れていないマーケットプレイスのプラグインごとに1つのオブジェクトです。

plugin details#

プラグインのコンポーネントの一覧と、予想されるトークンのコストを出します。プラグインは読み込まれている必要があります（インストール済み・スキルのディレクトリで見つかったもの・同じコマンドの --plugin-dir か --plugin-url で渡したもの）。<name> はプラグインの name か name@marketplace です。--help 以外のフラグはありません。

claude plugin details <name>

プラグインの名前・版・説明・取得元を出し、続けて次の節を出します。

2つのコストの数字の意味はプラグインを作って配るのコスト計測の節にあります。読み込まれていないプラグインでは、Plugin "formatter" not found. Run `claude plugin list` to see installed plugins, or pass --plugin-dir <path> to load one from disk. と出して 1 で終了します。

plugin configure#

入れたプラグインの userConfig のオプションと設定済みかを表示するか、標準入力で渡された値を保存します（v2.1.285 以降）。

claude plugin configure <plugin>
claude plugin configure formatter@my-marketplace --values-stdin < values.json

フラグなしでは、各オプションを、required か optional、マニフェストが sensitive と宣言するオプションには sensitive、set か not set の最大3つのラベルで一覧にします。保存された値は出しません。--json では、sensitive でないオプションの保存値を含み、sensitive なものの文字列は出しません。値を保存するには、オプションのキーを文字列の値に対応づける JSON オブジェクトをファイルに書き、標準入力で渡します（{"api_url": "https://example.com"} を持つ values.json なら、上の2行目のコマンド）。

Claude Code は、各値をオプションの宣言した型で検証し、Configuration saved. Restart Claude Code to apply it. と出します。マニフェストが宣言していないキーか、検証に失敗する値があると、何も保存せず、Failed to save configuration: と理由を出して 1 で終了します（--json では、拒否された値が、message と、1つのオプションの誤りなら option キーを持つ refused フィールドの付いたオブジェクトも標準出力へ出す）。claude plugin list が示す、プラグインの完全な name@marketplace の ID を渡します。名前だけは受け付けません。その ID のプラグインが読み込まれていないと、No installed plugin has the id "<plugin>". と出て 1 で終了します。同梱の MCP サーバーの設定は、plugin install --config、または /plugin の「Configure」を使います。

plugin prune#

どのインストール済みプラグインにも要らなくなった、自動で入った依存を外します。自分で入れたプラグインは外しません。

claude plugin prune [options]
claude plugin prune --dry-run

--dry-run は、孤立した依存を一覧にして (dry run — nothing removed) で終わります。外すものが無いと Nothing to prune で始まる行を出します。--dry-run なしでは、プロンプトで確認するか -y を渡したときだけ外します。プロンプトにどう答えても終了コードは 0 です。

plugin eval#

プラグインの eval ケースを動かし、採点した結果を報告します（v2.1.269 以降。ケースの形式・グレーダー・結果・CI での使い方はプラグインの評価（evals））。各ケースは、プロンプトとグレーダーで、対象のプラグインだけを読み込んだ隔離したセッションで複数回動かされ、既定では、差を示すためプラグインなしでも動かされます。

claude plugin eval [target] [options]

target（省略可）の既定は現在のディレクトリで、次の形を取ります。プラグインのディレクトリ、1つの prompt.md か case.yaml ファイル、入れたプラグインを name か name@marketplace で、name@skills-dir。--tag・--allow-tools・--json の前に target を置きます。これらのオプションは、後ろの語を値として取るので、あとに書いた target は、タグ・ツール名・JSON の出力先と読まれます。主なオプションは次のとおりです（--case・--tag・--output-dir・--report・--allow-real-servers・--keep-temp・--verbose などは claude plugin eval --help で見ます）。

plugin eval init#

カレントディレクトリのプラグインの eval スイートを作ります（v2.1.269 以降）。プラグインのルート（.claude-plugin/plugin.json かスキルの SKILL.md があるディレクトリ）で実行します。別のディレクトリにわざと作るには --eval-dir を渡します。

claude plugin eval init [name] [options]

端末では、作成のインタビューのために対話の Claude Code のセッションを開きます。インタビューで Claude は、プラグインを読み、何をうまくやるべきかを尋ね、ケースとグレーダーを提案し、ケースのファイルを書き、ケースを動かして、グレーダーが自分と同じように採点するか、採点を一緒に見直します。--bare を付けるか端末がないと、代わりに1ケースの空のテンプレートを書きます。Claude Code のセッション内から実行すると、テンプレートを書かず、そのセッションが従うインタビューの指示を表示します。name（省略可）はケース名で、--bare か端末なしでは、そのケースの空のテンプレートを書くため必須です。ケース名は英字か数字で始まり、英数字・.・_・- だけを含みます。どのプラットフォームでも、con や . で終わる名前のように、Windows が保存できない名前は拒否します。

plugin tag#

プラグインのリリースに、<name>--v<version> という名前の注釈付き git タグを作ります。タグを付ける前に、plugin.json と、それを載せるマーケットプレイスの項目が、版で一致しているかを確認します。[path] はプラグインのディレクトリで、既定はカレントディレクトリです。そのプラグインを載せる .claude-plugin/marketplace.json まで、そのディレクトリから上に辿って、マーケットプレイスの項目を探します。

claude plugin tag [path] [options]
claude plugin tag plugins/formatter --dry-run

--dry-run は、計画（プラグイン名、版とそれを得たファイル、該当するマーケットプレイスの項目、タグ名、実行する git tag と git push のコマンド）を出します。--dry-run なしでは Created tag formatter--v1.0.0 と、Pushed to origin か自分で実行する push のコマンドを出します。push が失敗してもタグは手元にできていて、コマンドはエラーで終わります。安全にタグを付けられないときは、1 で終了して理由を出します。一般的な理由は、plugin.json にもマーケットプレイスの項目にも version が無い、タグがすでにある、作業ツリーが汚れている、です。リリースにタグを付ける時期はプラグインを作って配るにあります。

plugin test#

Mod（モッド、mod）、つまりコードがイベントハンドラを登録するプラグインのテストを実行します。セッションもサインインもネットワークも要りません。テストの書き方は Mod を作る・試すにあります。

claude plugin test [directory]

[directory] は Mod のディレクトリで、既定はカレントディレクトリです。その下の、名前が .test.ts か .test.tsx で終わるファイルをすべて実行し、テストが失敗すると終了コード 1 で終わります。

./first-mod の Mod のテストを実行する例です。

claude plugin test ./first-mod

plugin validate#

プラグインのマニフェスト、マーケットプレイスのマニフェスト、ディレクトリのスキル・エージェント・コマンドを検証し、CI が扱えるコードで終了します（マニフェストでの検査内容は上の「マニフェスト」と「マーケットプレイス」）。

claude plugin validate <path> [options]
claude plugin validate ./my-plugin --strict

<path> はマニフェストのファイルかディレクトリです。ディレクトリを渡すと、そこで見つかるもので、検証する対象が決まります。

1. .claude-plugin/marketplace.json があればそれ
2. 無ければ .claude-plugin/plugin.json
3. 無ければ、ディレクトリの名前で選ばれるコンポーネントのファイル（マニフェストなしのコンポーネントファイルの検証は v2.1.233 以降）：skills・agents・commands という名前のディレクトリは中のファイル、.claude という名前のディレクトリはその中の skills・agents・commands、それ以外のディレクトリはその下の .claude にある3つのディレクトリ

ディレクトリが .claude-plugin/marketplace.json と .claude-plugin/plugin.json の両方を持つときは、Claude Code はマーケットプレイスに加えて、プラグインのマニフェストとコンポーネントのファイルも検証します。v2.1.289 以降です。

Claude Code は、名前を渡したディレクトリの中のシンボリックリンクを辿りません。動作はリンクの場所で変わります。

• プラグインか .claude のルートの下の、リンクになった skills・agents・commands ディレクトリ：中は何も読まれなかったと警告する
• skills・agents・commands ディレクトリの中の、リンクになった項目：飛ばして、セッションが読み込むはずだった数を、ディレクトリごとに警告する
• 渡した skills・agents・commands ディレクトリ自身、またはその親の .claude がシンボリックリンク：エラーを報告し、中は何も確認しない。実際のディレクトリを渡す

検証が読まないファイルがあります。プラグインのルートの SKILL.md（プラグインのディレクトリに対する実行では確認されない）、プラグインのルートの CLAUDE.md（プラグインの実行では警告される）、マーケットプレイスの実行でのプラグインのファイル（マーケットプレイスのディレクトリからは、マーケットプレイスが別のディレクトリに載せたプラグインのスキル・エージェント・コマンド・フックのファイルや、同梱の MCP サーバーのファイルを開かない。これらのファイルのエラーを見つけるには、各プラグインのディレクトリを検証する）です。ファイル、パスつきのエラーと警告、判定の行を出し、終了コードは判定に従います。

--json では、レポートを標準出力に、次のトップレベルのフィールドを持つ1つの JSON オブジェクトとして書きます。

• success：終了コードと同じ判定
• strict：警告をエラーとして扱った実行か
• target：Claude Code が検証した、解決後のパス
• manifest：マニフェスト自体の結果。マニフェストなしの実行では null
• contents：ファイルごとの結果。それぞれ file と、errors・warnings・notes の配列を持つ

終了コード 2 のときは、標準出力には何も書かず、エラーメッセージは標準エラーに出ます。

plugin marketplace add#

GitHub リポジトリ・git の URL・ホストした marketplace.json・ローカルのパスからマーケットプレイスを追加し、設定ファイルに宣言します。追加後、Claude Code は、入れたプラグインが欠いていた依存を入れます。

claude plugin marketplace add <source> [options]
claude plugin marketplace add your-org/your-marketplace --scope project

<source> の形で、取得元の種類と、Claude Code のマーケットプレイスの取得方法が決まります。

clone の URL に .git の接尾辞が付かないホスト（AWS CodeCommit など）は、代わりに extraKnownMarketplaces の git の項目としてマーケットプレイスを追加します。Claude Code は、gitlab.com の入れ子のサブグループつきの URL（https://gitlab.com/group/subgroup/project）も clone します。

成功すると、マーケットプレイス自身のマニフェストの name を使って、Successfully added marketplace: your-marketplace (declared in project settings) と出ます。同じものを追加し直すか、取得元が不正なときは、次の結果になります。

claude.ai がホストするマーケットプレイスは、claude plugin marketplace list の From claude.ai: の節に出る名前で追加します（claude plugin marketplace add --claudeai claudeai-organization-library）。--claudeai は --scope と --sparse を拒否します。そのマーケットプレイスはアカウントのためにホストされ、設定ファイルに宣言されないので、プロジェクトの .claude/settings.json では共有できません。

plugin marketplace list#

追加したマーケットプレイスを、取得元とともに一覧にします。--json で、一覧を JSON として出します。Configured marketplaces: と、マーケットプレイスごとの Source: の行を出し、無いと No marketplaces configured と出します。--json では、マーケットプレイスごとに1つのオブジェクトの配列を出し、各フィールドは文字列です。

追加した claude.ai のマーケットプレイスにはローカルの clone が無いので、installLocation の代わりに、claude.ai の識別子の marketplaceId と organizationUuid を持ちます。記録があれば scope、そして status も持ちます。端末のセッションがプラグインを claude.ai のアカウントから同期していると、テキストの一覧は From claude.ai: の節で終わります（v2.1.273 以降）。claude.ai がアカウントについて出す、まだ追加していないマーケットプレイス（git ベースのものとホストされたもの）を並べます。--json の出力は、設定済みのマーケットプレイスだけを含み、この節は含みません。

plugin marketplace remove#

マーケットプレイスの宣言を設定から外します（別名 rm）。

claude plugin marketplace remove <name> [options]
claude plugin marketplace remove your-marketplace

<name> は、add に渡した取得元でなく、plugin marketplace list が示すマーケットプレイスの名前です。

成功すると Successfully removed marketplace: your-marketplace と出ます。コマンドがプラグインをアンインストールしたときは、Also uninstalled 2 plugins from this marketplace: のような行の下に並べます。宣言していない設定ファイルに --scope を向けると、Marketplace 'your-marketplace' is not declared in project settings. Omit --scope to remove it from all scopes. で失敗します。

plugin marketplace update#

1つか全部のマーケットプレイスを取得元から更新し、新しいプラグインと版を取得します。ブランチかタグの ref つきで追加したマーケットプレイスは、リポジトリの既定ブランチではなく、その ref の最新のコミットに更新されます。--help 以外のフラグはありません。

claude plugin marketplace update [name]

成功すると Successfully updated marketplace: your-marketplace と出ます。名前を省くと Successfully updated 2 marketplaces のように数が出ます。マーケットプレイスが1つも追加されていないと No marketplaces configured と出て 0 で終了します。

セッション内のコマンド#

/plugin#

対話セッションでは、/plugin がプラグインのパネルを開きます。各サブコマンドは、パネルをタブで開く、そこで操作を実行する、結果をその場に出す、のどれかです。/plugins と /marketplace は /plugin の別名です。対話の端末のセッションでだけ実行でき、claude -p のような非対話の実行では、/plugin が使えないと返ります。<plugin> はプラグインの name か name@marketplace です。init・update・details・prune・eval・eval init・test には、セッション内の形がありません。

/plugin enable・disable・uninstall・configure で、現在のプロジェクトに入っていないプラグインを指すと、操作せずに Plugin "<plugin>" is not installed in this project と出ます。

/reload-plugins#

実行中のセッションを再起動せずに、保留中のプラグインの変更を反映します。保留中の変更とは、セッションの開始以降に、入れた・更新した・有効にした・無効にした・ディスクで編集したプラグインです。/plugin のパネルで変更して閉じるときは、Claude Code が /reload-plugins を代わりに実行します。別の端末で動かした claude plugin コマンドのような、パネル外の変更のあとは自分で実行します。

/reload-plugins [--force]

--force は、プロンプトキャッシュが無効になるときでもリロードを適用します（ダッシュなしの force も使えます）。

Claude Code は有効なプラグインをすべてリロードし、Reloaded: N plugins · N skills · N agents · N hooks · N plugin MCP servers · N plugin LSP servers という要約を1行出します（対話端末のないセッションでは、プラグインの MCP サーバーの数は省かれます）。プラグインが失敗していれば、要約に N errors during load. Run /plugin for details. が足されます。スキルの数には、プラグインが提供するスキル（commands/ の項目と SKILL.md のスキルの両方）が数えられます。エージェントの数は、セッションに読み込まれたエージェントの数で、プラグイン由来でないものも含みます。リロードされたプラグインの依存が欠けていると、Claude Code はそれを入れて再度リロードし、要約に (+ N dependencies: <names>) resolved を足します。

リロードがプラグインの MCP サーバーか LSP ツールを足すか外すことになり、その変更がプロンプトキャッシュを無効にするときは、Claude Code はリロードを適用せず、This reload changes MCP tools (<server>) — your next message will re-read the whole conversation instead of using the cache. Run /reload-plugins --force to apply. のような行を出します。--force で適用します。/reload-plugins は、デスクトップアプリ・Agent SDK・-p の非対話モードのような、対話端末のないセッションでも動きます（v2.1.260 以降）。ただし、セッション自身に自分で打ち込んだときだけで、リモートコントロールや Slack から中継されたメッセージで届いたときは、/reload-plugins isn't available over a remote connection in this session. と返して何もリロードしません。そうしたセッションのリロードは、プラグインの MCP サーバーを接続も切断もせず、その変更は次のセッションで効きます。

1セッションだけ読み込むフラグ#

次の2つの claude のフラグは、インストールせずに、1セッションだけプラグインを読み込みます。どちらも繰り返せます。プラグインの作者が、公開前に試すために使います（プラグインを作って配る）。

どちらかのフラグが読み込んだプラグインは、セッション限りのプラグインです。claude plugin list が表示するのは、claude --plugin-dir ./my-plugin plugin list のように、同じフラグがサブコマンドの前にあるときだけです。プラグインは Session-only plugins で始まる見出しの下に <name>@inline として出て、--json はその scope を session と報告します。セッション限りのプラグインが入れたプラグインと同じ名前のとき、そのセッションではセッション限りのコピーを読み込み、入れたものは飛ばします。セッション限りのコピーを claude plugin disable <name>@inline で無効にしたとき、または管理設定がそのプラグイン名をロックしているときは、入れたコピーが代わりに読み込まれます。管理者は、管理設定の disableSideloadFlags で、2つのフラグと CLAUDE_CODE_PLUGIN_DIRS のフォルダを拒否できます（その場合、フラグが組織の管理設定で無効だと出して、1 で起動せずに終了します）。Agent SDK では plugins オプションが --plugin-dir に当たります。

読み込みの規則#

プラグインがどこから読み込まれ、どの設定ファイルが読み込みを決め、なぜ更新が何も変えなかったのかを辿るための規則です。セッションの開始時と、/reload-plugins を実行するたびに適用されます。

3つの段階#

enabledPlugins の項目は、段階を経て使えるプラグインになります。設定が宣言し、Claude Code がディスクへ取得し、動いているセッションが読み込みます。設定ファイルから想像した動作にならないときは、どの段階まで進んだかを確かめます。

プラグインは、セッションの開始時に、installed_plugins.json とキャッシュから、ネットワークを使わずに読み込まれます。セッションの開始後に、Claude Code は宣言されたマーケットプレイスを背景で確認します。

• 設定が宣言していて known_marketplaces.json に無いマーケットプレイス：clone し、プラグインを再読み込みして、まだキャッシュされていない有効なプラグインをダウンロードする
• 取得元が設定で変わった、宣言済みのマーケットプレイス：新しい取得元から再取得し、Plugins changed. Run /reload-plugins to activate. と出す

どちらの経路も取得せず、使えるキャッシュのディレクトリも無い有効なプラグインは、/plugin の「Errors」タブに Plugin "<name>" not cached at <path> と出し、claude plugin list は同じ行に — run /plugin to refresh を足します。

プラグインの出どころ（ID）#

プラグインにはすべて <name>@<origin> の形の ID があり、設定ファイルと claude plugin list --json に出ます。@ の後ろが、Claude Code がプラグインを見つけた場所です。

マーケットプレイスのプラグインでは、<name> は marketplace.json の項目の名前で、@inline と @skills-dir ではプラグインのマニフェストの name です。この表の出どころの名前は予約済みなので、inline・skills-dir・synced という名前のマーケットプレイスは作れません。マーケットプレイスのプラグインには、違うことがある2つの名前があります。

• marketplace.json の項目の名前：インストールと有効化のキー。enabledPlugins に書くもの、キャッシュのディレクトリの名前の元、claude plugin list が表示するもの
• マニフェストの name：プラグインのコンポーネントの名前空間になるもの、名前の衝突が比べるもの

リポジトリで共有するプラグイン#

リポジトリを通じてプラグインを共有するには、.claude/settings.json の enabledPlugins に並べるか、.claude/skills/ の下に置きます。Claude Code は、プロジェクトの .claude/plugins/ ディレクトリを走査しません。クラウドセッションは、リポジトリが extraKnownMarketplaces に並べたマーケットプレイスを追加しません（それにはワークスペースの信頼のダイアログが要り、クラウドセッションはそれを出さないため）。

プロジェクトスコープのスキルのディレクトリのプラグインは、セッションの主作業ディレクトリの .claude/skills/ からだけ、そのフォルダのワークスペースの信頼ダイアログを承認したあとにだけ読み込まれます。普通のスキルやコマンドのように、リポジトリのルートまで親ディレクトリを探すことはありません。サブディレクトリから起動すると、リポジトリのルートのプラグインは読み込まれません。ルートから起動するか、/cd でセッションをそこへ移します（v2.1.246 以降）。

プロジェクトスコープのプラグインは、リポジトリにチェックインされ、クローンした全員に届きます。内容が自分でなくリポジトリから来るので、.claude/settings.json のプロジェクトの許可ルールと同じ信頼の確認を通ったあとにだけ読み込まれます。親フォルダを信頼している、-p で実行している、は十分ではありません。コードを動かすコンポーネントには、さらに制限があります。

• 宣言する MCP サーバー：プロジェクトの .mcp.json と同じサーバーごとの承認を通る
• MCP バンドル（.mcpb か .dxt のファイル）として、またはプラグインのディレクトリの外のファイルから宣言した MCP サーバー：飛ばされる。インラインか、プラグインのディレクトリの中の .mcp.json で宣言する
• 背景のモニター：読み込まれない

個人スコープのプラグインには、これらの制限はありません。

claude.ai から同期されたプラグイン#

claude.ai のアカウントでオンにしたプラグイン（組織がメンバーにオンにしたものを含む）は、マーケットプレイスから入れたプラグインと並んで、Claude Code でも読み込まれます。それぞれ <name>@synced として、マーケットプレイスもインストールの記録もなしで読み込まれます。端末のセッションでは、同期されたプラグインのスキル・エージェント・フック・MCP サーバー・LSP サーバーがすべて読み込まれ、自分で入れたマーケットプレイスのプラグインと同じ信頼で扱われます（Cowork が読み込むコンポーネントは、claude.com の対応表にあります）。

• Cowork：セッションの開始時に、Claude Code がセッション自身の環境へダウンロードする
• 端末のセッション：Claude Code を起動するたびに、背景で1回同期し、新しいものと更新されたものをダウンロードし、自分や組織がオフにしたものを外す。端末での同期は v2.1.273 以降

端末の同期は背景で動くので、セッションの開始後に終わることがあります。対話のセッションで同期が同期されたプラグインを追加・更新・削除すると、Plugins changed. Run /reload-plugins to activate. と出ます。/reload-plugins でそのセッションに反映するか、次の起動まで待ちます。セッションの実行中に claude.ai でプラグインを有効にしたときは、次に Claude Code を起動するときにダウンロードされます。端末で同期されるのは、claude.ai のアカウントでサインインしたセッションだけです。次の端末のセッションでは、/login でサインインしても、同期されたプラグインはダウンロードも読み込みもされません。

• ANTHROPIC_AUTH_TOKEN・CLAUDE_CODE_OAUTH_TOKEN・apiKeyHelper のスクリプトが、そのサインインの代わりに資格情報を与えるセッション
• CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC を設定したセッションのように、Anthropic から機能フラグを取得しないセッション
• bare モード、または --safe-mode で始めたセッション
• user を除いた --setting-sources のリストで始めたセッション

以前の版の Claude Code でサインインした場合、そのサインインは、Claude Code が背景で更新するまで、プラグインを覆いません。早く使うには、/login をもう一度実行します（同期は、次に Claude Code を起動したときに始まる）。同期されたプラグインは、1つずつオフにできます（組織が必須にしたものを除く）。マシンの全同期プラグインをオフにすることもできます。

• 1つ：シェルの claude plugin disable <name>@synced と、セッションの /plugin の「Installed」タブが、どちらもユーザーレベルの enabledPlugins に "<name>@synced": false を保存する。すべての環境でプロジェクトから外すには、プロジェクトのコミットされた .claude/settings.json に同じキーを設定する
• マシンのすべて：ユーザー設定で syncClaudeAiPlugins を false にする（組織が管理設定で設定してもよい）。Claude Code はダウンロードを止め、次の起動時に、すでに同期したプラグインを ~/.claude/plugins/.trash/ へ移して、読み込まなくなる。組織が claude.ai でスキルをオフにしたときも、プラグインは同期されなくなる
• 組織が必須にしたプラグイン：claude.ai で組織が必須にしたプラグインは、前に無効にしていても読み込まれる。claude plugin disable は Plugin "<name>@synced" is required by your organization and can't be disabled here. Contact your admin to change it. で拒否し、claude plugin list はそれに required by your org と付ける

どこで有効になっているか#

enabledPlugins の項目は、6つの出どころのどれにでも設定できます。次の表は、優先度が低いものから高いものの順に、各出どころが誰に適用されるかを示します。

これらの出どころは、キーごとにマージされます。各プラグイン ID で、適用される値は、その ID に言及する最も優先度の高い出どころの値です。ID に言及しない出どころは、優先度の低い出どころの値をそのままにします。

• ユーザー設定で無効にしたのに読み込まれる：~/.claude/settings.json で false にしたプラグインが読み込まれるなら、優先度の高い出どころの true が上書きしている。claude plugin list と /plugin の行に Disabled in ~/.claude/settings.json but still loads — project settings enable it, which overrides your user setting と出る。メッセージが、上書きした出どころを名指しする（project、.claude/settings.local.json の project, gitignored、cli flag、managed）。自分のマシンでプロジェクトが有効にしたプラグインから外れるには、プロジェクトのファイルより優先度が高い .claude/settings.local.json で、その ID を false にする
• プロジェクトの設定で有効だが入っていない：プラグインの唯一の true がプロジェクトの .claude/settings.json にあるとき、そのマーケットプレイスの項目が相対パスの取得元を持つか、種のディレクトリがすでに持っていない限り、Claude Code は、入っていないマシンに取得しない。代わりに、/plugin の「Errors」タブに Plugin "<name>" is enabled in project settings but isn't installed here と出る。相対パスのプラグインは、マーケットプレイス自体から読み込まれるので、インストールの記録が要らない。Claude Code が外部の取得元のプラグインを取得するのは、次のどれかが true に設定するときだけ：自分のユーザー設定、git が追跡しない .claude/settings.local.json、--settings フラグ、管理設定

ディスク上の場所#

Claude Code は、プラグインのファイルと状態の記録を、1つのプラグインのルート（CLAUDE_CODE_PLUGIN_CACHE_DIR を設定しない限り ~/.claude/plugins）の下に置きます。表のパスはすべてそのルートからの相対です。

${CLAUDE_PLUGIN_ROOT} は版のディレクトリを指すので、プラグインのルートのパスは版ごとに変わります。長持ちするファイルは、代わりに ${CLAUDE_PLUGIN_DATA} に置きます。

その場で読み込むものとコピーするもの#

Claude Code は、出どころに応じて、一部のプラグインを置き場所からその場で読み込み、残りをキャッシュにコピーします。

• --plugin-dir とスキルのディレクトリのプラグイン：ディレクトリをその場で読み込み、コピーしない。--plugin-url のアーカイブや --plugin-dir の .zip は、先にセッションの一時ディレクトリへ展開される
• ローカルのパスから追加したマーケットプレイスの、相対パスのプラグイン：マーケットプレイスのフォルダ内のパスからその場で読み込む。ソースのディレクトリの編集は、次のセッション開始か /reload-plugins で反映され、版を上げる必要はない。プラグインのフックのプロセスと MCP・LSP サーバーは、ソースのディレクトリを指す CLAUDE_PLUGIN_ROOT を受け取る
• link モードの command の取得元のプラグイン：コマンドが出力したディレクトリを、キャッシュの項目のリンク経由でその場で読み込む
• それ以外のマーケットプレイスのプラグイン：インストール時にプラグインを cache/<marketplace>/<plugin>/<version>/ へコピーし、そのコピーを読み込む。プラグインのディレクトリの外のファイルはコピーされないので、コピーされたプラグインの中のスクリプトが ../shared のようなプラグインのルートの上のパスを読むと、見つからない

どれもプラグインのディレクトリの外にコンポーネントを宣言させません。plugin.json かマーケットプレイスの項目のどちらで宣言されたパスでも、プラグインのルートの外に解決されるものを拒否します。

• 書いたとおりにプラグインの外を指すパス：../shared-utils など
• プラグインの外へ向かうシンボリックリンク：同じマーケットプレイスのプラグイン間のリンクを除く
• macOS と Linux で、パスのどこかにバックスラッシュを含むもの：パスがプラグインの内側にとどまっていても。そのため、バックスラッシュのパスで宣言したコンポーネントは Windows でだけ読み込まれる。./commands/deploy.md のように、スラッシュで書く

拒否されたパスは path escapes plugin directory のエラーになり、プラグインはそのコンポーネントなしで読み込まれます。

プラグインを更新するかアンインストールすると、Claude Code は前の版のディレクトリに .orphaned_at の印を書き、14日後の背景の掃除で消します（すでに古い版を読み込んだセッションは動き続けられる）。掃除は、installed_plugins.json が少なくとも1つのインストールを記録しているあいだだけ動きます。最後のプラグインをアンインストールしたあと、孤立したディレクトリは、次に何か入れるまで残ります。

Node.js のパッケージ依存#

Claude Code は、プラグインをキャッシュへコピーするとき、プラグインの Node.js のパッケージ依存もそこへ入れるので、プラグインのフックと MCP サーバーがそれを読み込めます。これは、プラグイン自身の package.json が宣言する npm と Bun のパッケージのことで、他のプラグインへの依存の版はプラグインを作って配るにあります。Claude Code は、版のディレクトリを作るたびに、そのコピー先へ依存をインストールします。

• プラグインを入れるとき
• Claude Code がプラグインを新しい版に更新するとき
• 新しいマシンのように、有効なプラグインがまだキャッシュされていないセッションの開始時

ローカルのパスから追加したマーケットプレイスからその場で読み込む相対パスのプラグインでは、ソースのディレクトリへの依存のインストールは行われません。自分でそこに入れるか、フックで ${CLAUDE_PLUGIN_DATA} に入れます。インストールは、プラグインのルートのディレクトリが package.json と対応するロックファイルの両方を持つときだけ動きます。

ロックファイルが、Claude Code が動かすパッケージマネージャーを決めます。

プラグインが複数のロックファイルを含むときは、bun.lock・npm-shrinkwrap.json・package-lock.json の順に確認して、最初に合ったものを使います。

次のロックファイルでは、インストールを飛ばします。

• bun.lockb：Bun のバイナリのロックファイルは検査できない。テキストの bun.lock か npm のロックファイルを同梱する
• yarn.lock か pnpm-lock.yaml：npm のロックファイルに置き換える
• Claude Code が読めない形式のロックファイル：npm のロックファイルは lockfileVersion が 2 か 3（npm 7 以降が書く）、bun.lock は lockfileVersion が 2 以下であること

最も多くのユーザーに届けるには、npm のロックファイルを含めます。Claude Code は合ったロックファイルのパッケージマネージャーをユーザーの PATH から動かし、それが無くても他のロックファイルを試しません。npm の取得元で配るプラグインには、npm-shrinkwrap.json を使います（npm が package-lock.json を公開パッケージから除くため）。

このインストールは、プラグインやそのパッケージのコードが動かないように制約され、時間も制限されます。

• レジストリのパッケージだけ：すべての依存が、ロックファイルで正確な版に固定されたレジストリのパッケージであること。git・GitHub・フォルダ・ワークスペース・リンクの依存を持つプラグインは、インストールされない
• https のダウンロード：ロックファイルのダウンロードのリンクは、インストールするユーザー自身の既定の npm レジストリを指すときを除き、https であること
• 別のインストール用フォルダ：パッケージマネージャーは、検査済みの依存の一覧のコピーだけを置いた専用のフォルダで動く。そのため npm と Bun は、プラグインの .npmrc・.env・bunfig.toml を読まない。インストールが成功すると、できた node_modules をプラグインへ移す
• 固定した解決：ロックファイルが固定した版をそのままインストールし、package.json とロックファイルが同じ依存を並べていなければ飛ばす
• ライフサイクルスクリプトなし：--ignore-scripts で、preinstall・install・postinstall を動かさないので、それらのスクリプトでネイティブモジュールをビルドする依存は、ダウンロードされてもコンパイルされない
• 上書きとパッチなし：package.json に npm の overrides があるプラグインは npm のロックファイルからインストールされず、Bun の patchedDependencies があるプラグインは bun.lock からインストールされない
• 60秒のタイムアウト：それより長いインストールは止めて失敗として扱う

自動のインストールは止められません。無効にする設定や環境変数はありません。制限されたネットワークでは、許可するホストはネットワークの文書にあります（ネットワークと LLM ゲートウェイ）。

インストールが失敗するか飛ばされても、プラグインは読み込まれますが、足りないパッケージを要る部分は動かないことがあります。

/plugin と claude plugin list は、有効なプラグインのキャッシュのコピーにロックファイルと実行時の依存を挙げた package.json があるのに node_modules が無いとき、注記を出します。注記は、インストールが終わらなかったのか、このプラグインでは実行できないのかを示します。それぞれの対処は、トラブルシューティングの「The packages it lists are not installed」にあります。

自動のインストールが依存を与えられないとき（ライフサイクルスクリプトでのビルドが要るパッケージ、Python の依存、Yarn や pnpm でロックしたプラグイン、git の依存のようなレジストリのパッケージでない依存）は、フックから永続データのディレクトリへインストールします。

版と更新#

プラグインの作者が新しいコミットを押したのに、claude plugin update が <name> is already at the latest version (<version>). と出すときは、Claude Code が計算するプラグインの版が変わっていないので、プラグインのディスク上のファイルは変わりません。Claude Code は、入れるすべてのプラグインの版を計算し、その版が更新の検出の仕組みです。claude plugin update と背景の自動更新は、版をもう一度計算し、installed_plugins.json が記録するものと一致すれば、キャッシュのコピーを置き換えません。自分で始めた更新は、そのコピーの終わっていない依存のインストールを再試行することがあります。版は、プラグインのキャッシュのディレクトリの名前にもなります。ローカルのパスから追加したマーケットプレイスからその場で読み込むプラグインは、版の文字列にかかわらず、セッションの開始のたびに現在のソースのファイルを読み込みます。claude.ai がホストするマーケットプレイスのプラグインは、claude.ai が記録する版がその版で、マニフェストの version は読まれません。

版は、マーケットプレイスの項目の取得元の種類で規則が決まり、command を除くすべての取得元で、次の順に決まります。

1. プラグインのマニフェストの version フィールド
2. 次に、マーケットプレイスの項目の version フィールド
3. どちらも無いとき、取得元の種類から決まる

Claude Code は、~/.claude を git で管理しているときのような、インストール先のパスを囲むリポジトリからは版を取りません。command の取得元では、常にコマンドが出力したものから版を導き（ハッシュ12文字だけ、マニフェストが版を設定していれば <manifest version>-<hash>）、マーケットプレイスの項目の version は無視されます。マニフェストが優先なので、"version": "1.0.0" を固定したマニフェストは、作者が文字列を変えるまで、コミットをいくつ押しても、全ユーザーをキャッシュしたコピーのままにします。コミットを追わせるには、マニフェストと項目の両方から version を外します。

プラグインを入れるとき、Claude Code はマーケットプレイスのカタログのローカルのコピーで調べます。

name@marketplace のインストールの前の更新は、マーケットプレイスの自動更新の設定や DISABLE_AUTOUPDATER に依存しません。更新が失敗すると、インストールはキャッシュしたカタログから進み、claude plugin install は marketplace not refreshed と報告します。次のときは、name@marketplace のインストールの前の更新を飛ばします。

• マーケットプレイスをローカルの file か directory の取得元から追加した、または settings の取得元で設定にインラインで定義している
• 種のディレクトリがマーケットプレイスを提供している
• 直前30秒以内に更新した
• CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC を設定した
• 管理設定がマーケットプレイスをブロックしている（その場合、Claude Code はインストールも拒否する）

自動更新は、対話セッションで、最初のメッセージを送ってから、最大10分のランダムな待ちのあと、自動更新がオンのすべてのマーケットプレイスを更新し、そこから入れたプラグインのディスク上のコピーを更新します。動いているセッションは読み込んだ版のままで、Plugin updated: <name> · Run /reload-plugins to apply と出ます。リロードするかにかかわらず、新しい版は次の起動で読み込まれます。マーケットプレイスが自動更新するかは、次のうち最初に設定されているものに従います。

1. 設定ファイルの extraKnownMarketplaces の項目の autoUpdate
2. known_marketplaces.json の項目の autoUpdate（/plugin の「Marketplaces」の「Enable auto-update」の切り替えが書く。設定ファイルも extraKnownMarketplaces でそのマーケットプレイスを宣言しているときは、切り替えが、その設定の項目にも autoUpdate を書く）
3. 既定：claude-plugins-official のような Anthropic の公式のマーケットプレイスはオン、knowledge-work-plugins と first-party-plugins はオフ、claude.ai から追加したマーケットプレイスはオン、それ以外はすべてオフ

DISABLE_UPDATES=1・DISABLE_AUTOUPDATER=1・CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 を設定すると、更新の処理全体がオフになり、「Enable auto-update」の切り替えが隠れます（FORCE_AUTOUPDATE_PLUGINS=1 も設定しない限り）。自動更新は、マーケットプレイスの項目が headersHelper を宣言するプラグインも飛ばします。コピーしたプラグインがセッション中に更新されると、フックのコマンド・モニター・MCP サーバー・LSP サーバーは、前の版のパスを使い続けます。/reload-plugins を実行すると、フック・MCP サーバー・LSP サーバーが新しいパスに切り替わります。モニターはセッションの再起動が要ります。

command の取得元のプラグインは、自動更新の処理を待ちません。出力されたディレクトリは、コマンドを動かした時点のツールの状態を映すので、Claude Code は承認されたコマンドを、次のときにもう一度動かします。

• プラグインを入れる・更新するたびに
• 有効な command の取得元の各プラグインにつき、セッションごとに1回、セッションの開始の少しあとに背景で（マーケットプレイスの自動更新の設定や DISABLE_AUTOUPDATER に依存しない）
• 有効なプラグインの入れた版がプラグインのキャッシュに無いとき、起動時か /reload-plugins で

CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC を設定すると、2つの背景の実行を飛ばします（明示的なインストールと更新は、その変数があってもコマンドを動かします）。コマンドのハッシュした出力が変わっていると、Claude Code は結果を新しい版として入れ、動いている対話セッションで再読み込みして、/reload-plugins が切り替えるのと同じコンポーネントを切り替えます。通知が出ます。その場で再読み込みするとセッションのプロンプトキャッシュが無効になるときは、代わりに /reload-plugins を実行するよう促し、キャッシュの費用を警告して、--force で再実行すると適用します。

名前の衝突#

別々の出どころの有効なプラグインがマニフェストの名前を共有するとき、次の順（優先度の高いものから）で、どれが読み込まれるかが決まります。

1. 管理設定の enabledPlugins に、true か false で ID が現れるプラグイン。名前の部分が ID と一致するマニフェストの名前を持つ --plugin-dir のコピーは読み込まれず、--plugin-dir copy of "<name>" ignored: plugin is locked by managed settings と出る
2. 有効な --plugin-dir・--plugin-url・CLAUDE_CODE_PLUGIN_DIRS のプラグイン。同名の、入れたマーケットプレイスのプラグインやスキルのディレクトリのプラグインを置き換える。入れたマーケットプレイスのプラグインは、黙って置き換えられ、claude plugin list はマーケットプレイスの行を（設定を映すので）有効のまま示し、--debug で起動したときに ~/.claude/debug/ の下へ書かれるログだけが Plugin "<name>" from --plugin-dir overrides installed version を記録する。スキルのディレクトリのプラグインは、/plugin の「Errors」タブに Not loaded — the name "<name>" is already taken by a session-only plugin (--plugin-dir / --plugin-url), which takes precedence の行が出て置き換えられる
3. 入れたマーケットプレイスのプラグイン。同名のスキルのディレクトリのプラグインは、入れたプラグインを名指しする同じ Not loaded の行になる
4. スキルのディレクトリのプラグイン。2つのあいだでは、~/.claude/skills/ のコピーが読み込まれ、プロジェクトの .claude/skills/ のコピーは、どのパスが覆ったかを示す行とともに落とされる
5. claude.ai から同期されたプラグイン。他の出どころの有効なプラグインが名前に合うと、Claude Code はそちらを読み込み、同期されたコピーを読み込まれなかったものとして報告する。claude.ai のコピーを使うには、自分のコピーを無効にする

順序がマニフェストの名前を比べるので、マニフェストが "name": "hello-plugin" でもある hello@example-marketplace を、hello-plugin という名前の --plugin-dir のプラグインが置き換えます。--plugin-dir のプラグインが何も覆わないようにするため、または親のプロセスがフラグを渡すときにオフにするには、どの設定ファイルでも、その ID を false にします。マニフェストの名前が hello-plugin のプラグインなら、"enabledPlugins": {"hello-plugin@inline": false} です。無効なセッション限りのプラグインは何も覆わないので、代わりにマーケットプレイスかスキルのディレクトリのコピーが読み込まれます。

エラーとトラブルシューティング#

メッセージは、それを出す段階ごとに、実行したコマンドとは限らない見出しの下に載せています。たとえば、マーケットプレイスが無いためにインストールが失敗することがあるので、そのメッセージは「マーケットプレイスの追加」の節にあります。メッセージが名指しするプラグインやマーケットプレイスは、<name> のようなプレースホルダーで示します。その他のエラーの一覧はエラー一覧、一般的な切り分けはトラブルシューティングにあります。

/plugin が動く場所#

/plugin は、動いている Claude Code の端末セッションの中で打つコマンドで、対話のパネルを開きます。

存在しない綴りと、使うべきコマンドは次のとおりです。

間違って見えて動く綴りもあります。claude plugins は claude plugin の別名、claude plugin remove は claude plugin uninstall の別名、セッションの /plugins と /marketplace は /plugin と同じパネルを開きます。

マーケットプレイスの追加#

プラグインのインストール#

依存のエラー#

依存を宣言するプラグインは、依存を満たせないとき、インストールに失敗するか、入っても無効のままになります。メッセージはインストール時（インストールのエラーメッセージとして）か読み込み時（claude plugin list と「Errors」タブに出て、解決するまで影響を受けたプラグインを無効のままにする）に届きます。

プログラムで見るには、シェルで claude plugin list --json を実行します。問題のあるプラグインは、メッセージの errors フィールドと、各メッセージの type を持つ errorDetails フィールドを持ちます。最初の2行は dependency-unsatisfied、3行目は dependency-version-unsatisfied です。

プラグインを入れたのに動かない#

インストールは成功したのに、プラグインのスキル・フック・サーバーが動かないときです。

フックとサーバー#

プラグインの開発#

claude plugin validate（セッションでは /plugin validate <path>）のメッセージは次のとおりです。検証を止めるメッセージと、--strict を渡したときだけ止める2つの警告（No frontmatter block found と Unknown field '<key>'）を載せています。説明の欠けのような他の警告は載せていません。検証器は、プラグインのディレクトリなら .claude-plugin/plugin.json、マーケットプレイスのディレクトリなら .claude-plugin/marketplace.json のマニフェストを読み、マーケットプレイスでは、項目自身のマニフェストの問題の前に項目のインデックスを付けます（plugins[1] plugin.json → json: ...）。

マーケットプレイスのファイル自体の検証メッセージは次のとおりです。claude plugin validate は、source がローカルのパスの各項目も検証し、項目の version がプラグイン自身のマニフェストと食い違うと警告します。項目の階層のメッセージは、上のプラグインのメッセージに plugins[N] plugin.json → が付いたものです。

v2.1.247 より前は、制御文字や双方向の書式文字を含むマーケットプレイスの名前は、Marketplace name impersonates an official Anthropic/Claude marketplace としてだけ報告されました。

マーケットプレイスの運営#

組織のポリシーによる拒否#

組織が管理設定でプラグインを制限していて、コマンドがポリシーのメッセージで拒否されたときの索引です。メッセージごとに、背後の設定が分かるので、管理者に何を頼むかが分かります（管理者側はプラグインを作って配る）。