claude plugin validate に --json
CHANGELOG 原文(英語)
Added --json to claude plugin validate for a machine-readable validation report 公式の変更履歴を開く ↗ 日本語での補足
機械可読な検証レポートを出力
ドキュメント
ドキュメントの抜粋(参考訳)
plugin validate
プラグインマニフェスト、マーケットプレイスマニフェスト、またはディレクトリ内のスキル・エージェント・コマンドを検証し、CI ジョブが判定に使える終了コードで終了します。作成、テスト、編集のワークフローについては、プラグインを作成するを参照してください。各マニフェストで検証される内容については、プラグインマニフェストリファレンスとマーケットプレイスリファレンスを参照してください。
claude plugin validate <path> [options]
| Flag | Description |
|---|---|
--strict |
警告をエラーとして扱います。これにより、実行時には許容される認識されないフィールドやメタデータの不足があると、実行が失敗します |
--json |
検証レポートを、同じ終了コードのまま1つの JSON オブジェクトとして出力します。Claude Code v2.1.259 以降が必要です |
コミットする前にプラグインを検証します。
claude plugin validate ./my-plugin --strict
ディレクトリを検証する
<path> には、マニフェストファイルまたはディレクトリを指定します。ディレクトリを指定した場合、Claude Code はそこで見つかったものに応じて検証対象を選びます。
.claude-plugin/marketplace.jsonがあれば、それ- なければ
.claude-plugin/plugin.json - それもなければ、ディレクトリ名に応じて選ばれるコンポーネントファイル:
skills、agents、commandsという名前のディレクトリ: その中のファイル.claudeという名前のディレクトリ: その中のskills、agents、commandsディレクトリ- それ以外のディレクトリ: その
.claude配下にある、これら3つのディレクトリ
ディレクトリが .claude-plugin/marketplace.json と .claude-plugin/plugin.json の両方を保持している場合、Claude Code はマーケットプレイスだけでなく、プラグインのマニフェストとコンポーネントファイルも検証します。これには Claude Code v2.1.289 以降が必要です。
Claude Code は、指定したディレクトリ内のシンボリックリンクをたどりません。どう扱われるかは、リンクの場所によって異なります。
- プラグインまたは
.claudeのルート直下にある、リンクされたskills、agents、commandsディレクトリ: Claude Code は、その中身を何も読み取らなかったことを警告します。 skills、agents、commandsディレクトリ内のリンクされたエントリ: Claude Code はそれをスキップし、セッションであれば読み込まれるはずのエントリを何件スキップしたかを、ディレクトリごとに警告します。- 指定した
skills、agents、commandsディレクトリ自体、またはその親の.claudeディレクトリがシンボリックリンクの場合: Claude Code はエラーを報告し、その中身を何も検査しません。代わりに実体のディレクトリを指定してください。
検証の実行では、いくつかのファイルが読み取られません。
- プラグインルートにある
SKILL.md: プラグインディレクトリに対してclaude plugin validateを実行した場合、Claude Code はプラグインルートにあるSKILL.mdを検査しません - プラグインルートにある
CLAUDE.md: プラグインの実行では、Claude Code はプラグインルートにあるCLAUDE.mdについて警告も出します - マーケットプレイスの実行におけるプラグインのファイル: マーケットプレイスディレクトリから実行した場合、Claude Code は、マーケットプレイスが別のディレクトリから列挙している各プラグインのスキル、エージェント、コマンドのファイルや、それらに同梱される MCP サーバーのファイルを開きません。これらのファイルのエラーを見つけるには、各プラグインディレクトリを検証してください
マニフェストファイルを検証する
ファイル名が plugin.json や marketplace.json ではなく、.claude-plugin ディレクトリ内にもない場合、Claude Code はそのフィールドから種類を判断します。次のいずれかに該当する場合はマーケットプレイスとして検証し、それ以外はプラグインマニフェストとして検証します。
pluginsが配列であるpluginsとownerの両方が存在するownerのようにmarketplace.jsonにしかないフィールドを持ち、authorのようにplugin.jsonにしかないフィールドを持たない
どちらのチェックを使うか自分で選ぶには、ファイル名を plugin.json または marketplace.json にしてください。Claude Code は、.claude-plugin ディレクトリ内のそれ以外のファイルを、プラグインマニフェストとして検証します。
出力と終了コード
Claude Code は、検証したファイル、パス付きのエラーと警告、判定行を出力します。終了コードは判定に従います。
| Exit code | Verdict line | Meaning |
|---|---|---|
0 |
Validation passed または Validation passed with warnings |
マニフェストを読み込めます。--strict の場合は警告もありません |
1 |
Validation failed または Validation failed (--strict treats warnings as errors) |
エラーがあるか、--strict の下で警告があります。Advice は、--strict の有無にかかわらずカウントされません |
2 |
Unexpected error during validation: <reason> |
読み取れないパスなど、検証処理そのものが失敗しました |
--json を指定すると、Claude Code は次のトップレベルフィールドを持つ1つの JSON オブジェクトとして、レポートを標準出力に書き出します。
success: 終了コードと同じ検証結果strict: 警告をエラーとして扱ったかどうかtarget: Claude Code が検証した、解決後のパスmanifest: マニフェスト自体の検証結果。マニフェストなしでの実行の場合はnullcontents: ファイルごとの検証結果。各結果はfileにファイル名を持ち、errors、warnings、notesの各配列を含みます。エラー・警告・ノートのないファイルにはエントリが作られないため、報告することがない場合はcontentsは空になります。marketplace.jsonとplugin.jsonの両方があるディレクトリでは、manifestはmarketplace.jsonの結果になり、plugin.jsonの結果はcontentsに入りますgatingHooks:tool.callフックのように、アクションを拒否できる各mod フックが.catchハンドラーを持っているかどうか。各項目はmodule、pattern、hook、hasCatchを示します。Claude Code v2.1.290 以降が必要です
advice: この実行のadvice。各エントリは README をfileとして示し、messageと、貼り付け用のinstallLineを持ちます。advice がない場合は空になります。Claude Code v2.1.295 以降が必要ですhosts:namedなホストと、他のホストに到達し得るunreadなプラグイン部分。実行がそれらを一覧できない場合はnull。プラグインは、一覧にないホストにも到達できます。Claude Code v2.1.328 以降が必要です
終了コードが 2 の場合、このコマンドは標準出力に何も書き出しません。エラーメッセージは標準エラー出力に送られます。
READMEに関するadvice
claude plugin validate の出力にある Advice ブロックは、プラグインの README にマーケットプレイスからそのプラグインをインストールする行がないことを意味し、追加すべき行を提示します。advice はエラーでも警告でもありません。--strict の有無にかかわらず、判定行や終了コードを変えません。Claude Code v2.1.295 以降が必要です。
例えば、acme-tools マーケットプレイスのディレクトリを検証すると、その deploy-helper プラグインについて次の advice が出力されます。
Validating marketplace manifest: /path/to/acme-tools/.claude-plugin/marketplace.json
ℹ Advice (does not change the verdict):
❯ /path/to/acme-tools/plugins/deploy-helper/README.md: This README has no line that installs "deploy-helper" from a marketplace. Add the install line, which works in one step on Claude Code 2.1.275 or later.
/plugin install deploy-helper --marketplace acme/tools
✔ Validation passed
advice を解消するには、示された行を該当する README に貼り付けてから、シェルで claude plugin validate を再度実行してください。Advice ブロックがなくなります。
示された行に <owner>/<repo> というプレースホルダーが含まれている場合、そのまま貼り付けても advice は解消されません。先に実際のソースを取得してください。
- プラグイン自身のディレクトリを検証した場合: マーケットプレイスがそのプラグインを自身のディレクトリ内の場所から列挙している場合は、代わりにそのディレクトリを検証してください。GitHub リポジトリなど別の場所から列挙している場合は、
<owner>/<repo>を自分で入力してください - マーケットプレイスのディレクトリを検証した場合: Claude Code は、そのディレクトリの最上位にある
.gitディレクトリのoriginリモートからソースを入力します。リモートが存在しないなどの理由でそれを使えない場合は、<owner>/<repo>を自分のマーケットプレイスのソースに置き換えてください
すでに書かれているインストール行は、plugin install(省略形の plugin i)に続けて、同じ行に次のいずれかが書かれている場合にカウントされます。/plugin と claude plugin のどちらの表記もカウントされます。
<plugin>@<marketplace>、例えば/plugin install deploy-helper@acme-tools- プラグイン名と
--marketplace <source>、例えば/plugin install deploy-helper --marketplace acme/tools
取得日 · 2026-11-20