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

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.

JSON Schema Validation

At the core of the validation pipeline, the command parses the plugin's 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 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 files for each declared skill, hook files, icon assets, and other mandatory resources. According to the implementation in 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 reveals that strict:false is used for skills-only entries that ship without a full 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, it validates 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, the command walks every listed plugin entry and validates each in turn. The script 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.

Local Plugin Validation

For in-repository plugins modified in a pull request, the script 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 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 validates the assembled 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, 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:

# 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: 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: Validates changed in-repo plugin directories against the schema.
• .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: Validates the assembled marketplace.json catalog file.
• .github/actions/validate-plugins/scripts/41-validate-aux-files.sh: Performs auxiliary file validation for hooks and MCP configurations.
• .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 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 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 manifest against the official Claude plugin schema, verifies that required files like SKILL.md exist for each declared skill, and checks auxiliary files such as 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, you can disable strict mode with strict:false to allow skills-only plugins that don't include a complete 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 for in-repo changes, 30-validate-cli-external.sh for external repository references, and 20-validate-cli-marketplace.sh for validating the catalog file itself, ensuring comprehensive coverage of all marketplace entries.

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