claude-plugins-validation

Add a new component (skill / agent / command / hook / mcp) to an existing plugin

Add plugin dependencies to a target plugin (explicit `--add` specs or `--from` copy from another plugin's plugin.json) per plugin-dependencies.md

Bump plugin version + run the full publish pipeline (plugin.json, pyproject.toml, README badge, CHANGELOG, push, release)

Audit AND fix prompt-cache invalidation patterns (CA-01..CA-06) — interactive cache-optimizer agent

Deterministic codemod CLI — bulk-fix backtick-path → markdown-link, add TOC stubs, dedup blank lines, and other mechanical text transforms (issue

Scaffold a new agent in an existing plugin (creates agents/<name>.md with valid frontmatter that passes validate_plugin out of the box).

Scaffold a new slash command in an existing plugin (creates commands/<name>.md with valid frontmatter that passes validate_plugin out of the box).

Add a new hook entry to hooks/hooks.json in an existing plugin (idempotent — skips duplicate entries; cross-platform-aware so the hook command runs identically on Linux/macOS/Windows).

Register a new MCP server in an existing plugin's .mcp.json (stdio default; supports HTTP transport via --http-url; cross-platform command via Python/Node).

Scaffold a new skill in an existing plugin (creates skills/<name>/SKILL.md with valid frontmatter that passes validate_plugin out of the box).

Interactive creation — create plugins, marketplaces, publish to GitHub

Deep diagnostic audit of an existing plugin — pipeline staleness, security (with all 5 external scanners), cross-platform issues, marketplace registration, cached-vs-github sync. Returns a structured report + offers a follow-up menu.

Menu-driven plugin doctor — diagnose a single plugin, current folder, GitHub repo, scope, individual component, or run cache-cleanup / scanner-install / quick-health-check (NEVER auto-scans every cached plugin)

Fix issues from a marketplace validation report file (or migrate marketplace layout)

Fix issues from a PLUGIN validation report file (marketplace reports use /cpv-fix-marketplace-validation)

Link an existing plugin to an existing marketplace (local or GitHub source)

List all locally installed Claude Code plugins with version, status, and components

Single entry point — numbered-table menu of every CPV command/skill/agent (validate, fix, create, manage, GitHub, semantic-grade)

Interactive plugin management — install, update, enable, disable, search, health-check

Normalize an existing marketplace.json — convert source.url → source.repo + detect dead repos

Pack a folder of standalone components (skill/agent/command/hook/mcp/lsp/monitor/output-style) into a new installable plugin

Refresh AUTO-* marker blocks in a plugin's README (auto-detected components table)

Deep AI-driven semantic validation of skills and agents (uses opus)

Project-agnostic branch-protection ruleset installer — works on ANY GitHub repo (not just CPV plugins/marketplaces). Requires explicit --check contexts. Idempotent, auto-merge friendly, preserves existing bot bypass actors.

Create/update the GitHub branch-protection ruleset on a plugin or marketplace repo — enforces CI as a required status check, preserves bypass for trusted bots, idempotent.

Move dev-only artefacts (default: tests/) from a plugin's MAIN repo into a per-plugin git submodule. Implements TRDD-793ac32a — exploits Claude Code's no-recurse-submodules shallow clone (PSS pattern). ONE submodule per plugin by default; add more to cpv.strip.extract[] in plugin.json if your plugin has additional heavy dev folders.

Upgrade an existing plugin to the current CPV pipeline standards (idempotent publish.py, cpv_lint_engine, cross-platform Python + pathlib, sanitized inputs, no bash scripts). Runs the 82-check Pre-completion verification matrix AND a real publish.py + gh run watch on the resulting tag — total time 10-15 minutes.

Audit a plugin or project for prompt-cache invalidation patterns (CA-01..CA-06)

Validate a Claude Code marketplace from a GitHub repository without registering it (optional --audit for security scan)

Validate a Claude Code plugin from a GitHub repository without installing it (optional --audit for security scan)

Validate non-git-tracked (local-scope) Claude Code configuration under a given project path — settings.local.json, CLAUDE.local.md, gitignored agents/skills/commands/rules, and per-project MCP state in ~/.claude.json.

Run full validation on a Claude Code plugin

Validate git-tracked (project-scope) Claude Code configuration under a given project path — settings.json, .mcp.json, agents, skills, commands, rules, and CLAUDE.md that are shared with the team.

Validate extraKnownMarketplaces in a settings.json file

Validate skill directories in a plugin

Audit a plugin or settings.json for OTEL telemetry supply-chain risks (otelHeadersHelper, OTEL_LOG_*, endpoint hijack)

Interactive validation — the validator agent asks what to validate (numbered-table menu, no AskUserQuestion) and runs the right script

Show the CPV management tools version

Self-sufficient cache-optimization WORK agent invoked by cache-optimizer-menu (haiku) after a menu choice is made. Accepts EITHER a pre-existing cache-audit report path OR a plugin/project path via the dispatching menu's `<context>` block. Runs the full validate → fix → re-validate loop on its own. Fixes the six documented prompt-cache invalidation patterns (CA-01..CA-06) AND, when the user asks (mode `audit_then_fix_broader`), performs Phase 4 broader cache-aware improvements to the plugin's skills/agents/commands/CLAUDE.md/rules. Loads cache-validation-skill and the fix-validation skill (cache-fixes references). Per TRDD-82e836dc: this is the OPUS work half of the cache-optimizer-menu / cache-optimizer-agent split. The menu agent (haiku) handles First Contact menu rendering + integer parsing + dispatch; this agent handles the actual cache audit + fix + Phase 4 workflow.

Lightweight haiku menu for /cpv-cache-optimize. Renders the First Contact table (auto-discovered recent cache-audit reports OR a fresh-audit prompt when none exist), parses the user's integer reply, then dispatches to cache-optimizer-agent (opus) only when a leaf is picked. NEVER does fixing itself — pure dispatch. Per TRDD-82e836dc: menu rendering and integer parsing fit the haiku tier; the actual cache-optimization work (CA-01..CA-06 audit, fix loop, Phase 4 broader refactors) stays on opus via the cache-optimizer-agent work agent.

CPV doctor WORK agent invoked by cpv-doctor-menu (haiku) after the user picks a row from the 22-row "Diagnose what?" first-contact menu. Runs the matching diagnostic recipe (single plugin / current folder / all installed / GitHub repo / local marketplace / project-scope / user-scope / single component / cache cleanup / scanner install / quick health check / dependency tree / add dependencies / free-form ask-the-doctor) per the routing in the agent body, then renders the POST-SCAN follow-up menu (rows 1-9) when findings exist — that follow-up menu requires scanner-output context and stays on opus per TRDD-82e836dc §4 B.4. Free-form "Ask the doctor" mode (mode=ask_doctor_freeform) routes the user's typed description to a fresh sub-agent for multi-turn dialog.

Lightweight haiku menu for /cpv-doctor — the FIRST CONTACT entry-point. Renders the 22-row Diagnose-what menu (single plugin, current folder, all installed, GitHub plugin/marketplace, project/local/user scope, individual skill/agent/hook/MCP/monitor/output-style/LSP, cache cleanup, scanner install, quick health check, dependency tree, add dependencies), parses the user's integer reply, then dispatches the cpv-doctor-agent (opus) work agent via the Agent tool with the chosen mode pre-baked into the `<context>` block. Per TRDD-82e836dc §4 B.4: the FIRST CONTACT menu is haiku (pure dispatch); the cpv-doctor-agent work agent keeps its POST-SCAN follow-up menu on opus because the post-scan menu requires scanner-output context.

Single-entry numbered-table menu for every CPV command/skill/agent. Prints Unicode box-drawing tables (Validate, Fix, Create, Manage, Diagnose & Upgrade, GitHub setup, Semantic, Help) with `0 — Cancel / Exit` at every level and `9 — Back` at every sub-menu. Loads cpv-main-menu-skill for the menu tree and per-leaf execution recipes. NEVER uses AskUserQuestion. Runs on Haiku for fast menu rendering (this agent only displays tables and parses integer/letter choices). Heavy lifting is dispatched to specialised Opus agents (plugin-creator, plugin-fixer, plugin-diagnoser, marketplace-fixer, semantic-validator, cache-optimizer-agent) when a leaf is picked.

Lightweight haiku menu for /cpv-fix-marketplace-validation. Renders the First Contact table (auto-discovered recent marketplace validation reports, plus rows for architectural migration / pipeline standardization / manual entry), parses the user's integer reply, then dispatches to marketplace-fixer (opus) only when a leaf is picked. NEVER does fixing itself — pure dispatch. Per TRDD-82e836dc: menu rendering and integer parsing fit the haiku tier; the actual fix work (validate → fix → re-validate loop, mechanical fixes, Layout A/B/C migrations) stays on opus via the marketplace-fixer work agent.

Self-sufficient marketplace fix WORK agent invoked by marketplace-fixer-menu (haiku) after a menu choice is made. Accepts either a validation report OR a marketplace repo path via the dispatching menu's `<context>` block. Runs validate → fix → re-validate in a loop until the marketplace is clean (zero CRITICAL/MAJOR/MINOR/NIT and zero publish-blocking WARNINGs). Also handles architectural migration between Layout A (hub-and-spoke), Layout B (nested monorepo), and Layout C (marketplace-in-plugin self-referential) when the report carries category: architecture signals. Loads fix-marketplace-validation for mechanical fixes, migrate-marketplace-architecture for layout conversions, and setup-marketplace-auto-notification for per-plugin auto-notify chains. Per TRDD-82e836dc: this is the OPUS work half of the marketplace-fixer-menu / marketplace-fixer split. The menu agent (haiku) handles First Contact menu rendering + integer parsing + dispatch; this agent handles the actual fix workflow (mechanical + architectural).

Creates new Claude Code plugin or marketplace repositories from scratch with full CI/CD pipeline, git hooks, and standard file structure. Use when user wants to create a new plugin, scaffold a repo, or set up a new marketplace hub.

Deep diagnostic auditor for Claude Code plugins. Goes beyond validate_plugin (structure-only) by ALSO running all 5 external security scanners, the pipeline-staleness checks, the cross-platform compliance checks, the marketplace-registration probe, and the cached-vs-GitHub sync probe. Returns a structured diagnosis report and prints a follow-up menu so the user can pick: full upgrade / CRITICAL only / register marketplace / sync cache / end.

Lightweight haiku menu for /cpv-fix-validation. Renders the First Contact table (auto-discovered recent validation reports OR a free-text prompt when no reports exist), parses the user's integer reply, then dispatches to plugin-fixer (opus) only when a leaf is picked. NEVER does fixing itself — pure dispatch. Per TRDD-82e836dc: menu rendering and integer parsing are predefined tasks that fit the haiku tier, while the actual fix work (validate → fix → re-validate loop, semantic analysis of findings, applying Edit operations) stays on opus via the plugin-fixer work agent.

Self-sufficient fix WORK agent invoked by plugin-fixer-menu (haiku) after a menu choice is made. Accepts either a validation report OR a plugin path via the dispatching menu's `<context>` block. Runs validate → fix → re-validate in a loop until the plugin is clean (zero CRITICAL/MAJOR/ MINOR/NIT and zero publish-blocking WARNINGs). When handed a plugin path, first applies the Path Resolution Protocol (parent folders, skill folders, .claude configs, etc.) to lock onto the right plugin root, then runs the loop. Loads fix-validation skill for error-to-fix mappings and plugin-validation-skill for structural reference. When invoked for canonical-pipeline migration (via /cpv-upgrade-plugin) the agent ALSO enforces the 82-check Pre-completion verification matrix from references/canonical-pipeline-migration-checklist.md and runs a real publish.py + gh run watch on the resulting tag — see "Pre-completion verification (REQUIRED)" section below. Per TRDD-82e836dc: this is the OPUS work half of the plugin-fixer-menu / plugin-fixer split. The menu agent (haiku) handles First Contact menu rendering + integer parsing + dispatch; this agent handles the actual fix workflow.

Autonomous plugin management agent for installing, validating, and maintaining Claude Code plugins. Use when user asks to: install/uninstall plugins, validate plugin quality, check plugin health, search for plugins by type, manage marketplaces, or perform bulk plugin operations.

Lightweight validation agent that runs scripts and returns compact summaries. Does NOT fix issues or perform semantic analysis — use plugin-fixer and semantic-validator for those. Runs on Haiku (script-launcher tier per TRDD-82e836dc): the entire workflow is Bash + Read + 1-2 lines of summary, no analysis.

Deep AI-driven semantic analysis agent for skill and agent quality. Evaluates description triggering, instruction clarity, example quality, and workflow completeness — things scripts cannot check. Use only via /cpv-semantic-validation (explicit opt-in, uses opus).

Lightweight skill validation agent that runs scripts and returns compact summaries. Does NOT fix issues or perform semantic analysis — use plugin-fixer and semantic-validator for those. Runs on Haiku (script-launcher tier per TRDD-82e836dc): the entire workflow is Bash + Read + 1-2 lines of summary, no analysis.

Validate plugins / projects against Anthropic's prompt-cache invalidation patterns (CA-01..CA-06). Loaded by cache-optimizer-agent. Use when auditing for cache regressions or fixing CA-01..CA-06 findings.

Standard files, CI/CD, hooks, and release pipeline for Emasoft Claude Code plugins. Use when creating or auditing plugin repos. Loaded by plugin-creator, plugin-fixer, and marketplace-fixer agents.

Routes the /cpv-main-menu numbered-table menu. Loaded by cpv-main-menu command. Use when navigating CPV's many commands via a single entry point.

Create Claude Code plugin or marketplace repos with full CI/CD. Use when scaffolding a new plugin or marketplace. Loaded by plugin-creator agent.

Maps marketplace validation errors to fix reference files. Loaded by marketplace-fixer agent. Use when a marketplace validation report has CRITICAL/MAJOR/MINOR/NIT findings from validate_marketplace.py or validate_marketplace_pipeline.py.

Maps CPV validation errors to mechanical per-error fix guides. Use when looking up remediation steps for CRITICAL/MAJOR/MINOR/NIT findings. Architectural migrations are handled by migrate-marketplace-architecture. Loaded by plugin-fixer agent.

Convert a non-CPV marketplace between Layout A (hub-and-spoke), Layout B (nested-with-discipline), and Layout C (marketplace-in-plugin self-referential). Use when migrating marketplace architecture. Loaded by marketplace-fixer agent.

Manage Claude Code plugins: install, validate, audit, enable, disable, search, doctor. Use when managing plugin lifecycle. Loaded by plugin-manager and plugin-creator agents.

Validates Claude Code plugins for structural correctness, quality, and marketplace readiness. Use when validating, fixing, migrating, upgrading, or scaffolding a plugin. Loaded by plugin-validator, plugin-creator, plugin-fixer, plugin-diagnoser. Embeds canonical plugins-reference.md.

Use when publishing a plugin to a GitHub-hosted marketplace. Loaded by plugin-creator agent.

Deep AI semantic validation for skills/agents. Use when checking triggering, clarity, examples. Loaded by semantic-validator agent. 10x token cost.

Use when creating a plugin marketplace or linking plugins to one. Loaded by plugin-creator agent.

Use when configuring a plugin to notify its marketplace after each release so Claude Code can auto-update users. Universal CI recipe for any plugin/marketplace pair. Loaded by plugin-creator and marketplace-fixer agents.

Create and configure Claude Code plugin GitHub repositories with CI/CD, hooks, and marketplace notification. Use when setting up a new plugin repo. Loaded by plugin-creator agent.

Validate skills using 190+ rules from AgentSkills OpenSpec, Nixtla, and Meta-Skill frameworks. Use when validating SKILL.md files or auditing skill quality. Loaded by skill-validation-agent.

Audit and fix plugin/marketplace repos to match CPV standards. Use when standardizing or auditing repo structure. Loaded by plugin-creator agent.