review-plugin-submission

name	review-plugin-submission
description	Audit a Claude Code plugin for marketplace readiness. Use when validating the manifest, component placement, frontmatter, discovery paths, and submission quality before publishing.

Review plugin submission

Trigger

A plugin is implemented and needs a final quality check before submission or release.

Workflow

1. Verify manifest validity:
   • .claude-plugin/plugin.json is optional — a plugin with no manifest is still valid. If one exists, it must parse as JSON.
   • name is valid lowercase kebab-case. It is the only required field.
   • Metadata fields are coherent: displayName, version, description, author, homepage, repository, license, keywords, defaultEnabled.
   • Non-spec keys sit under the free-form metadata object, not at the top level. Unrecognized top-level fields are ignored at load and reported as warnings by claude plugin validate — --strict turns them into errors.
   • If userConfig is present, each entry has type, title, and description; optional keys are sensitive, required, default, multiple, min, max. Secrets are marked sensitive: true and referenced as ${user_config.KEY}, never hardcoded.
2. Verify component placement — components live at the plugin root, never inside .claude-plugin/:
   • Skills in skills/<name>/SKILL.md
   • Agents in agents/*.md
   • Commands in commands/*.md
   • Hooks in hooks/hooks.json
   • MCP servers in .mcp.json; LSP servers in .lsp.json
   • Executables in bin/, plus workflows/, output-styles/, settings.json as applicable
   • Discovery is automatic. Manifest component keys (skills, agents, hooks, mcpServers, …) should appear only where a component sits at a non-default path — and every such path must exist.
   • Flag any plugin-level CLAUDE.md that is being treated as context: Claude Code does not load it.
3. Verify component metadata:
   • Skills: frontmatter is optional but description is expected. Field names are limited to name, description, when_to_use, argument-hint, arguments, disable-model-invocation, user-invocable, allowed-tools, disallowed-tools, model, effort, context, agent, background, hooks, paths, shell, metadata, license, compatibility.
   • Skill name must be kebab-case. In a plugin skill it becomes the last segment of /<plugin>:<name>, so a name with spaces produces a broken command.
   • Agents: name and description present. Frontmatter limited to name, description, model, effort, maxTurns, tools, disallowedTools, skills, memory, background, isolation: worktree. Reject hooks, mcpServers, permissionMode (unsupported in plugin agents) and readonly (does not exist — the equivalent is disallowedTools: Write, Edit, NotebookEdit). model is opus, sonnet, haiku, or inherit.
   • Commands: name and description present.
   • Hooks: hooks/hooks.json uses the double-nested shape { "hooks": { "<Event>": [ { "hooks": [ { "type": "command", "command": "…" } ] } ] } } with PascalCase event names.
4. Verify path hygiene:
   • All manifest paths are relative and stay inside the plugin directory — no absolute paths, no .. traversal.
   • Runtime references use ${CLAUDE_PLUGIN_ROOT}, ${CLAUDE_PLUGIN_DATA}, ${CLAUDE_PROJECT_DIR}, or ${CLAUDE_SKILL_DIR} rather than hardcoded locations.
5. Verify repository integration:
   • For marketplace repos, .claude-plugin/marketplace.json has name, owner, and plugins[], and this plugin has an entry.
   • The entry has name and source; a relative source starts with ./. Optional entry keys: category, tags, description, strict, defaultEnabled.
   • Plugin names are unique within the marketplace and source resolves to a real directory.
6. Verify documentation quality:
   • README.md states purpose, installation (/plugin install <name>@<marketplace>), and component coverage.
   • The component tables match what actually ships — no entries for components that do not exist.
   • Any optional logo path is valid and repository-hosted.
7. Run the validator and report the real output:
   • claude plugin validate <plugin-dir>
   • claude plugin validate <plugin-dir> --strict — warnings become errors here, so this is the submission gate.
   • Load the plugin locally (/plugin marketplace add <path>, /plugin install <name>@<marketplace>, /reload-plugins) to confirm the components appear.

Checklist

• Manifest, if present, parses as valid JSON and name is kebab-case
• No components hidden inside .claude-plugin/
• Manifest component keys used only for non-default paths, and all declared paths exist
• No unrecognized top-level manifest fields; extras live under metadata
• All paths relative, no traversal, no broken file references
• Skill frontmatter name values are kebab-case
• No unsupported agent frontmatter (hooks, mcpServers, permissionMode, readonly)
• Plugin scope is clear and focused
• Marketplace registration complete, with source starting ./ (if multi-plugin repo)
• claude plugin validate --strict exits clean

Output

• Pass/fail report by section
• Verbatim claude plugin validate --strict output
• Prioritized fix list
• Final submission recommendation