Plugin marketplace validation errors could be more descriptive (stale docs, reserved names, wrong file location)

Problem

Setting up a new plugin marketplace is a frustrating back-and-forth because each validation failure blocks on an error message that names the violation but not the rule. I had to run \/plugin marketplace add\ + \/plugin install\ seven times across two PRs before the marketplace worked, each time hitting a new error that required reading docs to decode:

1. \Error: Marketplace file not found at /home/.../temp_xxx/.claude-plugin/marketplace.json\ — didn't say the canonical path is \.claude-plugin/marketplace.json\ (the repo had \marketplace.json\ at root). Would be great if the error included \expected path: .claude-plugin/marketplace.json relative to repo root\.

1. \Error: Failed to parse marketplace file: Invalid schema: name: Marketplace name impersonates an official Anthropic/Claude marketplace\ — didn't list which names are reserved. Is the set of reserved names documented anywhere? I'd expect the error to include the reserved prefix/suffix pattern (e.g. "names starting with 'claude-' or 'anthropic-' are reserved") and link to a docs page.

1. \Invalid schema: name: Invalid input: expected object, received string\ — this one points at a specific field but the error could include a URL to the schema docs + a minimal example of the correct shape. Currently I have to guess what \"object\" shape is expected (it turned out to be \{\"name\": \"...\", \"url\": \"...\"}\ for the \owner\ field, not just any object).

1. \Plugin has an invalid manifest file ... author: Invalid input: expected object, received string\ — same pattern. Plus the error doesn't indicate that \requirements\ isn't a recognized field (I added it speculatively, and Claude Code silently accepted it while rejecting author — schema strictness should be consistent).

Concrete suggestions

1. Include expected path in "not found" errors

\\\
Error: Marketplace file not found at /home/.../temp_xxx/.claude-plugin/marketplace.json.
This path is required. If your file is elsewhere, move it to .claude-plugin/marketplace.json.
Docs: https://code.claude.com/docs/en/plugin-marketplaces
\\\

2. Reserved names — list the pattern + the official marketplaces

\\\
Error: Marketplace name 'claude-plugins' is reserved.
Names matching the pattern ^(claude|anthropic)-? are reserved for official Anthropic
marketplaces. Pick a name that doesn't start with claude- or anthropic-.
Your repo description suggests 'standra-plugins' would work.
\\\

(The third line is a stretch — AI-style suggestion — but the first two are essential.)

3. Schema errors — embed the expected shape + doc URL

\\\`
Error: Plugin has invalid manifest at .claude-plugin/plugin.json
Validation errors:

• author: expected object, received string

Expected shape: {"name": "string", "email": "string?", "url": "string?"}
You provided: "zenprocess/standra"
See: https://code.claude.com/docs/en/plugins-reference#metadata-fields
\\\`

4. Strict schema mode — reject unrecognized fields explicitly

Right now, \requirements\ (which I added but isn't in the schema) was silently ignored. If the validator rejected unknown fields with a "did you mean..." hint, I would have caught it on the first pass:
\\\
Error: Plugin manifest contains unrecognized field 'requirements'.
Valid fields are: name, version, description, author, homepage, repository, license,
keywords, skills, commands, agents, hooks, mcpServers, outputStyles, lspServers,
userConfig, channels.
If you meant to record runtime requirements, add them to the 'description' field
or the plugin's README.
\\\

Reproduction / context

Setting up a private zenprocess/claude-plugins marketplace for zendev-lite's ecosystem enrollment. Hit every error above, each blocking a \/plugin install hub-participant@standra-plugins\ attempt. Required 2 upstream PRs against the marketplace repo to finally land (schema fixes in .claude-plugin/marketplace.json and plugins/hub-participant/.claude-plugin/plugin.json). The same errors would have been fixable in one PR if the messages pointed at the schema.

The docs at https://code.claude.com/docs/en/plugins-reference and https://code.claude.com/docs/en/plugin-marketplaces are good and complete — the gap is that \/plugin\ errors don't link to them when they fire.

Not blocking, just painful

Marketplace setup is a one-time operation per project, so the pain is amortized. But every plugin author goes through this cycle, and the back-and-forth adds friction that could be eliminated with slightly richer error text.

Thanks for making plugins easy to distribute once you get past the initial gate — this issue is specifically about smoothing that initial gate.

🤖 Filed after a multi-hour debugging session setting up a private marketplace for a Claude Code ecosystem.