How to Validate Plugin Manifests Before Distribution Using `claude plugin validate`

Run claude plugin validate . from your repository root to check schema conformity, file existence, hook integrity, and semantic versioning before publishing Claude-compatible plugins.

The ayghri/i-have-adhd repository demonstrates best practices for building Claude-compatible plugins through its .claude-plugin directory structure. Validating plugin manifests before distribution prevents broken deployments and ensures marketplace compatibility. The built-in claude plugin validate command provides a lightweight, CI-friendly solution for automated checks.

Running the Validation Command

The claude plugin validate command is designed for simplicity and integration. When executed from the repository root, it automatically discovers and validates manifest files in the .claude-plugin directory.

Basic Validation

# Validate from repository root (most common)

claude plugin validate .

CI-Ready Validation with Exit Codes

# Fail fast for CI pipelines — non-zero exit on validation failure

claude plugin validate . && echo "✅ Manifest is valid"

Multi-Plugin Repository Validation

# Target a specific plugin subdirectory

claude plugin validate plugins/my-awesome-plugin

What the Validator Checks

According to the ayghri/i-have-adhd source structure, the validation command performs five critical checks:

• Schema conformity — Verifies required fields in .claude-plugin/plugin.json including name, version, description, entry, and hooks
• File existence — Confirms all referenced paths (entry scripts, hook definitions) exist in the repository
• Hook integrity — Cross-checks each hook in hooks/hooks.json against declared plugin capabilities
• Circular-dependency detection — Prevents plugin reference loops that could break runtime execution
• Semantic versioning — Parses and validates that version strings follow semver rules

Validation failures produce detailed error reports with specific file paths and remediation guidance.

Key Manifest Files

File	Purpose
.claude-plugin/plugin.json	Core descriptor with name, version, entry point, and hooks
.claude-plugin/marketplace.json	Distribution metadata including tags, category, and author
hooks/hooks.json	Global hook definitions referenced by the plugin

Integrating with CI Pipelines

The validator's lightweight architecture makes it ideal for automated testing. A typical GitHub Actions step validates manifests on every pull request:

- name: Validate Claude plugin
  run: npx claude plugin validate .

The command's non-zero exit status on failure ensures CI pipelines halt before broken plugins reach production.

Summary

• Execute claude plugin validate . from the repository root to validate manifests in .claude-plugin/
• The command checks schema, file existence, hook integrity, dependencies, and semver compliance
• Validation supports both single-plugin repositories and multi-plugin monorepos via path arguments
• Exit codes enable seamless CI/CD integration for pre-distribution quality gates

Frequently Asked Questions

What happens if claude plugin validate finds errors?

The CLI prints a detailed error report specifying which check failed, the affected file path, and the required fix. The process exits with a non-zero status, blocking CI progression until issues are resolved.

Can I validate multiple plugins at once?

Yes. Run claude plugin validate . from a parent directory containing multiple plugin subdirectories, or validate individually with claude plugin validate plugins/plugin-name for targeted checks.

Does the validator require network access?

No. The claude plugin validate command performs local file system checks against the schema definitions bundled with the CLI tooling, making it suitable for air-gapped CI environments.

Which manifest fields are strictly required?

Per the schema validation in ayghri/i-have-adhd, every plugin manifest must include name, version, description, entry, and hooks fields in .claude-plugin/plugin.json to pass validation.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}