プラグインマーケットプレイスの作成と配布

Claude Code 拡張機能を配布するためのプラグインマーケットプレイスを構築およびホストします。

プラグインマーケットプレイスは、他のユーザーにプラグインを配布できるカタログです。マーケットプレイスは、一元化された検出、バージョン追跡、自動更新、および複数のソースタイプ（Git リポジトリ、ローカルパスなど）のサポートを提供します。このガイドでは、チームやコミュニティとプラグインを共有するための独自のマーケットプレイスを作成する方法を説明します。

既存のマーケットプレイスからプラグインをインストールしたいですか？既成プラグインの検出とインストールを参照してください。

概要

マーケットプレイスの作成と配布には、以下が含まれます。

1. プラグインの作成：skills、agents、hooks、MCP サーバー、または LSP サーバーを使用して 1 つ以上のプラグインを構築します。このガイドでは、配布するプラグインが既にあることを前提としています。プラグインの作成方法の詳細については、プラグインの作成を参照してください。
2. マーケットプレイスファイルの作成：プラグインとその場所を一覧表示する marketplace.json を定義します。マーケットプレイスファイルの作成を参照してください。
3. マーケットプレイスのホスト：GitHub、GitLab、または別の Git ホストにプッシュします。マーケットプレイスのホストと配布を参照してください。
4. ユーザーと共有：ユーザーが /plugin marketplace add でマーケットプレイスを追加し、個別のプラグインをインストールします。プラグインの検出とインストールを参照してください。

マーケットプレイスがライブになったら、リポジトリに変更をプッシュして更新できます。ユーザーは /plugin marketplace update でローカルコピーを更新します。

チュートリアル：ローカルマーケットプレイスの作成

この例では、1 つのプラグイン（コードレビュー用の quality-review skill）を含むマーケットプレイスを作成します。ディレクトリ構造を作成し、skill を追加し、プラグインマニフェストとマーケットプレイスカタログを作成してから、インストールしてテストします。

mkdir -p my-marketplace/.claude-plugin
mkdir -p my-marketplace/plugins/quality-review-plugin/.claude-plugin
mkdir -p my-marketplace/plugins/quality-review-plugin/skills/quality-review

---
description: Review code for bugs, security, and performance
---

Review the code I've selected or the recent changes for:
- Potential bugs or edge cases
- Security concerns
- Performance issues
- Readability improvements

Be concise and actionable.

{
"name": "quality-review-plugin",
"description": "Adds a quality-review skill for quick code reviews",
"version": "1.0.0"
}

{
"name": "my-plugins",
"owner": {
"name": "Your Name"
},
"plugins": [
{
"name": "quality-review-plugin",
"source": "./plugins/quality-review-plugin",
"description": "Adds a quality-review skill for quick code reviews"
}
]
}

/plugin marketplace add ./my-marketplace
/plugin install quality-review-plugin@my-plugins

/quality-review-plugin:quality-review

プラグインが実行できることの詳細（hooks、agents、MCP サーバー、LSP サーバーを含む）については、プラグインを参照してください。

マーケットプレイスファイルの作成

リポジトリルートに .claude-plugin/marketplace.json を作成します。このファイルは、マーケットプレイスの名前、所有者情報、およびソースを含むプラグインのリストを定義します。

各プラグインエントリには、最低限 name と source（Claude Code がどこから取得するかを指定）が必要です。利用可能なすべてのフィールドについては、以下の完全なスキーマを参照してください。

{
  "name": "company-tools",
  "owner": {
    "name": "DevTools Team",
    "email": "devtools@example.com"
  },
  "plugins": [
    {
      "name": "code-formatter",
      "source": "./plugins/formatter",
      "description": "Automatic code formatting on save",
      "version": "2.1.0",
      "author": {
        "name": "DevTools Team"
      }
    },
    {
      "name": "deployment-tools",
      "source": {
        "source": "github",
        "repo": "company/deploy-plugin"
      },
      "description": "Deployment automation tools"
    }
  ]
}

マーケットプレイススキーマ

必須フィールド

所有者フィールド

オプションフィールド

description と version は後方互換性のため metadata の下でも受け入れられます。

プラグインエントリ

plugins 配列内の各プラグインエントリは、プラグインとその場所を説明します。プラグインマニフェストスキーマのフィールド（description、version、author、commands、hooks など）を含めることができます。さらに、これらのマーケットプレイス固有のフィールド：source、category、tags、strict、および relevance があります。

必須フィールド

オプションプラグインフィールド

標準メタデータフィールド：

コンポーネント設定フィールド：

プラグインソース

プラグインソースは、マーケットプレイスに一覧表示されている各個別プラグインを取得する場所を Claude Code に指示します。これらは marketplace.json 内の各プラグインエントリの source フィールドで設定されます。

Claude Code がプラグインをローカルマシンにクローンまたはダウンロードした後、プラグインは ~/.claude/plugins/cache のローカルバージョン管理プラグインキャッシュにコピーされます。

以下の Git ベースのソースタイプは github、url、および git-subdir です。ref と sha の両方がそれらのいずれかに設定されている場合、sha が有効なピンです。Claude Code はピンされたコミットを直接取得してチェックアウトします。

GitHub、GitLab、Bitbucket を含むほとんどの Git ホストでは、ブランチまたは ref で指定されたタグが上流で削除されていても、コミットがリポジトリから到達可能である限り、インストールは成功します。AWS CodeCommit などの一部のサーバーは、SHA によるコミットの取得をサポートしていません。これらのサーバーでは、ref が存在し、ピンされたコミットがそこから到達可能である必要があります。

相対パス

同じリポジトリ内のプラグインの場合、./ で始まるパスを使用します。

{
  "name": "my-plugin",
  "source": "./plugins/my-plugin"
}

パスはマーケットプレイスルート（.claude-plugin/ を含むディレクトリ）に相対的に解決されます。上記の例では、./plugins/my-plugin は <repo>/plugins/my-plugin を指します。marketplace.json は <repo>/.claude-plugin/marketplace.json に存在していても同じです。../ を使用してマーケットプレイスルートの外を参照しないでください。

GitHub リポジトリ

{
  "name": "github-plugin",
  "source": {
    "source": "github",
    "repo": "owner/plugin-repo"
  }
}

特定のブランチ、タグ、またはコミットに固定できます。

{
  "name": "github-plugin",
  "source": {
    "source": "github",
    "repo": "owner/plugin-repo",
    "ref": "v2.0.0",
    "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
  }
}

Git リポジトリ

{
  "name": "git-plugin",
  "source": {
    "source": "url",
    "url": "https://gitlab.com/team/plugin.git"
  }
}

特定のブランチ、タグ、またはコミットに固定できます。

{
  "name": "git-plugin",
  "source": {
    "source": "url",
    "url": "https://gitlab.com/team/plugin.git",
    "ref": "main",
    "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
  }
}

Git サブディレクトリ

git-subdir を使用して、Git リポジトリのサブディレクトリ内に存在するプラグインを指します。Claude Code はスパースな部分クローンを使用してサブディレクトリのみを取得し、大規模なモノレポの帯域幅を最小化します。

{
  "name": "my-plugin",
  "source": {
    "source": "git-subdir",
    "url": "https://github.com/acme-corp/monorepo.git",
    "path": "tools/claude-plugin"
  }
}

特定のブランチ、タグ、またはコミットに固定できます。

{
  "name": "my-plugin",
  "source": {
    "source": "git-subdir",
    "url": "https://github.com/acme-corp/monorepo.git",
    "path": "tools/claude-plugin",
    "ref": "v2.0.0",
    "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
  }
}

url フィールドは、GitHub ショートハンド（owner/repo）または SSH URL（git@github.com:owner/repo.git）も受け入れます。

npm パッケージ

npm パッケージとして配布されるプラグインは、npm install を使用してインストールされます。これは、公開 npm レジストリまたはチームがホストするプライベートレジストリ上の任意のパッケージで機能します。

{
  "name": "my-npm-plugin",
  "source": {
    "source": "npm",
    "package": "@acme/claude-plugin"
  }
}

特定のバージョンに固定するには、version フィールドを追加します。

{
  "name": "my-npm-plugin",
  "source": {
    "source": "npm",
    "package": "@acme/claude-plugin",
    "version": "2.1.0"
  }
}

プライベートまたは内部レジストリからインストールするには、registry フィールドを追加します。

{
  "name": "my-npm-plugin",
  "source": {
    "source": "npm",
    "package": "@acme/claude-plugin",
    "version": "^2.0.0",
    "registry": "https://npm.example.com"
  }
}

高度なプラグインエントリ

この例は、commands、agents、hooks、MCP サーバーのカスタムパスを含む、多くのオプションフィールドを使用するプラグインエントリを示しています。

{
  "name": "enterprise-tools",
  "source": {
    "source": "github",
    "repo": "company/enterprise-plugin"
  },
  "description": "Enterprise workflow automation tools",
  "version": "2.1.0",
  "author": {
    "name": "Enterprise Team",
    "email": "enterprise@example.com"
  },
  "homepage": "https://docs.example.com/plugins/enterprise-tools",
  "repository": "https://github.com/company/enterprise-plugin",
  "license": "MIT",
  "keywords": ["enterprise", "workflow", "automation"],
  "category": "productivity",
  "commands": [
    "./commands/core/",
    "./commands/enterprise/",
    "./commands/experimental/preview.md"
  ],
  "agents": ["./agents/security-reviewer.md", "./agents/compliance-checker.md"],
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh"
          }
        ]
      }
    ]
  },
  "mcpServers": {
    "enterprise-db": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"]
    }
  },
  "strict": false
}

注目すべき重要な点：

• commands と agents：複数のディレクトリまたは個別のファイルを指定できます。パスはプラグインルートに相対的です。
• ${CLAUDE_PLUGIN_ROOT}：hooks と MCP サーバー設定でこの変数を使用して、プラグインのインストールディレクトリ内のファイルを参照します。プラグインはインストール時にキャッシュロケーションにコピーされるため、これは必要です。永続的なデータまたはプラグイン更新後も保持する必要がある状態については、代わりに ${CLAUDE_PLUGIN_DATA} を使用します。
• strict: false：これが false に設定されているため、プラグインは独自の plugin.json を必要としません。マーケットプレイスエントリがすべてを定義します。以下の厳密モードを参照してください。

デフォルトでは、プラグインの skills は、その source の下の skills/ ディレクトリから読み込まれます。skills フィールドに一覧表示されているパスはそのスキャンに追加されます。

"skills": ["./skills/", "./extra-skills/"]

複数のプラグインエントリがマーケットプレイスルート（source: "./" ）で 1 つの skills/ フォルダを共有する場合、各エントリが独自の skills のみを読み込むように、特定のサブディレクトリを代わりに一覧表示します。

"source": "./",
"skills": ["./skills/code-review", "./skills/docs"]

マーケットプレイスルート source を使用する場合、一覧表示されたパスはそのエントリの完全なセットであり、共有 skills/ フォルダ内の他のディレクトリは読み込まれません。./skills/ 自体またはプラグインルートを一覧表示すると、完全なスキャンが保持されます。一覧表示されたパスが存在しない場合、デフォルトスキャンが代わりに実行されます。

厳密モード

strict フィールドは、plugin.json がコンポーネント定義（skills、agents、hooks、MCP サーバー、出力スタイル）の権限であるかどうかを制御します。

各モードを使用する場合：

• strict: true：プラグインは独自の plugin.json を持ち、独自のコンポーネントを管理します。マーケットプレイスエントリは上に追加の skills または hooks を追加できます。これはデフォルトで、ほとんどのプラグインで機能します。
• strict: false：マーケットプレイスオペレーターが完全に制御したい場合。プラグインリポジトリは生ファイルを提供し、マーケットプレイスエントリはそれらのファイルのどれが skills、agents、hooks などとして公開されるかを定義します。マーケットプレイスがプラグイン作成者の意図と異なる方法でプラグインのコンポーネントを再構成またはキュレートする場合に便利です。

マーケットプレイスのホストと配布

GitHub でホスト（推奨）

GitHub はマーケットプレイスをホストして配布するための推奨される方法です。

1. リポジトリを作成：マーケットプレイス用の新しいリポジトリを設定します
2. マーケットプレイスファイルを追加：プラグイン定義を含む .claude-plugin/marketplace.json を作成します
3. チームと共有：ユーザーが /plugin marketplace add owner/repo でマーケットプレイスを追加します

メリット：組み込みバージョン管理、問題追跡、チームコラボレーション機能。

他の Git サービスでホスト

GitLab、Bitbucket、自己ホスト型サーバーなど、任意の Git ホスティングサービスが機能します。ユーザーは完全なリポジトリ URL で追加します。

/plugin marketplace add https://gitlab.com/company/plugins.git

プライベートリポジトリ

Claude Code はプライベートリポジトリからプラグインをインストールすることをサポートしています。手動インストールと更新の場合、Claude Code は既存の Git 認証情報ヘルパーを使用するため、HTTPS アクセスは gh auth login、macOS キーチェーン、または git-credential-store 経由で機能し、ターミナルと同じように動作します。SSH アクセスは、ホストが既に known_hosts ファイルにあり、キーが ssh-agent に読み込まれている限り機能します。Claude Code はホストフィンガープリントとキーパスフレーズの対話的な SSH プロンプトを抑制するためです。

バックグラウンド自動更新は、認証情報ヘルパーなしで起動時に実行されます。これは、対話的なプロンプトが Claude Code の起動をブロックするためです。プライベートマーケットプレイスの自動更新を有効にするには、環境に適切な認証トークンを設定します。

シェル設定（例：.bashrc、.zshrc）でトークンを設定するか、Claude Code を実行するときに渡します。

export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx

配布前にローカルでテスト

共有する前にマーケットプレイスをローカルでテストします。

/plugin marketplace add ./my-marketplace
/plugin install quality-review-plugin@my-plugins

add コマンドの完全な範囲（GitHub、Git URL、ローカルパス、リモート URL）については、マーケットプレイスの追加を参照してください。

チーム向けマーケットプレイスの要求

リポジトリを設定して、チームメンバーがプロジェクトフォルダを信頼するときにマーケットプレイスをインストールするよう自動的に促されるようにできます。マーケットプレイスを .claude/settings.json に追加します。

{
  "extraKnownMarketplaces": {
    "company-tools": {
      "source": {
        "source": "github",
        "repo": "your-org/claude-plugins"
      }
    }
  }
}

デフォルトで有効にするプラグインを指定することもできます。

{
  "enabledPlugins": {
    "code-formatter@company-tools": true,
    "deployment-tools@company-tools": true
  }
}

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

コンテナ用にプラグインを事前入力する

コンテナイメージと CI 環境の場合、ビルド時にプラグインディレクトリを事前入力して、Claude Code が実行時にクローンすることなく、マーケットプレイスとプラグインが既に利用可能な状態で起動するようにできます。CLAUDE_CODE_PLUGIN_SEED_DIR 環境変数をこのディレクトリを指すように設定します。

複数のシードディレクトリをレイヤーするには、Unix では : で、Windows では ; でパスを区切ります。Claude Code は各ディレクトリを順番に検索し、特定のマーケットプレイスまたはプラグインキャッシュを含む最初のシードが優先されます。

シードディレクトリは ~/.claude/plugins の構造をミラーリングします。

$CLAUDE_CODE_PLUGIN_SEED_DIR/
  known_marketplaces.json
  marketplaces/<name>/...
  cache/<marketplace>/<plugin>/<version>/...

シードディレクトリを構築するには、イメージビルド中に Claude Code を 1 回実行し、必要なプラグインをインストールしてから、結果の ~/.claude/plugins ディレクトリをイメージにコピーして、CLAUDE_CODE_PLUGIN_SEED_DIR をそれを指すように設定します。

コピーステップをスキップするには、ビルド中に CLAUDE_CODE_PLUGIN_CACHE_DIR をターゲットシードパスに設定して、プラグインが直接そこにインストールされるようにします。

CLAUDE_CODE_PLUGIN_CACHE_DIR=/opt/claude-seed claude plugin marketplace add your-org/plugins
CLAUDE_CODE_PLUGIN_CACHE_DIR=/opt/claude-seed claude plugin install my-tool@your-plugins

その後、コンテナのランタイム環境で CLAUDE_CODE_PLUGIN_SEED_DIR=/opt/claude-seed を設定して、Claude Code が起動時にシードから読み込むようにします。

起動時に、Claude Code はシードの known_marketplaces.json にあるマーケットプレイスをプライマリ設定に登録し、cache/ の下にあるプラグインキャッシュを再クローンせずに使用します。これは対話モードと -p フラグを使用した非対話モードの両方で機能します。

動作の詳細：

• 読み取り専用：シードディレクトリは書き込まれません。読み取り専用ファイルシステムで git pull が失敗するため、シードマーケットプレイスの自動更新は無効になります。
• シードエントリが優先：シードで宣言されたマーケットプレイスは、起動時にユーザー設定の一致するエントリを上書きします。シードプラグインをオプトアウトするには、マーケットプレイスを削除するのではなく /plugin disable を使用します。
• パス解決：Claude Code はシードの JSON に保存されているパスを信頼するのではなく、実行時に $CLAUDE_CODE_PLUGIN_SEED_DIR/marketplaces/<name>/ をプローブしてマーケットプレイスコンテンツを見つけます。これは、シードがビルド時と異なるパスにマウントされている場合でも、シードが正しく機能することを意味します。
• 変更がブロックされます：シードで管理されているマーケットプレイスに対して /plugin marketplace remove または /plugin marketplace update を実行すると、管理者にシードイメージを更新するよう指示するガイダンスで失敗します。
• 設定と構成：extraKnownMarketplaces または enabledPlugins がシードに既に存在するマーケットプレイスを宣言している場合、Claude Code はクローンする代わりにシードコピーを使用します。

管理マーケットプレイスの制限

プラグインソースを厳密に制御する必要がある組織の場合、管理者は管理設定の strictKnownMarketplaces 設定を使用して、ユーザーが追加できるプラグインマーケットプレイスを制限できます。また、単一実行のために CLI フラグをサイドロードするプラグイン、エージェント、MCP サーバーを拒否するには、disableSideloadFlags と組み合わせます。

strictKnownMarketplaces が管理設定で設定されている場合、制限動作は値によって異なります。

一般的な設定

すべてのマーケットプレイス追加を無効にする：

{
  "strictKnownMarketplaces": []
}

特定のマーケットプレイスのみを許可する：

{
  "strictKnownMarketplaces": [
    {
      "source": "github",
      "repo": "acme-corp/approved-plugins"
    },
    {
      "source": "github",
      "repo": "acme-corp/security-tools",
      "ref": "v2.0"
    },
    {
      "source": "url",
      "url": "https://plugins.example.com/marketplace.json"
    }
  ]
}

ホストの正規表現パターンマッチングを使用して、内部 Git サーバーからのすべてのマーケットプレイスを許可する。これは GitHub Enterprise Server または自己ホスト型 GitLab インスタンスの推奨アプローチです。

{
  "strictKnownMarketplaces": [
    {
      "source": "hostPattern",
      "hostPattern": "^github\\.example\\.com$"
    }
  ]
}

パスの正規表現パターンマッチングを使用して、特定のディレクトリからのファイルシステムベースのマーケットプレイスを許可する：

{
  "strictKnownMarketplaces": [
    {
      "source": "pathPattern",
      "pathPattern": "^/opt/approved/"
    }
  ]
}

pathPattern として ".*" を使用して、ネットワークソースを hostPattern で制御しながら、任意のファイルシステムパスを許可します。

制限の仕組み

制限はネットワークまたはファイルシステム操作の前にチェックされます。チェックはマーケットプレイス追加時およびプラグインのインストール、更新、リフレッシュ、自動更新時に実行されます。マーケットプレイスがポリシー設定前に追加され、そのソースがホワイトリストと一致しなくなった場合、Claude Code はそこからプラグインをインストールまたは更新することを拒否します。同じ強制が blockedMarketplaces に適用されます。

ホワイトリストはほとんどのソースタイプに対して正確なマッチングを使用します。マーケットプレイスが許可されるには、指定されたすべてのフィールドが正確に一致する必要があります。

• GitHub ソースの場合：repo は必須で、ホワイトリストで指定されている場合は ref または path も一致する必要があります
• URL ソースの場合：完全な URL が正確に一致する必要があります
• hostPattern ソースの場合：マーケットプレイスホストが正規表現パターンと照合されます
• pathPattern ソースの場合：マーケットプレイスのファイルシステムパスが正規表現パターンと照合されます

正確なマッチングは URL を正規化しません。末尾のスラッシュ、.git サフィックス、または ssh:// と https:// の形式は異なる値として扱われます。組織のマーケットプレイスが複数の URL 形式でクローンできる場合、リテラル URL よりも hostPattern エントリを優先して、すべての形式が一致するようにします。

strictKnownMarketplaces は管理設定で設定されるため、個別のユーザーとプロジェクト設定はこれらの制限をオーバーライドできません。

完全な設定詳細（サポートされているすべてのソースタイプと extraKnownMarketplaces との比較を含む）については、strictKnownMarketplaces リファレンスを参照してください。

バージョン解決とリリースチャネル

プラグインバージョンはキャッシュパスと更新検出を決定します。解決されたバージョンがユーザーが既に持っているものと一致する場合、/plugin update と自動更新はプラグインをスキップします。

Claude Code はプラグインのバージョンを以下の最初のものから解決します。

1. プラグインの plugin.json の version
2. プラグインのマーケットプレイスエントリの version
3. プラグインのソースの Git コミット SHA

Git ベースのソースタイプ github、url、git-subdir、および Git ホスト型マーケットプレイス内の相対パスの場合、version を完全に省略でき、すべての新しいコミットが新しいバージョンとして扱われます。これは内部または積極的に開発されているプラグインの最も簡単なセットアップです。

リリースチャネルの設定

プラグインの「安定」と「最新」リリースチャネルをサポートするには、同じリポジトリの異なる ref または SHA を指す 2 つのマーケットプレイスを設定できます。その後、管理設定を通じて 2 つのマーケットプレイスを異なるユーザーグループに割り当てることができます。

例

{
  "name": "stable-tools",
  "plugins": [
    {
      "name": "code-formatter",
      "source": {
        "source": "github",
        "repo": "acme-corp/code-formatter",
        "ref": "stable"
      }
    }
  ]
}

{
  "name": "latest-tools",
  "plugins": [
    {
      "name": "code-formatter",
      "source": {
        "source": "github",
        "repo": "acme-corp/code-formatter",
        "ref": "latest"
      }
    }
  ]
}

チャネルをユーザーグループに割り当てる

管理設定を通じて各マーケットプレイスを適切なユーザーグループに割り当てます。例えば、安定グループは以下を受け取ります。

{
  "extraKnownMarketplaces": {
    "stable-tools": {
      "source": {
        "source": "github",
        "repo": "acme-corp/stable-tools"
      }
    }
  }
}

早期アクセスグループは代わりに latest-tools を受け取ります。

{
  "extraKnownMarketplaces": {
    "latest-tools": {
      "source": {
        "source": "github",
        "repo": "acme-corp/latest-tools"
      }
    }
  }
}

プラグイン依存関係バージョンをピンする

プラグインは依存関係を semver 範囲に制限して、依存関係の更新が依存プラグインを破壊しないようにできます。{plugin-name}--v{version} Git タグ規約、範囲構文、および同じ依存関係に対する複数の制約がどのように組み合わされるかについては、プラグイン依存関係バージョンを制限するを参照してください。

プラグインの名前変更または削除

プラグインの name はその安定識別子です。ユーザーは enabledPlugins、pluginConfigs、および /plugin install コマンドでそれを参照するため、それを変更するとすべての既存インストールが破壊されます。UI に表示されるラベルを既存インストールを破壊することなく変更するには、displayName を設定して name を変更しないままにします。

プラグインの name を変更する必要がある場合、または plugins 配列からプラグインを削除する場合は、既存ユーザーが plugin-not-found エラーを見る代わりに移行するように、トップレベルの renames エントリを追加します。自動移行には Claude Code v2.1.193 以降が必要です。各前の名前を現在の名前にマップするか、プラグインが存在しなくなった場合は null にマップします。次の例は formatter を code-formatter に名前変更し、legacy-linter が削除されたことを記録します。

{
  "name": "acme-tools",
  "owner": { "name": "Acme" },
  "plugins": [
    { "name": "code-formatter", "source": "./plugins/code-formatter" }
  ],
  "renames": {
    "formatter": "code-formatter",
    "legacy-linter": null
  }
}

ユーザーが古い名前がまだ設定に含まれた状態で Claude Code を起動すると、Claude Code は renames マップに従います。

• エントリが新しい名前を指している場合、Claude Code はプラグインを新しい名前で読み込み、Renamed to "code-formatter" in the "acme-tools" marketplace などの 1 行の通知を表示します。その後、ユーザー、プロジェクト、ローカル設定スコープの enabledPlugins と pluginConfigs の両方で古いキーを新しいキーに書き直すため、通知は 1 回表示されます。
• null エントリの場合、Claude Code は古いキーを削除し、通知はプラグインがマーケットプレイスから削除されたことを報告します。
• 名前変更されたプラグインが github または npm などのリモートソースを使用する場合、Claude Code は名前変更後に plugin-cache-miss を報告し、ユーザーは新しい名前で取得するために 1 回 /plugin install を実行する必要があります。

renames を追加のみの履歴として扱う：すべてのユーザーが移行することを期待した後でも、古いエントリを所定の位置に保持します。Claude Code はチェーンに従うため、後で code-formatter を formatter-pro に名前変更する場合は、最初のエントリを編集するのではなく、2 番目のエントリを追加します。元の formatter がまだ有効になっているユーザーは、両方のエントリを通じて formatter-pro に解決されます。

マップを編集した後、claude plugin validate . を実行します。チェーンがサイクルを形成したり、null または plugins にリストされている名前で終了しないエントリを拒否します。

以前のバージョンの Claude Code は renames フィールドを無視し、古い名前に対して plugin-not-found を報告します。

検証とテスト

共有する前にマーケットプレイスをテストします。

マーケットプレイス JSON 構文を検証します：

claude plugin validate .

または Claude Code 内から：

/plugin validate .

テスト用にマーケットプレイスを追加します：

/plugin marketplace add ./path/to/marketplace

すべてが機能することを確認するためにテストプラグインをインストールします：

/plugin install test-plugin@marketplace-name

完全なプラグインテストワークフローについては、プラグインをローカルでテストを参照してください。技術的なトラブルシューティングについては、プラグインリファレンスを参照してください。

CLI からマーケットプレイスを管理する

Claude Code は、スクリプトと自動化のための非対話的な claude plugin marketplace サブコマンドを提供します。これらは、対話的なセッション内で利用可能な /plugin marketplace コマンドと同等です。

プラグインマーケットプレイス追加

GitHub リポジトリ、Git URL、リモート URL、またはローカルパスからマーケットプレイスを追加します。

claude plugin marketplace add <source> [options]

引数：

• <source>：GitHub owner/repo ショートハンド、Git URL、marketplace.json ファイルへのリモート URL、またはローカルディレクトリパス。ブランチまたはタグに固定するには、GitHub ショートハンドに @ref を追加するか、Git URL に #ref を追加します

URL はスキームを含める必要があります。Claude Code v2.1.196 以降、gitlab.example.com/team/plugins のようにスキームなしで入力されたホストは、無効な owner/repo ショートハンドとして拒否され、エラーメッセージは https:// を追加するか、ローカルパスに ./ を使用するよう指示します。以前のバージョンでは、これを GitHub リポジトリパスとして誤読し、GitHub の見つからないエラーでクローン時に失敗します。

オプション：

GitHub から owner/repo ショートハンドを使用してマーケットプレイスを追加します。

claude plugin marketplace add acme-corp/claude-plugins

@ref を使用して特定のブランチまたはタグに固定します。

claude plugin marketplace add acme-corp/claude-plugins@v2.0

非 GitHub ホスト上の Git URL から追加します。

claude plugin marketplace add https://gitlab.example.com/team/plugins.git

marketplace.json ファイルを直接提供するリモート URL から追加します。

claude plugin marketplace add https://example.com/marketplace.json

テスト用にローカルディレクトリから追加します。

claude plugin marketplace add ./my-marketplace

マーケットプレイスをプロジェクトスコープで宣言して、.claude/settings.json 経由でチームと共有します。

claude plugin marketplace add acme-corp/claude-plugins --scope project

モノレポの場合、プラグインコンテンツを含むディレクトリにチェックアウトを制限します。

claude plugin marketplace add acme-corp/monorepo --sparse .claude-plugin plugins

プラグインマーケットプレイスリスト

設定されたすべてのマーケットプレイスをリストします。

claude plugin marketplace list [options]

オプション：

--json を使用すると、各エントリには name、source、およびソース固有のフィールドが含まれます：GitHub ソースの場合は repo、Git および URL ソースの場合は url、ローカルソースの場合は path。GitHub および Git ソースには、マーケットプレイスが固定されたブランチまたはタグで追加された場合、ref フィールドも含まれます。

プラグインマーケットプレイス削除

設定されたマーケットプレイスを削除します。エイリアス rm も受け入れられます。

claude plugin marketplace remove <name> [options]

引数：

• <name>：削除するマーケットプレイス名。claude plugin marketplace list で表示されます。これは渡したソースではなく、marketplace.json の name です

オプション：

プラグインマーケットプレイス更新

マーケットプレイスをソースから更新して、新しいプラグインとバージョン変更を取得します。

claude plugin marketplace update [name]

引数：

• [name]：更新するマーケットプレイス名。claude plugin marketplace list で表示されます。省略した場合はすべてのマーケットプレイスを更新します

remove と update の両方は、読み取り専用のシード管理マーケットプレイスに対して実行すると失敗します。すべてのマーケットプレイスを更新する場合、シード管理エントリはスキップされ、他のマーケットプレイスは引き続き更新されます。シード提供プラグインを変更するには、管理者にシードイメージを更新するよう依頼してください。コンテナ用にプラグインを事前入力するを参照してください。

トラブルシューティング

マーケットプレイスが読み込まれない

症状：マーケットプレイスを追加できない、またはそこからプラグインが表示されない

解決策：

• マーケットプレイス URL がアクセス可能であることを確認します
• .claude-plugin/marketplace.json が指定されたパスに存在することを確認します
• claude plugin validate または /plugin validate を使用して JSON 構文が有効であることを確認します。skill、agent、command frontmatter をチェックするには、各プラグインディレクトリに対してコマンドを実行します
• プライベートリポジトリの場合、アクセス権限があることを確認します

マーケットプレイス検証エラー

マーケットプレイスディレクトリから claude plugin validate . または /plugin validate . を実行して、問題をチェックします。マーケットプレイスディレクトリを指定した場合、バリデーターは marketplace.json のスキーマエラー、重複するプラグイン名、ソースパストラバーサルをチェックします。source がローカルパスである各エントリについて、そのプラグイン自体の plugin.json も検証し、エントリの version が plugin.json のものと一致しない場合に警告します。プラグインの plugin.json で見つかった問題には、エントリインデックスが接頭辞として付けられ、plugins[2] plugin.json → の形式になります。

Claude Code v2.1.196 以降、エントリごとのパスは以下も含みます：

• source が . であるプラグイン
• marketplace.json が .claude-plugin ディレクトリの外にある場合に実行され、ソースをファイル自体のディレクトリに対して解決します
• ファイルの別の部分にスキーマエラーがある場合でも、各エントリの問題を報告します

以前のバージョンではマーケットプレイスルートのプラグインをスキップし、.claude-plugin/marketplace.json からのみ下降します。

個別のプラグインの plugin.json およびその skill、agent、command、hook ファイルを検証するには、プラグインディレクトリ自体に対してコマンドを実行します。例えば claude plugin validate ./plugins/my-plugin。一般的なエラー：

警告（ブロッキングなし）：

• Marketplace has no plugins defined：plugins 配列に少なくとも 1 つのプラグインを追加します
• No marketplace description provided：ユーザーがマーケットプレイスを理解するのに役立つように、トップレベルの description を追加します
• Plugin name "x" is not kebab-case：プラグイン名に大文字、スペース、または特殊文字が含まれています。小文字、数字、ハイフンのみに名前を変更します（例：my-plugin）。Claude Code は他の形式を受け入れますが、claude.ai マーケットプレイス同期はそれらを拒否します。

プラグインインストール失敗

症状：マーケットプレイスは表示されますが、プラグインインストールが失敗します

解決策：

• プラグインソース URL がアクセス可能であることを確認します
• プラグインディレクトリに必須ファイルが含まれていることを確認します
• GitHub ソースの場合、リポジトリが公開されているか、アクセス権限があることを確認します
• プラグインソースを手動でクローン/ダウンロードしてテストします
• ソースが ref と sha の両方をピンしている場合、削除されたアップストリームブランチまたはタグはほとんどの Git ホスト（GitHub、GitLab、Bitbucket を含む）でインストールをブロックしません。AWS CodeCommit などの SHA でコミットをフェッチすることをサポートしないサーバーでは、ref が存在する必要があり、ピンされたコミットがそこから到達可能である必要があります。インストールが失敗し続ける場合は、ピンされたコミットがリポジトリに存在することを確認します

プライベートリポジトリ認証が失敗する

症状：プライベートリポジトリからプラグインをインストールするときに認証エラーが発生します

解決策：

手動インストールと更新の場合：

• Git プロバイダーで認証されていることを確認します（例：GitHub の場合は gh auth status を実行）
• 認証情報ヘルパーが正しく設定されていることを確認します：git config --global credential.helper
• リポジトリを手動でクローンして、認証情報が機能することを確認します

バックグラウンド自動更新の場合：

• 環境でトークンが設定されていることを確認します：echo $GITHUB_TOKEN
• トークンに必要な権限があることを確認します（リポジトリへの読み取りアクセス）
• GitHub の場合、トークンがプライベートリポジトリの repo スコープを持つことを確認します
• GitLab の場合、トークンが少なくとも read_repository スコープを持つことを確認します
• トークンが期限切れになっていないことを確認します

オフライン環境でマーケットプレイス更新が失敗する

症状：マーケットプレイス git pull が失敗し、Claude Code が既存のキャッシュをワイプするため、プラグインが利用不可になります。

原因：デフォルトでは、git pull が失敗すると、Claude Code は古いクローンを削除して再クローンを試みます。オフラインまたはエアギャップ環境では、再クローンが同じ方法で失敗し、マーケットプレイスディレクトリが空になります。

解決策：CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1 を設定して、プルが失敗したときにワイプする代わりに既存のキャッシュを保持します：

export CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1

この変数を設定すると、Claude Code は git pull 失敗時に古いマーケットプレイスクローンを保持し、最後の既知の良好な状態を使用し続けます。リポジトリに到達できないオフライン展開の場合は、代わりに CLAUDE_CODE_PLUGIN_SEED_DIR を使用してビルド時にプラグインディレクトリを事前入力します。

Git 操作がタイムアウトする

症状：プラグインインストールまたはマーケットプレイス更新が「Git clone timed out after 120s」または「Git pull timed out after 120s」などのタイムアウトエラーで失敗します。

原因：Claude Code は、プラグインリポジトリのクローンやマーケットプレイス更新のプルを含む、すべての Git 操作に 120 秒のタイムアウトを使用します。大規模なリポジトリまたは遅いネットワーク接続がこの制限を超える可能性があります。

解決策：CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS 環境変数を使用してタイムアウトを増やします。値はミリ秒単位です：

export CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS=300000  # 5 分

相対パスを持つプラグインが URL ベースのマーケットプレイスで失敗する

症状：URL（https://example.com/marketplace.json など）経由でマーケットプレイスを追加しましたが、"./plugins/my-plugin" のような相対パスソースを持つプラグインが「path not found」エラーでインストールに失敗します。

原因：URL ベースのマーケットプレイスは marketplace.json ファイル自体のみをダウンロードします。サーバーからプラグインファイルをダウンロードしません。マーケットプレイスエントリの相対パスは、ダウンロードされなかったリモートサーバー上のファイルを参照します。

解決策：

• 外部ソースを使用：プラグインエントリを相対パスの代わりに GitHub、npm、または Git URL ソースを使用するように変更します：

  { "name": "my-plugin", "source": { "source": "github", "repo": "owner/repo" } }
  

• Git ベースのマーケットプレイスを使用：マーケットプレイスを Git リポジトリでホストし、Git URL で追加します。Git ベースのマーケットプレイスはリポジトリ全体をクローンするため、相対パスが正しく機能します。

インストール後にファイルが見つからない

症状：プラグインはインストールされますが、ファイルへの参照が失敗します。特に、プラグインディレクトリの外部のファイル

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

解決策：symlinks とディレクトリ再構成を含む回避策については、プラグインキャッシングとファイル解決を参照してください。

追加のデバッグツールと一般的な問題については、デバッグと開発ツールを参照してください。

関連項目

• 既成プラグインの検出とインストール - 既存のマーケットプレイスからプラグインをインストール
• プラグイン - 独自のプラグインの作成
• プラグインリファレンス - 完全な技術仕様とスキーマ
• プラグイン設定 - プラグイン設定オプション
• strictKnownMarketplaces リファレンス - 管理マーケットプレイス制限