Plugin Validator

Overview

Validates Claude Code plugin structure, JSON schemas, frontmatter format, security compliance, and marketplace catalog consistency. Runs the same checks as the CI pipeline to catch issues before committing.

Prerequisites

• Read access to the target plugin directory and repository-level .claude-plugin/marketplace.extended.json
• jq installed for JSON validation (jq empty )
• grep and find available on PATH for pattern scanning
• ./scripts/validate-all-plugins.sh available at the repository root

Instructions

1. Identify the target plugin path from context or user request. Default to the current working directory if the path contains a .claude-plugin/ subdirectory.
2. Validate required files exist (see ${CLAUDESKILLDIR}/references/validation-checks.md):

• .claude-plugin/plugin.json present and valid JSON.
• README.md present and non-empty.
• LICENSE file present.
• At least one component directory exists (commands/, agents/, skills/, hooks/, or mcp/).

1. Validate plugin.json schema:

• Confirm all required fields: name (kebab-case), version (semver x.y.z), description, author.name, author.email, license, keywords (array, minimum 2).
• Reject any fields not in the allowed set (name, version, description, author, repository, homepage, license, keywords).

1. Validate frontmatter in all component files:

• Commands (commands/*.md): require name, description, model (one of sonnet, opus, haiku).
• Agents (agents/*.md): require name, description, model.
• Skills (skills/*/SKILL.md): require name, description; allowed-tools optional but validated against the allowed tools list if present.

1. Validate directory structure matches the expected hierarchy (see ${CLAUDESKILLDIR}/references/validation-checks.md for the complete structure diagram).
2. Check script permissions: find all .sh files and verify they have execute permission. Report any that lack it with a fix command.
3. Run security scans: search for hardcoded secrets, AWS keys, private keys, dangerous commands, and suspicious URLs.
4. Validate marketplace compliance:

• Confirm the plugin has an entry in marketplace.extended.json.
• Verify version, name, category, and source path match between plugin.json and the catalog entry.
• Check for duplicate plugin names.

1. Validate README content: confirm it contains installation, usage, and description sections.
2. Check hook path variables: verify hooks use ${CLAUDEPLUGINROOT} instead of hardcoded absolute paths (/home/, /Users/).
3. Compile results into a validation report following the format in ${CLAUDESKILLDIR}/references/validation-report-format.md.

Output

A structured validation report containing:

• Total checks passed and failed (e.g., "8/10 PASSED")
• Per-check results with pass/fail status
• For each failure: the specific issue, file location, and a ready-to-run fix command
• Warnings for non-critical issues (e.g., missing optional README sections)
• Overall verdict: PASSED or FAILED with critical issue count

Error Handling