Skip to content
← リリースに戻る · 2.1.259
新機能 / v2.1.259

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: マニフェスト自体の検証結果。マニフェストなしでの実行の場合は null
  • contents: ファイルごとの検証結果。各結果は 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

変更の詳細