マーケットプレイスのstrict modeとvalidateの使い方
定義の権威を決めるstrict modeと、配布前に実行するclaude plugin validateの使い方を扱います。
このTipsでできること
マーケットプレイスを配布する前に確認しておきたい2点、strict フィールドの使い分けと claude plugin validate の実行方法をまとめます。どちらもマーケットプレイス運営者が公開前に一度は判断・実行しておくべき項目です。
この2つを後回しにすると、社内で配ったプラグインが「一部のユーザーだけ読み込めない」「スキルが増えているはずなのに反映されない」という報告につながりやすくなります。原因の多くは、strict の既定値を意識せずマーケットプレイスエントリと plugin.json を両方書いてしまった、あるいは配布前に claude plugin validate を一度も走らせていなかった、というシンプルなものです。
strictフィールドで定義の権威を決める
プラグインの各コンポーネント(スキル・エージェント・フック・MCPサーバー・出力スタイル)には、定義の権威が2つ存在しえます。plugin.json とマーケットプレイスエントリです。どちらが実際に定義するかは、マーケットプレイスエントリの strict フィールドで決まります。
| 値 | ふるまい |
|---|---|
true(既定) | ふるまいplugin.json が権威を持つ。マーケットプレイスエントリは追加のコンポーネントを補うだけで、両方がマージされる |
false | ふるまいマーケットプレイスエントリが定義のすべてになる。プラグイン側にも plugin.json があってコンポーネントを宣言していると、これは競合とみなされプラグインは読み込まれない |
strict: true(既定)が向いているのは、プラグインが自分の plugin.json を持ち、自分でコンポーネントを管理しているケースです。ほとんどのプラグインはこのままで問題ありません。
strict: false が向いているのは、マーケットプレイス側が完全にコンポーネントを制御したいケースです。プラグインのリポジトリは生ファイルを提供するだけで、そのうちどれをスキル・エージェント・フックとして公開するかはマーケットプレイスエントリ側が決めます。プラグイン作者が意図した構成とは違う形でマーケットプレイスがコンポーネントを再構成・キュレーションしたい場合に使います。
典型例を挙げます。社内の共有リポジトリに複数チームのスキルファイルが雑多に置かれていて、マーケットプレイス運営チームが「このディレクトリ配下だけを正式なプラグインとして公開する」と選別したい場合です。この場合、プラグイン側のリポジトリ作者に plugin.json の整備を依頼する必要はありません。マーケットプレイスエントリの commands / agents / skills フィールドで対象パスを直接指定すれば、公開する範囲をマーケットプレイス側の一存で決められます。
ここで注意したいのは、strict: false が失敗になるのは「プラグイン側の plugin.json がコンポーネントを宣言している」場合に限られる点です。plugin.json 自体が存在しても、name や description のようなメタデータだけを書いていてコンポーネントを宣言していなければ、競合にはなりません。
strictKnownMarketplacesとは別の設定
名前が似ているため混同しやすい設定があります。strictKnownMarketplaces です。これは組織のmanaged settingsで使う設定で、ユーザーが追加できるマーケットプレイス自体を許可リストで絞ります。一方の strict は、プラグイン1つの中で「誰が定義の権威か」を決める設定で、両者は別物です。前者は .claude-plugin/marketplace.json のプラグインエントリに書き、後者は組織のmanaged settingsに書きます。managed settingsの仕組み自体はClaude Code組織管理ガイドで扱っています。
配布前にclaude plugin validateを実行する
マーケットプレイスを共有する前に、まずJSONの構文とスキーマを検証します。手順はシンプルです。マーケットプレイスのディレクトリで、次のいずれかを実行するだけです。
claude plugin validate .Claude Codeセッション内からでも構いません。同じ検証をスラッシュコマンドで実行できます。
/plugin validate .マーケットプレイスのディレクトリを指定した場合、検証対象は3つです。marketplace.json のスキーマエラー・プラグイン名の重複・ソースパスのトラバーサルをチェックします。source がローカルパスのエントリについては、そのプラグイン自身の plugin.json も検証対象になり、エントリ側の version と plugin.json 側の値が食い違っていれば警告が出ます。プラグインの plugin.json 内で見つかった問題は、plugins[2] plugin.json → のようにエントリの番号付きで表示されるので特定は容易です。
v2.1.196以降では、このプラグインごとの検証パスに次の改善が加わっています。
sourceが.のプラグインも対象に含まれるmarketplace.jsonが.claude-pluginディレクトリの外にある場合でも実行され、ファイル自身のディレクトリを基準にソースを解決する- ファイルの一部にスキーマエラーがあっても、各エントリの問題を個別に報告する
なお、マーケットプレイスのディレクトリを対象にした検証では、プラグイン内のスキル・エージェント・コマンド・フックのファイルは開きません。それらのファイルの誤りを見つけたいときは、対象ディレクトリを変えて実行し直す必要があります。
検証対象を選んで実行する
claude plugin validate は、指定したディレクトリによってチェックする内容が変わります。何を確かめたいかで、渡すパスを選びます。
| 確認したいもの | 実行コマンド |
|---|---|
plugin.json を持つプラグイン全体 | 実行コマンドclaude plugin validate ./plugins/my-plugin |
スキル・エージェント・コマンドのディレクトリ単体(plugin.json がまだ無いプラグインなど) | 実行コマンドclaude plugin validate .claude/skills のように対象ディレクトリを直接指定 |
ルート直下が SKILL.md になっているフォルダ | 実行コマンド親の skills ディレクトリを指定して実行(skills という名前のディレクトリでないと対象外) |
| プロジェクトの3ディレクトリをまとめて | 実行コマンドclaude plugin validate .claude |
| ユーザーレベルの設定 | 実行コマンドclaude plugin validate ~/.claude |
プラグインディレクトリを対象にした実行では、プラグインルート直下の SKILL.md はチェックされません。skills という名前のディレクトリの下にプラグインが置かれている場合は、そのディレクトリ自体を指定する実行と、プラグインディレクトリを指定する実行の両方を行う必要があります。
Claude Code v2.1.233以降が必要なのは、表の1行目(plugin.json を持つプラグインを対象にする実行)を除く4行です。1行目だけは、それより古いバージョンでも実行できます。
よく出るエラーと対処
配布前の検証で実際によく出る、対処に迷いやすいものを挙げます。マーケットプレイスのディレクトリを対象にした実行のエラーはこちらです。
| エラー | 原因 | 対処 |
|---|---|---|
No manifest found in directory | 原因対象ディレクトリに marketplace.json も plugin.json も、チェック対象になるスキル・エージェント・コマンドファイルも無い | 対処マーケットプレイスのルートから実行するか、必須フィールドを持つ marketplace.json を作成する |
Duplicate plugin name "x" found in marketplace | 原因2つのプラグインが同じ名前を使っている | 対処各プラグインに一意の name を付ける |
plugins[0].source: Path contains ".." | 原因ソースパスに .. が含まれている | 対処マーケットプレイスルートからの相対パスを .. なしで指定する |
Marketplace name cannot contain control or bidirectional-formatting characters | 原因マーケットプレイス名に、文字の表示順を操作するUnicode制御文字が混ざっている | 対処名前から該当文字を取り除く(v2.1.247より前はこの文字が別の誤ったエラーメッセージになっていた) |
スキルやエージェントのディレクトリを直接指定する実行では、出るものが変わります。よく出る出力はこちらです。
| 出力 | 意味 |
|---|---|
Validation passed | 意味問題なし |
YAML frontmatter failed to parse: ... | 意味SKILL.md 等のfrontmatterが壊れている |
hooks/hooks.json の Invalid JSON syntax: ... | 意味フック定義のJSONが壊れている |
プラグインルートの CLAUDE.md に関する警告 | 意味ルート直下に置くべきでないファイルが混ざっている |
非致命的な警告もあります。プラグインが1つも定義されていない、説明文が無い、名前がkebab-caseでない(小文字・数字・ハイフンのみが推奨)、といったものです。この中で名前まわりの警告は無視しないほうが安全です。org / org-provisioned / unknown という名前はClaude Desktopでは予約語として扱われ、マーケットプレイスの同期ごと拒否されます。Claude Desktopが受け付ける名前は128文字までの英数字・.・_・-のみです。そのため、Claude Codeで検証が通ってもClaude Desktop側では個別のプラグインが静かに落とされることがあります。
これらのDesktop向けチェックはv2.1.221以降の claude plugin validate で追加されたものです。それより前のバージョンでは警告自体が出ません。古いCLIで検証が通っていても油断はできない理由です。マーケットプレイスをClaude Desktopでも配りたい場合は、検証に使うClaude Code本体のバージョンも意識しておく必要があります。
symlinkを使っている場合の注意
検証はディレクトリ内のsymlinkをたどりません。skills / agents / commands ディレクトリ自体がsymlinkの場合は「中身を読んでいない」という警告になり、ディレクトリの中の1エントリだけがsymlinkの場合はそのエントリだけがスキップされて警告が出ます。.claude 自体やコンポーネントディレクトリ自体がsymlinkだと、エラーになり中身は一切チェックされません。マーケットプレイス内で複数プラグインが同じ skills/ フォルダをsymlink共有している場合は、リンク先の実ディレクトリを直接指定して再実行すると、その中身も検証できます。
公開前チェックの流れ
ここまでの内容を、実際にマーケットプレイスを公開する前の作業順に並べ直すと次のようになります。
- プラグインごとに
strictを決める。自分のplugin.jsonでコンポーネントを管理するなら既定のtrueのまま、マーケットプレイス側で公開範囲を制御したいならfalseにする marketplace.jsonとプラグインエントリを書く- マーケットプレイスのディレクトリで
claude plugin validate .を実行し、スキーマエラー・名前の重複・パストラバーサルを潰す - スキルやエージェントの中身まで確かめたい場合は、該当ディレクトリを直接指定して再実行する
/plugin marketplace add ./path/to/marketplaceでローカルに追加し、テスト用プラグインを実際にインストールして動作を確かめる
この順番で一度通しておけば、配布後に「一部のユーザーだけ読み込めない」という形で問題が表面化するのを避けられます。
よくある質問
strict:falseでもplugin.jsonは全く不要になりますか
いいえ。plugin.json 自体を省略することも、name などのメタデータだけを書いて残しておくこともできます。失敗になるのは、plugin.json がスキルやフックといったコンポーネントを宣言していて、かつマーケットプレイスエントリ側にも定義がある場合だけです。
claude plugin validateはCIパイプラインに組み込めますか
ローカルで実行するのと同じコマンドをCIのステップに追加するだけで組み込めます。マーケットプレイスをリポジトリで管理している場合、プッシュのたびに構文エラーやパストラバーサルを検知できるようにしておくと、公開前に気づける機会が増えます。
警告(warning)は無視して公開してよいですか
内容によります。説明文が無い程度の警告は、公開に支障しません。ただし名前がkebab-caseでない、あるいはClaude Desktopの予約語・命名規則に触れている警告は別です。Claude Desktop側でマーケットプレイス全体が同期対象から外れたり、該当プラグインだけ静かに落とされたりする実害につながります。名前まわりの警告は直しておくのが安全です。
まとめ
strict フィールドは、プラグイン1つの中でコンポーネント定義の権威をどちらに置くかを決める設定で、既定の true なら plugin.json を主に、false にすればマーケットプレイスエントリを主にできます。組織全体でどのマーケットプレイスを追加してよいかを絞る strictKnownMarketplaces とは別の設定である点を混同しないよう注意してください。
配布前には claude plugin validate . で構文・重複・パストラバーサルを確認し、スキルやエージェントの中身まで見たいときは対象ディレクトリを変えて実行し直します。マーケットプレイスの作り方全体はClaude Codeプラグイン完全ガイド、コンテナへの事前展開はプラグインをコンテナへ事前展開する手順もあわせて確認できます。