claude-code - 💡(How to fix) Fix Plugin marketplace validation errors could be more descriptive (stale docs, reserved names, wrong file location) [1 comments, 2 participants]

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`.

2. `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.

3. `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).

4. `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.