How to Test Claude Plugins Locally Before Submitting to the Marketplace

You can test Claude plugins locally by running claude plugin validate against your manifest and executing the three validation scripts (20-validate-cli-marketplace.sh, 30-validate-cli-external.sh, and 40-validate-cli-local.sh) that mirror the CI pipeline.

Before submitting a pull request to the anthropics/claude-plugins-community repository, you must verify that your plugin passes the same schema checks and marketplace validations run by GitHub Actions. Running these checks locally prevents rejected submissions by catching missing required fields, schema violations, and file path errors before you ever open a PR.

Install the Claude CLI

The validation workflow depends on the Claude CLI providing the claude plugin validate command. Install it globally via npm:

npm install -g @anthropic/claude-cli
claude --version

Once installed, the CLI can validate individual plugin manifests, the aggregate marketplace file, and external plugin references.

Understand the Validation Pipeline

The repository uses three sequential bash scripts located in .github/actions/validate-plugins/scripts/ to replicate the CI environment locally. Each script targets a specific validation layer:

• Marketplace validation – verifies the root marketplace.json aggregate file
• External validation – clones and checks plugins hosted in external repositories
• Local validation – discovers and tests in-repo plugins that have changed

Running all three ensures your changes will pass the .github/workflows/validate-plugins.yml workflow that executes on every PR.

Validate the Marketplace Configuration

Run the marketplace validation script from the repository root to check that .claude-plugin/marketplace.json is syntactically correct and internally consistent:

bash .github/actions/validate-plugins/scripts/20-validate-cli-marketplace.sh

This script executes claude plugin validate marketplace.json. If you added a new plugin, ensure the marketplace file includes an entry with the correct path field pointing to your plugin's manifest directory. Failures here indicate the aggregate marketplace is out-of-date or contains broken references.

Validate External Plugin References

If your PR adds or modifies entries for plugins hosted outside this repository, run the external validation script:

bash .github/actions/validate-plugins/scripts/30-validate-cli-external.sh

The script clones each external repository at the pinned SHA specified in the marketplace configuration, then runs claude plugin validate against the cloned .claude-plugin/plugin.json. This ensures that third-party plugins remain valid at the exact commit referenced by the community marketplace.

Validate Local Plugins

The most common validation step for contributors checks plugins stored directly in this repository:

bash .github/actions/validate-plugins/scripts/40-validate-cli-local.sh

This script identifies every folder containing a .claude-plugin/plugin.json file that changed in your branch, then executes:

claude plugin validate <folder>/.claude-plugin/plugin.json

The CLI returns PASS, WARN, or FAIL with line-specific details about schema violations or missing auxiliary files like icon.svg or .version.

Run Direct CLI Validation for Quick Checks

For rapid iteration on a single plugin without running the full script suite, invoke the CLI directly:

claude plugin validate quickdesign/.claude-plugin/plugin.json

Replace quickdesign with your plugin's directory name. This command validates the manifest schema, checks for required assets, and verifies field types immediately.

Fix Common Validation Errors

When the scripts report failures, address these specific issues before resubmitting:

• Schema violations – Edit plugin.json to include all required fields (name, version, skills/agents definitions) and correct data types
• Missing auxiliary files – Ensure icon.svg and .version files exist in the .claude-plugin directory if your plugin type requires them
• Marketplace inconsistencies – Update .claude-plugin/marketplace.json to include new plugin entries with accurate relative paths

Re-run the validation scripts iteratively until all steps exit with "OK" or "PASS".

Summary

• Install the @anthropic/claude-cli package globally to access the claude plugin validate command
• Execute 20-validate-cli-marketplace.sh to verify the aggregate marketplace file at .claude-plugin/marketplace.json
• Run 30-validate-cli-external.sh to validate third-party plugins at pinned SHAs
• Use 40-validate-cli-local.sh to test in-repository plugins that have changed in your branch
• Fix schema errors and missing file warnings before opening a PR to ensure the .github/workflows/validate-plugins.yml CI passes immediately

Frequently Asked Questions

What files does the Claude CLI check during validation?

The CLI validates the plugin.json manifest structure against the official schema, verifying required fields like name, version, and skill definitions. It also checks for auxiliary assets such as icon.svg and .version files when specified by the plugin type. According to the anthropics/claude-plugins-community source code, these checks mirror the schema enforcement performed by GitHub Actions in .github/workflows/validate-plugins.yml.

Can I validate a plugin that is not yet added to the marketplace?

Yes. Run claude plugin validate <path-to-plugin>/.claude-plugin/plugin.json directly against the manifest file. This works independently of the marketplace aggregator, allowing you to perfect the plugin configuration before updating .claude-plugin/marketplace.json and running the full 20-validate-cli-marketplace.sh script.

Why does the external validation script clone repositories at specific SHAs?

The 30-validate-cli-external.sh script clones external repositories at the exact commit SHA pinned in marketplace.json to guarantee reproducible builds. This prevents validation failures caused by upstream changes in third-party plugins after the marketplace entry was created, ensuring the community marketplace only references verified, immutable plugin states.

Do I need to run all three validation scripts for every change?

No. If you are only modifying a local in-repo plugin, running 40-validate-cli-local.sh is sufficient. Run 20-validate-cli-marketplace.sh only when you add new plugins or modify marketplace metadata, and execute 30-validate-cli-external.sh exclusively when updating external plugin references. However, running the complete suite before submission guarantees your PR passes the CI workflow without additional iterations.

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