claude plugin validate: catch what breaks your plugin before anyone installs it

One command reads your plugin.json, your skills, your agents and your hooks, and tells you which lines Claude Code will ignore at load time. What it stays quiet about matters just as much.

A plugin with five files: claude plugin validate reads four of them and one never reaches the report, next to the green pass and the --strict failure

TL;DR Run claude plugin validate --strict ./my-plugin before you share it. With --strict, a warning (a misspelled field, a skill with no description) exits 1, which is exactly what you want gating CI. Point it at the folder's real path: it does not follow symlinks.

A broken plugin does not complain. Claude Code loads what it understands, silently ignores what it does not, and the person who installed it ends up in a session where your skill is nowhere to be found. No trace, no warning, nothing to grep for in a log.

claude plugin validate is the step before that. It reads the manifest, the skills, the agents and the hooks in one pass and tells you which lines will fall on the floor at load time. Same job /doctor does on your own install, pointed at what you are about to hand out instead of at what you are running.

What it looks like when something is off

$ claude plugin validate ./my-plugin

Validating plugin manifest: ./my-plugin/.claude-plugin/plugin.json

⚠ Found 2 warnings:

  ❯ autor: Unknown field 'autor' — did you mean 'author'? Claude Code ignores
    unrecognized fields at load time, so this field has no effect.
  ❯ author: No author information provided. Consider adding author details

Validating skill: ./my-plugin/skills/hello/SKILL.md

⚠ Found 1 warning:

  ❯ description: No description in frontmatter. A description helps users and
    Claude understand when to use this skill.

✔ Validation passed with warnings

It only prints the files that have something to say. If all twenty of your skills are fine, none of them is listed: you get the header and the green check, and that means it read them all, not that it skipped them.

The distinction that matters is warning versus error. A warning still loads: the autor field will sit in your JSON and Claude Code will go on never reading it. An error does not load: invalid JSON, a missing name, a commands path pointing at a folder that is not there. That is when the command exits 1.

The warnings carry most of the value, and by default they pass

A field one letter off is exactly the kind of thing a human review waves through and nobody catches until someone asks why your command does not exist. Hence --strict:

1. On your machine, before you share it

claude plugin validate --strict ./my-plugin

Every warning becomes an error and the run ends in ✘ Validation failed (--strict treats warnings as errors) with exit 1.

2. In CI, before the merge

- run: npx @anthropic-ai/claude-code plugin validate --strict .

The exit code is the contract. If you would rather process the report than read it, --json returns the same structure (errors, warnings, notes per file) with the same exit codes.

Where to point it, which is not obvious

With a manifest, hand it the plugin folder and it looks for .claude-plugin/plugin.json or .claude-plugin/marketplace.json. Without one, it validates a loose component directory, but only if the directory is named after the component: skills/, agents/ or commands/. Point it at plain my-plugin/, or at one skill's own folder, and you get No manifest found in directory.

There is one more detail that handed me an empty result the first time. My skills live in a repo and ~/.claude/skills is a wall of symlinks:

$ claude plugin validate ~/.claude/skills

⚠ Found 1 warning:

  ❯ directory: 15 entries here are symlinks and were not read — components are
    read without following symlinks. A session loading this directory does
    follow them, so validate the real paths separately.

Fifteen skills, zero validated. A session does follow them, so the command says so and sends you to the real path. Pointed at ~/code/ai-infra/skills it passes clean.

What a green check does not promise

It validates what the loader would load, and nothing else. Three gaps worth keeping in mind:

Content in the wrong folder does not exist to anyone. A skill sitting in .claude-plugin/skills/ is never scanned, so the run ends in ✔ Validation passed without ever mentioning it. That is not a miss on its part: if the runtime will not read it, there is nothing to validate. But a green check is no proof your skill is where you think it is.

In a marketplace.json, a source pointing at a folder that does not exist passes, --strict included. In plugin.json that same broken path is a hard error, so the check exists; it just does not reach the catalog.

And it does not validate content. A skill having a description says nothing about whether that description makes Claude reach for it at the right moment, or whether your hooks do what you think. That gets proven by using it, or with claude plugin eval. validate only guarantees the thing arrives in one piece.

Reference

What you hand it	What it does
`./my-plugin` (with `.claude-plugin/`)	Validates the manifest and everything in it
`./skills`, `./agents`, `./commands`	Validates loose components, no manifest needed
`--strict`	Turns warnings into errors (exit 1)
`--json`	Same report as JSON, same exit codes
Exit 0 / exit 1	Passed (warnings or not) / failed

Run it before every release and --strict saves you the issue. If you do not have a plugin yet, start with what one actually is; if you have one and what you need is to hand it out, the marketplace is the next step.

Official docs: Plugins reference

Requirements

Claude Code v2.1.233 or later to validate manifest-less directories. Everything above was run on v2.1.263.