# How the `claude plugin validate` Command Works in Claude Plugins

> Understand how the claude plugin validate command works. It performs static schema validation on your Claude plugin's JSON structure and files without executing code.

- Repository: [Anthropic/claude-plugins-community](https://github.com/anthropics/claude-plugins-community)
- Tags: internals
- Published: 2026-08-30

---

**The `claude plugin validate` command performs static schema validation against the official Claude plugin specification, verifying JSON structure, required fields, and file presence without executing user code.**

The `claude plugin validate` command serves as the canonical verification tool used by the Claude CLI to ensure plugins conform to Anthropic's required specification before publication or installation. In the `anthropics/claude-plugins-community` repository, this command powers the automated CI pipeline that guards the official marketplace against malformed manifests. Understanding its validation logic enables developers to diagnose submission failures and ensure their packages meet the strict standards required for distribution.

## What the `claude plugin validate` Command Checks

The command executes five categories of static analysis, orchestrated through the `cli_validate` helper function defined in [`.github/actions/validate-plugins/lib/common.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/validate-plugins/lib/common.sh).

### JSON Schema Validation

At the core of the validation pipeline, the command parses the plugin's [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) manifest and validates it against the official Claude plugin schema. This guarantees that required fields—including **`name`**, **`description`**, **`version`**, and **`skills`**—are present and correctly typed. The `cli_validate` function in [`common.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/common.sh) invokes the CLI, captures its output, and classifies the result as PASS, WARN, or FAIL based on the schema compliance.

### File Presence Verification

Beyond JSON structure, the command asserts that every required file exists on disk. It verifies the presence of [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) files for each declared skill, hook files, icon assets, and other mandatory resources. According to the implementation in [`common.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/common.sh), these checks prevent runtime crashes caused by missing skill definitions in the Claude environment.

### Strict Mode vs. Non-Strict Mode

The validator supports two validation modes that control schema flexibility. By default, it runs in **strict mode**, which prohibits any extra keys beyond the official specification—immediately rejecting unknown fields like `extraField`. However, analysis of [`30-validate-cli-external.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/30-validate-cli-external.sh) reveals that `strict:false` is used for **skills-only** entries that ship without a full [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) manifest, allowing lightweight plugins to pass validation while maintaining schema integrity for full packages.

### Auxiliary File Validation

The command extends validation to auxiliary metadata files accompanying the main manifest. As implemented in [`41-validate-aux-files.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/41-validate-aux-files.sh), it validates [`hooks.json`](https://github.com/anthropics/claude-plugins-community/blob/main/hooks.json) and MCP configuration files against their respective specifications, ensuring helper files follow their own schemas and won't cause integration failures.

### Marketplace-Wide Validation

When run against [`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json), the command walks every listed plugin entry and validates each in turn. The script [`20-validate-cli-marketplace.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/20-validate-cli-marketplace.sh) orchestrates this process, ensuring the entire marketplace catalog remains internally consistent before any changes are merged.

## CI Integration and Automation

The repository provides a GitHub Action named **`validate-plugins`** that orchestrates the `claude plugin validate` command across three distinct contexts, all utilizing the `cli_validate` wrapper from [`common.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/common.sh).

### Local Plugin Validation

For in-repository plugins modified in a pull request, the script **[`40-validate-cli-local.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/40-validate-cli-local.sh)** executes `claude plugin validate` against each touched plugin folder. This catches schema violations before they reach the main branch.

### External Plugin Validation

The script **[`30-validate-cli-external.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/30-validate-cli-external.sh)** handles marketplace entries pointing to external Git repositories. It clones each external repo at its pinned SHA, then runs the validation command against the downloaded manifest. The script typically wraps this execution with a timeout to prevent hangs during CI runs.

### Marketplace File Validation

Finally, **[`20-validate-cli-marketplace.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/20-validate-cli-marketplace.sh)** validates the assembled [`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json) itself, ensuring that the catalog file structure matches the expected format and that all referenced plugins are valid.

The orchestration is defined in **[`.github/workflows/validate-plugins.yml`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/workflows/validate-plugins.yml)**, which triggers on pull requests and pushes to execute these three validation stages sequentially.

## Practical Usage Examples

Plugin developers and CI systems invoke the command directly against directories or specific manifest files:

```bash

# Validate a local plugin folder (e.g., ./quickdesign)

claude plugin validate ./quickdesign
#> ✅ Validation succeeded

# Validate a specific manifest file directly

claude plugin validate ./.claude-plugin/plugin.json
#> ❌ Error: missing required field "skills"

# Run in strict mode (default) to reject unknown keys

claude plugin validate --strict ./my-plugin
#> ❌ Error: unknown key "extraField" in manifest

# Validate the entire marketplace catalog

claude plugin validate marketplace.json
#> ✅ All plugins in the marketplace are valid

```

## Key Source Files and Architecture

Understanding the validation flow requires examining these specific files in the `anthropics/claude-plugins-community` repository:

- **[`.github/actions/validate-plugins/lib/common.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/validate-plugins/lib/common.sh)**: Contains the **`cli_validate`** helper function that encapsulates the core logic for invoking the CLI and classifying results.
- **[`.github/actions/validate-plugins/scripts/40-validate-cli-local.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/validate-plugins/scripts/40-validate-cli-local.sh)**: Validates changed in-repo plugin directories against the schema.
- **[`.github/actions/validate-plugins/scripts/30-validate-cli-external.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/validate-plugins/scripts/30-validate-cli-external.sh)**: Clones external plugins at their pinned SHA and runs validation, including strict mode configuration for skills-only entries.
- **[`.github/actions/validate-plugins/scripts/20-validate-cli-marketplace.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/validate-plugins/scripts/20-validate-cli-marketplace.sh)**: Validates the assembled [`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json) catalog file.
- **[`.github/actions/validate-plugins/scripts/41-validate-aux-files.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/validate-plugins/scripts/41-validate-aux-files.sh)**: Performs auxiliary file validation for hooks and MCP configurations.
- **[`.github/workflows/validate-plugins.yml`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/workflows/validate-plugins.yml)**: The GitHub Actions workflow that orchestrates the three validation scripts on every pull request.

## Summary

- The `claude plugin validate` command performs **static analysis only**, never executing user code.
- Validation includes **JSON schema checking**, **file presence verification**, and **auxiliary file validation** against official specifications.
- **Strict mode** (default) rejects unknown keys, while non-strict mode accommodates skills-only plugins without full [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) manifests.
- The `anthropics/claude-plugins-community` repository automates validation via the `validate-plugins` GitHub Action across local, external, and marketplace contexts.
- The **`cli_validate`** function in [`common.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/common.sh) serves as the central wrapper for all validation calls in CI.

## Frequently Asked Questions

### What does `claude plugin validate` check?

The command validates the [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) manifest against the official Claude plugin schema, verifies that required files like [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) exist for each declared skill, and checks auxiliary files such as [`hooks.json`](https://github.com/anthropics/claude-plugins-community/blob/main/hooks.json) and MCP configurations. It ensures all required fields—including `name`, `version`, and `skills`—are present and correctly typed according to the specification.

### How does strict mode work in `claude plugin validate`?

By default, the command runs in strict mode and rejects any keys not defined in the official schema. However, as implemented in [`30-validate-cli-external.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/30-validate-cli-external.sh), you can disable strict mode with `strict:false` to allow skills-only plugins that don't include a complete [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) manifest, providing flexibility for lightweight skill distributions.

### Can `claude plugin validate` execute plugin code?

No. The command is purely static—it reads and parses JSON files and checks file system presence without executing any user-provided code. This design makes it safe to run in any CI environment without sandboxing concerns or security vulnerabilities from malicious plugins.

### How is `claude plugin validate` used in CI/CD?

The `anthropics/claude-plugins-community` repository uses it in a GitHub Action named `validate-plugins` that runs three specific scripts: [`40-validate-cli-local.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/40-validate-cli-local.sh) for in-repo changes, [`30-validate-cli-external.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/30-validate-cli-external.sh) for external repository references, and [`20-validate-cli-marketplace.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/20-validate-cli-marketplace.sh) for validating the catalog file itself, ensuring comprehensive coverage of all marketplace entries.