Claude插件验证工具

Claude Plugins Validation (CPV)

Check if your Claude Code plugin is correct, secure, and ready to publish -- without spending a single token.

CPV is a suite of Python scripts that analyze Claude Code plugins locally on your machine. Every check runs offline, produces instant results, and costs nothing. No AI calls, no API keys, no cloud services needed.

There are two ways to use CPV. Pick the one that fits your workflow:

Using CPV from inside Claude Code? You don't need to memorize anything. Tell any Claude:

"read the CPV skills menu and use whatever you need"

and it routes your request — validate, security-scan, fix, optimize cache, create, publish — to the right tool automatically. Or run /cpv-main-menu for an interactive menu. Full capability list: Features at a glance.

Table of Contents

• Features at a glance
• What Does CPV Check?
  • Claude Code Documentation
• Usage
• Part 1: Standalone Validation (via uvx)
  • Getting Started
  • Available Scripts
  • Options
  • Reading the Results
• Part 2: Claude Code Plugin
  • Installation
  • AI Agents — The Main Interface
  • Menu Architecture
  • Slash Commands
• For Developers
• Requirements
• Troubleshooting

Features at a glance

Every CPV capability, with its route in three contexts: a human-facing slash command, the agent that owns it, and the standalone uvx alias. Throughout this table, cpv is the standalone alias = uvx --from git+https://github.com/Emasoft/claude-plugins-validation --with pyyaml cpv-remote-validate (make it a shell alias once and just type cpv plugin /path).

Two menus, two audiences. Humans run /cpv-main-menu — a real interactive numbered menu (zero token cost). Agents (and any routing Claude) read cpv-the-skills-menu instead — a plain à-la-carte catalog they pick from. The universal, memorize-nothing instruction is "read the CPV skills menu and use whatever you need".

What Does CPV Check?

CPV ships 25 on-disk validate_*.py scripts covering 190+ rules across every part of a Claude Code plugin and end-user .claude/ configuration. The plugin command orchestrates 17 of these as sub-validators (the marketplace / scope / settings scripts run from their own commands):

Empirical Plugin-Loading Bugs CPV Catches

Through extensive empirical testing of Claude Code's plugin loader (April 2026), CPV identified five silent-failure modes that the official docs hide and that CC's own claude plugin validate does NOT detect. CPV catches all five:

1. agents field with folder paths — CC rejects with cryptic agents: Invalid input. If validate is skipped, agents are silently dropped at runtime. CPV emits MAJOR with helpful fix recipe (.md file paths only). The official docs' own complete-schema example showing "./custom/agents/" is incorrect.
2. hooks: "./hooks/hooks.json" cascade — pointing the override at the auto-discovered default file passes validation silently, but at runtime CC emits Duplicate hooks file detected AND disables the plugin's MCP servers with error type: hook-load-failed. CPV emits MAJOR.
3. MCP cross-source server-name collision — same server name in both .mcp.json and inline plugin.json:mcpServers causes silent inline-wins shadowing; the .mcp.json declaration is dropped without warning. CPV emits MAJOR per duplicate.
4. LSP cross-source server-name collision — same silent-shadow risk for LSP servers. CPV emits MAJOR per duplicate.
5. mcpServers: "./.mcp.json" redundancy — points the override at the auto-discovered default file. Harmless single load (no cascade like hooks) but redundant and confusing. CPV emits MINOR nudge.

All five rules are documented with empirical evidence in skills/cpv-fix-validation/references/empirical-loading-bugs.md (13 test plugin scenarios, debug-log excerpts, runtime probes).

CC v2.1.207 — plugin options (v2.158.0+)

Claude Code v2.1.207 shipped a shell-injection fix that silently breaks two shapes plugins were previously encouraged to use. CPV catches both.

[RC-USERCFG-SHELL-INJECT] — CRITICAL (blocking). ${user_config.*} interpolated into a shell-form command is now rejected by Claude Code on three surfaces: hooks, monitors, and MCP headersHelper. A shell-form command is a single string handed to a shell, so an option value carrying shell metacharacters — a command separator followed by a destructive command, a command substitution that downloads and runs a remote script, backticks — escapes its argument slot and executes as code. A plugin shipping this shape is broken at runtime, not merely unsafe — hence CRITICAL rather than a warning.

Exec form stays legal and is never flagged. The same token inside an args array is spawned with an argv vector that no shell parses — it is the fix the spec prescribes, and flagging it would condemn the remedy:

// REJECTED by CC ≥ 2.1.207 — the value is spliced into a shell string
{ "type": "command", "command": "./scripts/post.sh --token ${user_config.api_token}" }

// LEGAL — argv vector, no shell involved
{ "type": "command", "command": "./scripts/post.sh", "args": ["--token", "${user_config.api_token}"] }

Per-surface remediation, straight from the changelog:

[RC-USERCFG-PROJECT-SETTINGS] — WARNING (advisory, does not block). Plugin option values are no longer read from project-level .claude/settings.json / .claude/settings.local.json — only user settings, --settings, and managed settings are honored. A pluginConfigs block left in a project settings file is now silently ignored: the plugin falls back to its defaults with no error. Move those values to ~/.claude/settings.json, pass them via --settings, or ship them as managed settings.

Cross-marketplace dependency allowlist (TRDD-20108ab7)

When plugin.json declares a dependency with dependencies[i].marketplace pointing at a marketplace OTHER than the one hosting the declaring plugin, Claude Code blocks the install at runtime with a cross-marketplace error UNLESS the hosting marketplace.json::allowCrossMarketplaceDependenciesOn array lists that target marketplace by name. CPV catches this MAJOR ahead of install time, with on-disk auto-discovery of the hosting marketplace.json from three deployment shapes:

• Layout C (marketplace-in-plugin) — plugin's own .claude-plugin/marketplace.json
• Layout B (nested monorepo) — parent .claude-plugin/marketplace.json (walked up to 3 levels)
• Cache layout — ~/.claude/plugins/cache/<marketplace>/<plugin>/ (immediate parent's marketplace.json)

When auto-discovery cannot find a hosting marketplace.json (standalone plugin clones, fresh PRs in CI), CPV emits INFO instead of MAJOR. Pass validate_plugin --marketplace-context PATH to force a specific marketplace.json. Spec: plugin-dependencies.md:54-79.

All in-process checks run as pure Python — no API calls, no tokens consumed, no data sent anywhere.

External Security Scanners (always-run, programmatic-only)

validate_security.py orchestrates five always-run external scanners alongside its in-process rule packs. Each is invoked unconditionally on every scan and self-skips with an INFO advisory when its source binary cannot be resolved on PATH or installed from its source URL. There is no opt-out flag — preventing a caller from accidentally silencing coverage. The enable_* keyword arguments on validate_security() survive only as test-isolation knobs.

A sixth scanner — Snyk Agent Scan — is opt-in and behaves differently from the five (it is cloud-backed and token-gated); it runs only when SNYK_TOKEN is exported. See Opt-in scanner: Snyk Agent Scan below.

Opt-in scanner — Snyk Agent Scan (SNYK_TOKEN)

Alongside the five always-run scanners, validate_security.py runs one opt-in, cloud-backed scanner — snyk/agent-scan (PyPI snyk-agent-scan, Apache-2.0). It adds an LLM-based second opinion CPV's regex engines cannot give: prompt injection, tool-poisoning, malware payloads, and untrusted-content / credential-handling risks in a plugin's instruction surfaces.

It is not always-run and must be explicitly enabled, for two reasons: it hard-requires a Snyk API token (a free account), and it is cloud-backed — scanned content is sent to Snyk for analysis. CPV must stay usable offline and must never ship a plugin's private source to a third party by default, so the scan runs only when you export SNYK_TOKEN. Absent the token it is skipped with a visible WARNING (naming the variable and the sign-up page) — never folded into the pass count, because a scan that never ran must never look like a scan that passed.

Enable it:

1. Register a free account at snyk.io.
2. Copy your API token from app.snyk.io/account (Auth Token → KEY → click to show).
3. Export it in your shell — add it to ~/.zshrc / ~/.bashrc (or your secret manager) to persist across sessions:
   复制

   export SNYK_TOKEN="<your-token>"
   

4. Re-run any security scan (cpv security <path>, /cpv-batch-security-audit, cpv-doctor). The step now shows RAN instead of SKIPPED.

cpv-doctor --install-scanners warms the snyk-agent-scan launcher (uv tool install snyk-agent-scan, opt out with CPV_NO_SNYK_INSTALL=1), but a warm launcher without a token still does not run — the token, not the binary, is the gate.

v2.48 — gitleaks removed. trufflehog (~700 detectors with --concurrency parallel-scan support) provides superset coverage. gitleaks shipped ~150 detectors and crashed under reliable parallel scanning, so it has been retired from the external-scanner roster.

v2.48 — cpv-doctor --install-scanners. A new batch installer fetches every scanner CPV uses with one command (silent and idempotent). It also installs fclones (pkolaczk/fclones), a Rust-based duplicate-file finder used as the first step of every CPV scan to skip duplicate files (cross-plugin shared READMEs, vendored libs, identical SKILL.md templates). Per-platform cascade: macOS = brew install fclones, Linux = snap install fclones then cargo install fclones, Windows = GitHub-release download then cargo install fclones. Per-tool opt-outs: CPV_NO_<TOOL>_INSTALL=1 (e.g. CPV_NO_FCLONES_INSTALL=1).

v2.48 — cpv-doctor --prune-old-versions. Frees disk space accumulated when claude plugin update doesn't remove old versions. Two-stage UX: --prune-dry-run previews; --prune-old-versions actually deletes. Always keeps the active version (whichever Claude Code references in enabledPlugins). --prune-keep N to retain N newest per plugin (default 1).

v2.48 — URL / archive ingestion + loose mode. The positional argument now accepts:

• GitHub URLs: https://github.com/owner/repo or shorthand github:owner/repo — cloned with gh repo clone --depth 1 to a tmpdir, scanned, then cleaned up automatically.
• Local archives: *.zip, *.tar.gz, *.tgz, *.tar.bz2, *.tar.xz, *.tar — extracted to a tmpdir (with path-traversal protection), scanned, cleaned up.
• Loose mode for flat skill packs: --loose (alias for --bare-folder) bypasses the .claude-plugin/ precondition. CPV auto-detects flat packs (5+ *.md files, no plugin.json, no canonical skills/<name>/SKILL.md layout) and prints a HINT recommending --loose in the error message.

v2.48 — Marketplace tree-scan-once with dedup. --marketplace <spec> now stages every plugin under one tmpdir, runs fclones ONCE on the entire corpus, deletes duplicate hardlinks (cache untouched — hardlinks share inodes safely), then scans each plugin's deduped staging. Findings on canonical files automatically propagate to peer plugins that originally contained a copy of the same content (no coverage hole from dedup). Real-world: ai-maestro-plugins (10 plugins) sees ~1,849 duplicate files / ~21 MB saved per scan run.

v2.48 — cpv-main-menu. Single interactive entry-point routing through every CPV command via nested numbered sub-menus. Every menu/sub-menu includes a Cancel/Exit option. Use this when you can't remember which slash command to invoke directly. Since v2.90.0 the menus are rendered post-turn by claude-menu-system's Stop hook — not by AskUserQuestion — so a menu costs zero tokens no matter how large it is; see Menu Architecture.

v2.101.0 — Batch / fleet skills + scope-aware doctor. Ten new user-invocable slash commands (TRDD-3dcbb37c + TRDD-a175f78d) for fleet-scale operations across many plugins in parallel. The main session fans out N parallel subagent dispatches from ONE message (the only place the Agent tool can parallelise per Anthropic spec). Universal input grammar — accepts single plugin path/URL, marketplace path/URL, comma-separated list, an @listfile prefix pointing to a text file of one input per line, single skill folder, skill pack, or mixed marketplace.json entries (plugins + skills + skill-packs all expandable). Reference-counted clone cleanup; bounded scan for repos with 100k+ skills.

The same-turn variants verify suspect findings via llm-externalizer with file-range syntax (<file>:<start>-<end>, ≤200 LOC per call) so false positives are caught BEFORE a fix is applied. Reached interactively from /cpv-main-menu row 1 → row 7 (Batch / fleet) which exposes all ten via a single Level-2 sub-menu.

v2.101.0 — Phase 6 FP-iteration on Emasoft/emasoft-plugins. Two systematic FP classes eliminated. (a) Python subprocess.run / Popen / call / check_call / check_output WITHOUT shell=True is now classified safe_literal by _skillaudit_python_context — Python guarantees no shell interpretation. Only shell=True with non-literal args stays suspect. (b) Markdown defensive-documentation heuristic: when a prompt-injection / intent-class rule fires INSIDE a double-quoted string AND surrounding ±5 lines contain defensive vocabulary (UNTRUSTED / trust boundary / treat as data / etc.), the finding is demoted to NIT — the agent is being WARNED about a phrase, not the phrase being injected at it. Iron rule preserved throughout: rules are NEVER deleted; only classifier precision improves.

Every external scanner's findings are routed through the same self-scan filter chain CPV applies to its own rules (cpv_self_scan_skip → vendored-deps → dev-scratch → test-files → FP-corpus markdown → per-line catalog/docstring/comment pattern-source predicate). This guarantees that scanning CPV with CPV — or scanning any plugin that ships its own rule catalogs — never surfaces the catalog source as a finding. The aggregator then groups all findings by (level, rule_id) so each vulnerability TYPE shows its full explanation exactly once, followed by an occurrence count and a capped file:line list — bounded report size, no findings ever silently dropped.

Claude Code Documentation

CPV validates plugins against the official Claude Code specification. If you are building a plugin, these are the key references:

• Discover plugins -- finding and installing plugins
• Plugins reference -- plugin.json schema, CLI commands, component specs
• CLI commands reference -- install, uninstall, enable, disable, update
• Skills reference -- SKILL.md frontmatter, substitutions, dynamic context
• Hooks reference -- hook events, matchers, hook types (CPV models 31 events and 5 types)
• Claude Code release notes -- latest changes and plugin updates

Usage

There are two ways to use CPV: via uvx (no install) or as a Claude Code plugin. See Part 1 for terminal/CI use and Part 2 for the interactive plugin with agents and menus.

Part 1: Standalone Validation (via uvx)

No installation needed. Just run the command and point it at your plugin folder.

Getting Started

You need uv installed. Then:

## Validate a plugin (runs all 17 sub-validators + linting)
uvx --from git+https://github.com/Emasoft/claude-plugins-validation --with pyyaml \
    cpv-remote-validate validate_plugin /path/to/your-plugin

That's it. uvx downloads CPV temporarily into an isolated environment, runs the validation with full environment isolation (the target plugin's local configs can't interfere), and shows results. Nothing is installed permanently.

The --with pyyaml flag ensures the YAML parser dependency is available.

Faster path — install from PyPI (#137). The git+https://… form above always works, but on a cold uvx cache it builds CPV from source (the slow first run). Once CPV is published to PyPI, drop the git+… source for a prebuilt wheel — no source build, and pyyaml ships in the wheel so you can omit --with pyyaml:

复制

uvx --from claude-plugins-validation cpv-remote-validate plugin /path/to/your-plugin

Maintainers: the one-time PyPI Trusted-Publishing setup is documented in .github/workflows/publish-pypi.yml; after it, every GitHub Release auto-publishes the wheel (OIDC, no stored token).

The Remote Launcher

cpv-remote-validate is the recommended way to validate external plugins. It wraps any CPV script with environment isolation so that the target plugin's local files (pyproject.toml, .mypy.ini, stale module copies) cannot interfere with validation.

## Full plugin validation (short alias)
uvx --from git+https://github.com/Emasoft/claude-plugins-validation --with pyyaml \
    cpv-remote-validate plugin /path/to/plugin

## Save a report to a file
uvx --from git+https://github.com/Emasoft/claude-plugins-validation --with pyyaml \
    cpv-remote-validate plugin /path/to/plugin -o report.md

## Validate a single skill with strict mode
uvx --from git+https://github.com/Emasoft/claude-plugins-validation --with pyyaml \
    cpv-remote-validate skill /path/to/skill --strict

## Security scan
uvx --from git+https://github.com/Emasoft/claude-plugins-validation --with pyyaml \
    cpv-remote-validate security /path/to/plugin

## Show help and all available commands
uvx --from git+https://github.com/Emasoft/claude-plugins-validation --with pyyaml \
    cpv-remote-validate --help

## From the CPV plugin cache (inside Claude Code):
python3 "${CLAUDE_PLUGIN_ROOT}/scripts/remote_validation.py" plugin /path/to/plugin

Tip: Create a shell alias to shorten the commands:

复制

alias cpv='uvx --from git+https://github.com/Emasoft/claude-plugins-validation --with pyyaml cpv-remote-validate'

Then just: cpv plugin /path/to/plugin or cpv skill /path/to/skill --strict

Available Scripts

Any of these can be passed as the first argument to cpv-remote-validate. Short aliases and full script names both work.

Standardize: the resolver tag, and why canon configs are merged (v2.158.0+)

The dependency-resolver tag. A version-constrained plugin dependency resolves only against a {plugin-name}--v{version} git tag (double hyphen, CC 2.1.110). Miss it and a dependent install fails with no-matching-tag and the plugin is disabled — a release that looks fine and is silently un-dependable. CPV's generator has always minted this tag, but standardize is profile-aware and deliberately refuses to overwrite an existing publish.py, so every plugin that already had one was being standardized without ever gaining the tag stage. A plain cpv standardize /path --fix now injects only that stage into the existing file, idempotently, so the resolver tag lands in the same atomic push as the release tag — a release can never ship with one ref and not the other. A publish.py too customized to migrate safely is left byte-identical and reported, never half-migrated.

Canon config files are merged, not clobbered. --force-templates used to overwrite a shared-canon config wholesale, silently deleting linter suppressions the plugin's build depended on. It now merges, with a rule per format — and prints exactly what it did either way:

The YAML asymmetry is deliberate. The real-world divergence is not a custom key — it is a custom value inside a key canon also declares (REPOSITORY_CHECKOV_ARGUMENTS extended with an extra skip-check, justified by an eight-line comment). CPV cannot tell "the author customized this" from "this is stale canon", and the outcomes are not symmetric: deleting a load-bearing suppression breaks your build, while missing a canon refresh merely annoys you. Reconcile the reported keys by hand if you wanted canon's value.

Options

These flags work with all validators:

Default output is path-only. Without --json or --report, validate_security.py auto-saves the aggregated report to $CLAUDE_PROJECT_DIR/reports/security/<timestamp>-<plugin>.md (or $TMPDIR/reports/security/... when CLAUDE_PROJECT_DIR is unset, e.g. on a remote uvx invocation) and prints only the compact summary (counts table + verdict + plugin path + report path) to stdout. This guarantees that an agent invoking the validator gets a tiny, predictable stdout payload that never floods its context window.

External scanners always run. There are no --no-tirith / --no-trufflehog / --no-semgrep opt-out flags. Each external scanner self-skips with an INFO advisory if its source binary cannot be resolved on PATH or installed from its source URL. Set CPV_NO_TIRITH_INSTALL=1 to disable tirith's auto-install fallback in CI sandboxes that block container pulls; set CPV_CISCO_SCAN_TIMEOUT_S=<seconds> to override the 600s default for very large trees. The one exception to "always run" is the opt-in Snyk Agent Scan, which runs only when SNYK_TOKEN is exported. See External Security Scanners above for the full inventory.

Reading the Results

Severity Levels

Exit Codes

For use in scripts and CI/CD pipelines:

Part 2: Claude Code Plugin

For Claude Code users. Install CPV once to get slash commands, AI agents, and plugin management tools directly inside Claude Code.

Installation

For the full CLI commands reference, see the official Anthropic docs.

Dependencies

CPV depends on claude-menu-system >= 0.1.5 (same emasoft-plugins marketplace). It provides the post-turn Stop/SubagentStop hook that renders every CPV menu at zero token cost (see Menu Architecture below). claude plugin install auto-resolves this dependency — no manual step needed. If CMS is missing at runtime, CPV's print_menu helper fails fast with an actionable install hint (fail-fast, no silent fallback).

## Add the Emasoft marketplace (first time only)
claude plugin marketplace add emasoft-plugins --url https://github.com/Emasoft/emasoft-plugins

## Install CPV (--scope user = available in all your projects, recommended)
claude plugin install claude-plugins-validation@emasoft-plugins --scope user

## OR install for this project only (--scope local, gitignored)
claude plugin install claude-plugins-validation@emasoft-plugins --scope local

## IMPORTANT: Restart Claude Code after installing, or run /reload-plugins

Managing the Plugin

## Update to the latest version
claude plugin update claude-plugins-validation@emasoft-plugins --scope user

## Disable without removing
claude plugin disable claude-plugins-validation@emasoft-plugins --scope user

## Re-enable
claude plugin enable claude-plugins-validation@emasoft-plugins --scope user

## Uninstall completely
claude plugin uninstall claude-plugins-validation@emasoft-plugins --scope user

## Uninstall but keep persistent data
claude plugin uninstall claude-plugins-validation@emasoft-plugins --scope user --keep-data

Replace --scope user with --scope local or --scope project depending on where you installed it:

For development: claude --plugin-dir ./claude-plugins-validation

AI Agents — The Main Interface

When used as a Claude Code plugin, agents are the primary way to interact with CPV. Each agent is a specialized AI assistant that knows which scripts to run, which skills to consult, and how to guide you through the process. Just tell Claude what you need and the right agent takes over.

This table lists the primary user-facing agents; CPV ships 14 in total (the rest — cpv-cache-optimizer-agent, cpv-doctor-agent, cpv-spark-agent, cpv-agent — are dispatched for you by the menu or by other agents). You never need to remember command names: run /cpv-main-menu for an interactive menu, or just tell any Claude what you need and the right agent takes over and guides you with plain-text questions.

Separation of Concerns: Plugins vs. Marketplaces

CPV treats plugins and marketplaces as two distinct concerns with dedicated validators, fix agents, and error indexes. This avoids the kitchen-sink fixer problem where one agent tries to reason about both an individual plugin's plugin.json and a marketplace's marketplace.json + release pipeline at the same time.

Mechanical fixes vs. architectural migrations. The cpv-fix-validation and cpv-fix-marketplace-validation skills do mechanical per-error remediation — one rule, one fix, minimal user input. The separate cpv-migrate-marketplace-architecture skill (loaded by cpv-marketplace-fixer-agent) does interactive architectural conversion with extensive AskUserQuestion prompts: it walks you through converting a Layout A hub-and-spoke marketplace into a Layout B nested single-repo marketplace or vice versa, including publish pipeline, CI, and CHANGELOG restructuring.

Supported Marketplace Layouts

CPV validates and supports three marketplace layouts — all three are first-class, and cpv-marketplace-fixer-agent converts between them:

Full layout specifications and decision criteria: skills/cpv-create-plugin/references/marketplace-layouts.md.

Script Validation vs. Semantic Validation

CPV has two validation layers:

The semantic validator always warns about the cost and asks for confirmation before running. In most cases, script validation is all you need.

Conditional Pillar — Channel MCP Server Source-Code Security

The semantic validator (reached via /cpv-main-menu → 4 Diagnose → semantic) automatically activates the Channel Source Security pillar when the target plugin's plugin.json declares a non-empty channels array (Claude Code v2.1.80+ research-preview channels). The pillar reads the MCP server entry-point source (TypeScript / JavaScript / Python) and verifies the spec-mandated sender-ID gating per channels-reference.md — a check no syntactic validator can perform.

A deterministic prefilter (scripts/cpv_channel_source_predicate.py) bounds the LLM's reading and short-circuits the pillar entirely for plugins that do not ship channels — zero opus tokens spent. See skills/cpv-semantic-validation-skill/references/channel-source-security.md for the four rules (CRITICAL: no sender gating, CRITICAL: permission-relay capability without gating, MAJOR: chat-ID-only gating, PASSED: fully gated).

Menu Architecture

Every CPV menu — the top-level cpv-main-menu, the cpv-doctor first-contact menu, the post-scan menus emitted by the batch skills (cpv-batch-validate, cpv-batch-security-audit, cpv-batch-fix, etc.), the cpv-plugin-creator-agent dev-stripping prompts, the cpv-plugin-diagnoser-agent Phase-9 follow-up, and every sub-menu in between — is rendered by claude-menu-system's Stop / SubagentStop / StopFailure hook. The orchestrator writes a small spec JSON, calls the queue helper, and ENDS ITS TURN; the post-turn hook prints the rendered menu through the hook JSON systemMessage field. Net effect: zero token cost regardless of menu size, menus are shown to the user but NEVER enter the transcript or the prompt cache, no subagent fork, no cache re-prime.

Fixed-key routing contract

CPV menus use two key namespaces that never collide:

• Numbers 1..N — the dynamic list (plugins / paths / URLs / folders to choose from). Always presented in alphabetical order, so "the user typed N" deterministically resolves to the Nth entry of the sorted list. The count varies run-to-run; the agent knows N because it built the list.
• Letters — the fixed actions and reserved navigation. Each letter is permanently bound to one meaning across all menus and states. Reserved navigation keys are global: M = Main menu · B = Back · X = Exit · 0 = Cancel. Per-menu fixed letter→action maps (D = Diagnose, C = Check, A = Ask, …) are immutable at skill-design time and documented in the skill/agent body — they are the single source of truth the orchestrator uses to interpret a typed key.
• Omission, not relettering — when an action does not apply right now, its row is simply not printed (no gap, no placeholder); the letters of surviving actions never shift. renumber: false keeps every key verbatim.
• No read-back of the rendered menu — the orchestrator never inspects what was printed to decide what a key means. The printed menu is presentation only; the typed key is resolved purely against the immutable per-menu map. This is what lets emission be a fire-and-forget post-turn hook with zero context cost.

For the canonical menu spec catalogue (every menu tree CPV emits, in one place), see skills/cpv-main-menu-skill/references/menu-tree.md.

Slash Commands

v2.90.0 — one entry point + v2.101.0 batch family. The canonical entry is still /cpv-main-menu. Type it; pick a number; navigate the entire plugin from a single coherent menu tree. v2.101.0 adds 10 user-invocable batch slash commands (/cpv-batch-*) for fleet-scale operations across many plugins in parallel — these are also reachable from the main menu (row 1 → row 7 "Batch / fleet"), and /cpv-pre-install-scan is the standalone pre-install security gate.

/cpv-main-menu                   # interactive — entry point for everything
/cpv-batch-validate <input>      # fleet validate
/cpv-batch-full-scan-and-fix <input>   # validate + security + cache + fix in one pass
/cpv-pre-install-scan <target>   # security gate before plugin install

Top-level menu (8 verbs the user actually wants to do):

Each category drills into a sub-menu, and each leaf prompts for any required arguments in plain text before dispatching the right work agent or skill. Every menu includes 0 — Cancel and (in sub-menus) 9 — Back.

The 37 individual slash commands from prior versions were consolidated:

• 23 redundant commands were deleted (their content was already in the corresponding skill — cpv-plugin-validation-skill, cpv-fix-validation, cpv-plugin-management, etc.)
• 14 unique commands were converted to user-invocable: false skills (cpv-add-component-to-plugin, cpv-add-dependency, cpv-bump-version, cpv-deterministic-codemod, cpv-scaffold-agent, cpv-scaffold-command, cpv-add-hook, cpv-register-mcp, cpv-scaffold-skill, cpv-link-plugin-marketplace, cpv-pack-components, cpv-refresh-readme, cpv-strip-dev-submodules, cpv-show-version) — invoked by cpv-main-menu behind the scenes, not visible in the slash-command palette

See design/archived/TRDD-c50531c2-menu-unification.md for the full migration rationale.

For CI/CD and scripting, the Python validators are still callable directly (no menu): python3 scripts/validate_plugin.py <path>, python3 scripts/validate_skill.py <path>, etc.

For Developers

Requirements

Required

CPV uses uv to run scripts (uv run), install Python linters (ruff, mypy) when not found locally (uvx), and manage the virtual environment. Python dependencies like pyyaml are installed automatically.

Optional tools (enhance linting)

CPV lints 15 languages. For each one it tries the local install first, then uvx/npx. If no linter is found, CPV reports what's missing and skips that check — it never silently passes a file it could not lint.

Other optional tools:

No API keys, accounts, or cloud services needed for any validation.

Troubleshooting

License

MIT License -- see LICENSE file.

Author

Emasoft (713559+Emasoft@users.noreply.github.com)