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, orcommands: the files inside it - A directory named
.claude: theskills,agents, andcommandsdirectories inside it - Any other directory: those three directories under its
.claude
- A directory named
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, orcommandsdirectory under the plugin or.clauderoot: Claude Code warns that nothing in it was read. - A linked entry inside a
skills,agents, orcommandsdirectory: Claude Code skips it and warns, per directory, how many entries it skipped that a session would load. - The
skills,agents, orcommandsdirectory you name is itself a symlink, or its parent.claudedirectory 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.mdat the plugin root: when you runclaude plugin validateagainst a plugin directory, Claude Code doesn't check aSKILL.mdat the plugin root - A
CLAUDE.mdat the plugin root: in a plugin run, Claude Code also warns about aCLAUDE.mdat 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:
pluginsis an arraypluginsandownerare both present- The file has a field that only
marketplace.jsondefines, such asowner, and none that onlyplugin.jsondefines, such asauthor
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 givesstrict: whether the run treated warnings as errorstarget: the resolved path Claude Code validatedmanifest: the manifest's own result, ornullfor a run without a manifestcontents: per-file results, each naming itsfileand carryingerrors,warnings, andnotesarrays. Files with no error, warning, or note get no entry, socontentsis empty when there's nothing to report. For a directory withmarketplace.jsonandplugin.json,manifestis themarketplace.jsonresult andplugin.jsonresults go incontentsgatingHooks: whether each mod hook that can refuse an action, such as atool.callhook, has a.catchhandler. Each item givesmodule,pattern,hook, andhasCatch. Requires Claude Code v2.1.290 or later
advice: the advice of the run, each entry naming the README asfileand carrying amessageand theinstallLineto paste. Empty when there is none. Requires Claude Code v2.1.295 or laterhosts:namedhosts, plusunreadplugin parts that could reach others.nullwhen 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
originremote of the.gitdirectory 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