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

> Validate Claude plugin manifests before distribution with claude plugin validate. Ensure schema conformity, file existence, hook integrity, and versioning for successful publishing.

- Repository: [Ayoub Ghriss/i-have-adhd](https://github.com/ayghri/i-have-adhd)
- Tags: how-to-guide
- Published: 2026-08-18

---

**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

```bash

# Validate from repository root (most common)

claude plugin validate .

```

### CI-Ready Validation with Exit Codes

```bash

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

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

```

### Multi-Plugin Repository Validation

```bash

# 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`](https://github.com/ayghri/i-have-adhd/blob/main/.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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/.claude-plugin/plugin.json) | Core descriptor with name, version, entry point, and hooks |
| [`.claude-plugin/marketplace.json`](https://github.com/ayghri/i-have-adhd/blob/main/.claude-plugin/marketplace.json) | Distribution metadata including tags, category, and author |
| [`hooks/hooks.json`](https://github.com/ayghri/i-have-adhd/blob/main/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:

```yaml
- 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`](https://github.com/ayghri/i-have-adhd/blob/main/.claude-plugin/plugin.json) to pass validation.