Skip to content
← Back to release · 2.1.259
New features / v2.1.259

JSON plugin validation reports

CHANGELOG · original

Added --json to claude plugin validate for a machine-readable validation report
Open official changelog ↗

Documentation

Documentation excerpt

plugin validate

Validate a plugin manifest, a marketplace manifest, or the skills, agents, and commands in a directory, and exit with a code a CI job can act on. For the create, test, and edit workflow, see Create a plugin. For what the validator checks in each manifest, see the plugin manifest reference and the marketplace reference.

claude plugin validate <path> [options]
Flag Description
--strict Treat warnings as errors, so unrecognized fields and missing metadata that the runtime tolerates fail the run
--json Output the validation report as one JSON object with the same exit codes. Requires Claude Code v2.1.259 or later

Validate a plugin before committing it:

claude plugin validate ./my-plugin --strict

Validate a directory

The <path> is a manifest file or a directory. Given a directory, Claude Code picks what to validate by what it finds there:

  • .claude-plugin/marketplace.json, when it exists
  • Otherwise .claude-plugin/plugin.json
  • Otherwise the component files, chosen by the directory's name:
    • A directory named skills, agents, or commands: the files inside it
    • A directory named .claude: the skills, agents, and commands directories inside it
    • Any other directory: those three directories under its .claude

When the directory holds both a .claude-plugin/marketplace.json and a .claude-plugin/plugin.json, Claude Code validates the marketplace and also the plugin's manifest and component files. This requires Claude Code v2.1.289 or later.

Claude Code doesn't follow symlinks inside the directory you name. What it does depends on where the link is:

  • A linked skills, agents, or commands directory under the plugin or .claude root: Claude Code warns that nothing in it was read.
  • A linked entry inside a skills, agents, or commands directory: Claude Code skips it and warns, per directory, how many entries it skipped that a session would load.
  • The skills, agents, or commands directory you name is itself a symlink, or its parent .claude directory is: Claude Code reports an error and checks nothing in it. Name the real directory instead.

A few files are not read by a validation run:

  • A SKILL.md at the plugin root: when you run claude plugin validate against a plugin directory, Claude Code doesn't check a SKILL.md at the plugin root
  • A CLAUDE.md at the plugin root: in a plugin run, Claude Code also warns about a CLAUDE.md at the plugin root
  • Plugin files in a marketplace run: from a marketplace directory, Claude Code doesn't open the skill, agent, or command files of plugins the marketplace lists in other directories, or the MCP server files they bundle. To find errors in those files, validate each plugin directory

Validate a manifest file

When the file isn't named plugin.json or marketplace.json and isn't in a .claude-plugin directory, Claude Code decides what it is by its fields. It validates the file as a marketplace in these cases, and otherwise as a plugin manifest:

  • plugins is an array
  • plugins and owner are both present
  • The file has a field that only marketplace.json defines, such as owner, and none that only plugin.json defines, such as author

To choose the checks yourself, name the file plugin.json or marketplace.json. Claude Code validates any other file in a .claude-plugin directory as a plugin manifest.

Output and exit codes

Claude Code prints the file it validated, any errors and warnings with their paths, and a verdict line. The exit code follows the verdict:

Exit code Verdict line Meaning
0 Validation passed or Validation passed with warnings The manifest loads. With --strict, no warnings either
1 Validation failed or Validation failed (--strict treats warnings as errors) An error, or a warning under --strict. Advice doesn't count, with or without --strict
2 Unexpected error during validation: <reason> The validator itself failed, such as on an unreadable path

With --json, Claude Code writes the report to stdout as one JSON object with these top-level fields:

  • success: the same verdict the exit code gives
  • strict: whether the run treated warnings as errors
  • target: the resolved path Claude Code validated
  • manifest: the manifest's own result, or null for a run without a manifest
  • contents: per-file results, each naming its file and carrying errors, warnings, and notes arrays. Files with no error, warning, or note get no entry, so contents is empty when there's nothing to report. For a directory with marketplace.json and plugin.json, manifest is the marketplace.json result and plugin.json results go in contents
    • gatingHooks: whether each mod hook that can refuse an action, such as a tool.call hook, has a .catch handler. Each item gives module, pattern, hook, and hasCatch. Requires Claude Code v2.1.290 or later
  • advice: the advice of the run, each entry naming the README as file and carrying a message and the installLine to paste. Empty when there is none. Requires Claude Code v2.1.295 or later
  • hosts: named hosts, plus unread plugin parts that could reach others. null when the run can't list them. A plugin can reach unlisted hosts. Requires Claude Code v2.1.328 or later

On exit 2, the command writes nothing to stdout. The error message goes to stderr.

Advice on the README

An Advice block in the output of claude plugin validate means a plugin's README has no line that installs the plugin from a marketplace, and it gives you a line to add. Advice isn't an error or a warning. It doesn't change the verdict line or the exit code, with or without --strict. It requires Claude Code v2.1.295 or later.

For example, validating the acme-tools marketplace's directory prints this advice for its deploy-helper plugin:

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

To clear the advice, paste the suggested line into the README it names, then run claude plugin validate again in your shell. The Advice block is gone.

If the suggested line holds the placeholder <owner>/<repo>, pasting it unchanged doesn't clear the advice. Get the real source first:

  • You validated the plugin's own directory: when the marketplace lists the plugin from a directory inside its own, validate that directory instead. When it lists the plugin from somewhere else, such as a GitHub repository, fill in <owner>/<repo> yourself
  • You validated the marketplace's directory: Claude Code fills in the source from the origin remote of the .git directory at the top of that directory. When it can't use that remote, such as when there is none, replace <owner>/<repo> with your marketplace's source yourself

An install line you already wrote counts when plugin install, or its short form plugin i, is followed on the same line by either of these. The /plugin and claude plugin spellings both count:

  • <plugin>@<marketplace>, such as /plugin install deploy-helper@acme-tools
  • The plugin's name and --marketplace <source>, such as /plugin install deploy-helper --marketplace acme/tools

Documentation snapshot · 2026-11-20

Change details