Claude Plugins APIで社内プラグインをCIから公開する

Plugins APIは、Claude Enterpriseの組織が持つプラグインをAPIで管理するための機能です。社内プラグインのアップロード、バージョンの追加、メンバーに配信するバージョンの切り替えまで、リリースパイプラインから実行できます。claude.aiの管理画面でzipを上げ直す作業を、CIのジョブに置き換えられます。

この記事はCIのジョブを書く人向けに、事前検査・エラー対処・再試行の判断に絞っています。18エンドポイントの全体像、グループ別の提供設定、マーケットプレイス検証、レート制限の詳細はPlugins APIでClaude Enterpriseのプラグイン配布を管理するが扱います。

先に条件を並べます。ベータ版で、使えるのはClaude Enterpriseの組織だけです。Claude Platform(Claude Console)の組織と、HIPAA対応を有効にした組織は対象外です。

使う前に揃える3つの条件

CIに組み込む前に、キーとヘッダーを確認します。ここを外すと、エラー文ではなく404が返ってきます。

「404が返る」ときは、URLの誤りよりもベータヘッダーの付け忘れを先に疑うのが近道です。組織でAPIが有効になっていない場合も、同じく404です。

スコープの分け方

アップロードして結果を読み戻すジョブには、両方のスコープが要ります。write:plugins はPOSTとDELETEを許可しますが、読み取りは許可しません。

read:org_audit と read:compliance_org_data でもGETは通ります。監査用の連携には読み取り専用のキーを別に作ると、公開用のキーを使い回さずに済みます。リポジトリにコミットせず、CIのシークレットに入れてください。

SDK(Python、TypeScript、C#、Go、Java、PHP、Ruby)は client.beta.organization 以下にこのエンドポイントを持ち、ヘッダーも自動で付けます。ant CLIなら ant beta:organization:plugins create です。以降はcurlで書きますが、読み替えは単純です。

アップロード前に確かめる要件

アップロードの規則はclaude.aiの画面からの追加と同じです。CIの前段で検査しておくと、失敗を早く拾えます。

• 形式は .zip か .plugin のアーカイブ1つ、または個別ファイルの束。トップに1階層のフォルダがあってもよい
• .claude-plugin/plugin.json がちょうど1つ必要で、name の宣言が必須。マニフェストのない SKILL.md 単体は拒否される
• name は小文字(どの言語の文字でも可)、数字、ハイフンで最大64字。大文字、空白、アンダースコアは不可
• displayName は64字まで、description は500字まで
• すべての SKILL.md に、name と description を持つYAMLフロントマターが必要。XMLタグは入れられない
• トップレベルの bin/ の下にファイルを置けない。入れ子の .zip も不可
• リクエスト本文と展開後のアーカイブは、それぞれ200MB以内。ファイル数は5,000まで
• ZIPはDEFLATEかSTORE圧縮で、暗号化とシンボリックリンクは不可

200MBを超えると、400ではなく413(request_too_large)が返ります。ファイル数とマーケットプレイスの収容数(500件)の上限は、今後引き上げられる可能性があると明記されています。

最初のプラグインをCIに載せる前に、手元で unzip -l と jq で検査する小さなスクリプトを置いておくと安心です。

# アーカイブ内の構成を事前に確認する例
unzip -l dist/sales-toolkit.zip | grep -c "plugin.json"
unzip -p dist/sales-toolkit.zip .claude-plugin/plugin.json \
  | jq -r '.name' | grep -E '^[a-z0-9-]{1,64}$'

最初の行が 1 を返し、2行目が名前を出力すれば、少なくとも名前の規則は満たしています。ほかの要件はAPI側の検証に任せます。

初回は作成、2回目以降はバージョンの追加

流れは2段階です。最初のリリースでプラグインを作り、それ以降はバージョンを足します。

初回の作成は次のとおりです。marketplace_id を省くと、組織の「ライブラリ」マーケットプレイスに入ります。このマーケットプレイスは最初のアップロード時に作られます。release_notes は5,000字までで、claude.aiのバージョン履歴に表示されます。

curl -X POST "https://api.anthropic.com/v1/organizations/plugins" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: ce-plugins-2026-09-01" \
  -F "files[]=@dist/sales-toolkit.zip" \
  -F "release_notes=First release"

2回目以降のリリースは、バージョンの作成に切り替えます。

curl -X POST \
  "https://api.anthropic.com/v1/organizations/plugins/$PLUGIN_ID/versions" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: ce-plugins-2026-09-01" \
  -F "files[]=@dist/sales-toolkit.zip" \
  -F "release_notes=Adds the call-prep command."

アップロード先にできるのは、組織が持つ manual のマーケットプレイスだけです。Gitリポジトリと同期するマーケットプレイス(github、gitlab、public_git)には、アップロードできません。次の同期で上書きされるためです。そちらは、リポジトリ側を変更します。メンバー個人のプラグインには、バージョンのアップロードも配信バージョンの変更もできず、403になります。

配信バージョンをCIで決める: ピン留めとロールバック

ここが、手作業よりCIが向く場面です。

ピン留めしていないプラグインでは、新しいバージョンが保存されると、通常はそのまま配信されます。テストしてから配信したいなら、現在のバージョンを served_version_id に指定して、一度ピン留めします。以降のアップロードは保存されるだけで、配信バージョンは動きません。昇格させたいバージョンを、自分で指定します。

curl -X POST \
  "https://api.anthropic.com/v1/organizations/plugins/$PLUGIN_ID" \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: ce-plugins-2026-09-01" \
  -d '{"served_version_id": "'"$NEW_VERSION_ID"'"}'

ロールバックも同じ呼び出しです。前のバージョンのIDを送ります。ピン留めしたプラグインは、ピン留めを外せません。APIでもclaude.aiでも同じです。ピン留めは一方通行だと理解したうえで、運用を決めてください。

内容スキャンがオンのときの注意

組織の設定でコンテンツスキャンが有効なら、保存されたバージョンは非同期でスキャンされます。APIで上げたバージョンは、スキャンの完了を待ちません。ピン留めがないまま配信バージョンになると、スキャンが通るまでメンバーはそのプラグインを受け取れなくなります。スキャンが失敗すれば、受け取れないままです。

メンバーに現行バージョンを使わせ続けたいなら、先にピン留めしておきます。昇格前には次の順で確認します。

1. GET /v1/organizations/plugins/{plugin_id}/versions/{version} を、content_scan.status が processing でなくなるまで繰り返す
2. 結果が completed で、assessment が pass か warn なら昇格する

スキャン中のバージョンへ切り替えると409(scan_pending)、失敗したバージョンへは400(scan_failed)です。最初のピン留めにも同じ判定がかかるので、現行バージョンのスキャンが終わるまで409が返ることがあります。

スキャンは、顧客管理の暗号鍵やゼロデータ保持を使う組織には提供されません。スキャンされていないバージョンは content_scan が null で、通常どおり配信されます。

公開したあと、誰が使えるようにするか

作成直後のプラグインに、独自の設定はありません。マーケットプレイスの既定値を引き継ぎ、既定値が未設定なら not_available(非表示)です。つまり、アップロードしただけではメンバーに見えません。

設定値は4つです。

組織全体の設定と、グループごとの設定を持てます。グループに設定があるメンバーは、組織全体の値ではなく、所属グループの設定のうち最も許容度の高いものを受け取ります。足し算ではなく置き換えです。組織全体を required にしても、Pilotグループに available を置いてあれば、Pilotの人は available のままです。

パイロットから全社展開へ移すときは、組織全体の値を required などに設定してから、グループの設定を削除する順で進めます。

CIで踏みやすいエラーと再試行

上げ直しの扱いは、エラーによって違います。

冪等性キーを受け付けるエンドポイントはありません。作成のレスポンスを取りこぼしたなら、そのまま再試行します。409の plugin_name_taken が返り、プラグインIDが分かるので、そこから続けられます。

バージョンの作成は事情が違います。レスポンスを取りこぼして再送すると、同一内容のバージョンがもう1つできます。アップロードの前に latest_version_id を記録しておき、失敗したらプラグインを読み直して、値が変わっていないときだけ再送します。

レート制限は、組織あたり読み取り300リクエスト/分、書き込み60リクエスト/分です。マーケットプレイスの検証は読み取り扱いで、さらに10回/分の上限があります。1つのプラグインへのインストール設定の書き込みを同時に送ると、503になることがあります。1件ずつ送ってください。

このAPIで扱えないこと

• 対象は組織が持つプラグインで、メンバー個人のスキル単体は扱えない。Anthropicが公開するプラグインも一覧に入らない
• マーケットプレイスの作成、リポジトリとの接続、削除はclaude.aiで行う
• 削除は取り消せず、バージョン単位の削除もない。止めたいだけなら、インストール設定を not_available にする方法がある

利用状況の取得は別のAPIの役割です。どのプラグインがどれだけ使われたかは、Enterprise Analytics APIの解説にまとめています。claude.ai側でスキャンが何を見るかはプラグインとスキルのセキュリティスキャンの記事が詳しく、画面から社内向けに配る手順は社内向けプラグインマーケットプレイスの作り方にあります。プラグインそのものの概念はClaude.aiのプラグイン機能の解説が入口です。

まとめ

公開の自動化で効くのは、配信バージョンを別に持てる点です。ピン留めを一度入れておけば、CIは「保存」と「昇格」を別の工程に分けられます。ただしピン留めは外せず、スキャンがオンの組織ではピン留めなしの上書きがメンバーの利用停止につながります。この2点は、最初のジョブを書く前に決めておく項目です。