# How the Claude Plugin Validation Pipeline Works: A Complete Technical Guide

> Discover how the Claude plugin validation pipeline works. This 8-stage GitHub Actions workflow automatically validates plugins, verifies assets, and enforces invariants on every pull request.

- Repository: [Anthropic/claude-plugins-community](https://github.com/anthropics/claude-plugins-community)
- Tags: how-to-guide
- Published: 2026-09-05

---

**The Claude plugin validation pipeline is an 8-stage GitHub Actions workflow that automatically validates every plugin against the official Claude CLI schema, verifies auxiliary assets, and enforces repository-wide invariants on every pull request.**

The `anthropics/claude-plugins-community` repository maintains a curated Marketplace of Claude plugins. To ensure quality and compatibility, the **plugin validation pipeline** runs automatically via [`.github/workflows/validate-plugins.yml`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/workflows/validate-plugins.yml), orchestrating a sequence of Bash scripts under `.github/actions/validate-plugins/scripts/`. Each stage serves a distinct purpose in guaranteeing that plugins meet the platform's technical requirements before reaching production.

## Stage 1: Detect Changes and Assemble Marketplace

The pipeline begins with **[`00-detect-changes.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/00-detect-changes.sh)**, which computes the delta between the current HEAD and a configurable `BASE_REF`. This script identifies three categories of changes:

- **Marketplace entries** — individual JSON files that define plugin listings
- **External sources** — third-party plugin manifests referenced by URL or git subdirectory
- **In-repo plugin folders** — complete plugin packages stored directly in the repository

The script outputs [`changes.json`](https://github.com/anthropics/claude-plugins-community/blob/main/changes.json) containing structured data for downstream consumption and assembles a temporary [`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json) by merging per-file entries if `ENTRIES_DIR` mode is active.

```bash

# Key environment variables consumed by this stage

BASE_REF=origin/main
MARKETPLACE_PATH=.claude-plugin/marketplace.json
ENTRIES_DIR=.claude-plugin/entries  # Optional: enables per-file mode

VALIDATE_TMP=/tmp/validate-XXXXXX

```

## Stage 2: CLI Marketplace Validation

The **[`20-validate-cli-marketplace.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/20-validate-cli-marketplace.sh)** script invokes the official Claude CLI command:

```bash
claude plugin validate $VALIDATE_TMP/marketplace.json

```

This validates the assembled marketplace manifest against the **live schema** shipped with the CLI, catching structural errors, missing required fields, and schema version mismatches before any external sources or individual plugins are examined.

## Stage 3: External Source Validation

For marketplace entries that reference external manifests via the `source` object (URLs or git subdirectories), **[`30-validate-cli-external.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/30-validate-cli-external.sh)** fetches and validates each remote definition:

```bash

# Pseudocode representation of the validation flow

for each entry in changes.json → external:
    fetch manifest from entry.source.url or entry.source.git
    claude plugin validate <fetched-manifest>

```

This prevents stale or broken external references from corrupting the Marketplace experience.

## Stage 4: In-Repo Plugin Validation

The **[`40-validate-cli-local.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/40-validate-cli-local.sh)** script walks each changed plugin folder identified in stage 1 and runs:

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

```

This checks:
- Plugin metadata (name, version, description)
- UI schema compliance
- Handler configurations
- Local asset references

## Stage 5: Auxiliary Files Validation

Beyond JSON schema compliance, **[`41-validate-aux-files.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/41-validate-aux-files.sh)** enforces **file-level constraints**:

- **Icons**: format, dimensions, file size limits
- **Screenshots**: required resolutions, maximum count
- **Documentation**: README presence, required sections
- **Naming conventions**: consistent file organization under `.claude-plugin/`

## Stage 6: Invariants Check

The **[`11-validate-invariants.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/11-validate-invariants.sh)** script enforces **repository-wide rules** that transcend individual plugin validity:

| Invariant | Purpose |
|-----------|---------|
| **Unique plugin names** | Prevents namespace collisions in the Marketplace |
| **Proper version bumping** | Ensures semantic versioning discipline |
| **Manifest-directory consistency** | Verifies that [`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json) entries match actual folder contents |

Violations here fail the build even if all individual plugins pass CLI validation.

## Stage 7: Reporting and PR Feedback

The final stage, **[`90-report.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/90-report.sh)**, consolidates all validation results into [`report.json`](https://github.com/anthropics/claude-plugins-community/blob/main/report.json) and annotates the pull request with a summary. The script:

1. Aggregates pass/fail status from all preceding stages
2. Generates human-readable error messages with file paths and line numbers
3. Posts a comment to the PR with a status badge
4. Exits with code `1` if any validation failed, blocking merge

## Running the Validation Pipeline Locally

Developers can replicate the full CI workflow locally for debugging:

```bash

# Clone and enter repository

git clone https://github.com/anthropics/claude-plugins-community.git
cd claude-plugins-community

# Execute validation pipeline (requires Claude CLI installed)

export BASE_REF=origin/main
export MARKETPLACE_PATH=.claude-plugin/marketplace.json
export VALIDATE_TMP=$(mktemp -d)

./.github/actions/validate-plugins/scripts/00-detect-changes.sh && \
./.github/actions/validate-plugins/scripts/20-validate-cli-marketplace.sh && \
./.github/actions/validate-plugins/scripts/30-validate-cli-external.sh && \
./.github/actions/validate-plugins/scripts/40-validate-cli-local.sh && \
./.github/actions/validate-plugins/scripts/41-validate-aux-files.sh && \
./.github/actions/validate-plugins/scripts/11-validate-invariants.sh && \
./.github/actions/validate-plugins/scripts/90-report.sh

```

### Quick Single-Plugin Validation

For faster iteration during development:

```bash
cd my-plugin
claude plugin validate .claude-plugin/plugin.json

```

## Key Files in the Validation Pipeline

| File Path | Responsibility |
|-----------|----------------|
| [`.github/workflows/validate-plugins.yml`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/workflows/validate-plugins.yml) | Workflow definition and job orchestration |
| [`.github/actions/validate-plugins/lib/common.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/validate-plugins/lib/common.sh) | Shared utilities (`group_start`, `log`, `die`) |
| [`.github/actions/validate-plugins/scripts/00-detect-changes.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/validate-plugins/scripts/00-detect-changes.sh) | Change detection and marketplace assembly |
| [`.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) | Full manifest validation |
| [`.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) | External source verification |
| [`.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) | In-repo plugin validation |
| [`.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) | Asset compliance checks |
| [`.github/actions/validate-plugins/scripts/11-validate-invariants.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/validate-plugins/scripts/11-validate-invariants.sh) | Repository-wide constraint enforcement |
| [`.github/actions/validate-plugins/scripts/90-report.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/validate-plugins/scripts/90-report.sh) | Report generation and PR annotation |

## Summary

- The **plugin validation pipeline** is an automated 8-stage GitHub Actions workflow defined in [`.github/workflows/validate-plugins.yml`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/workflows/validate-plugins.yml)
- **Change detection** ([`00-detect-changes.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/00-detect-changes.sh)) minimizes validation scope to modified components only
- **CLI validation** uses `claude plugin validate` at three levels: marketplace manifest, external sources, and local plugins
- **Auxiliary checks** ([`41-validate-aux-files.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/41-validate-aux-files.sh)) enforce asset quality standards for icons, screenshots, and documentation
- **Invariant enforcement** ([`11-validate-invariants.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/11-validate-invariants.sh)) maintains repository integrity through unique names and proper versioning
- **Local execution** is fully supported by running the same Bash scripts used in CI, enabling pre-commit validation

## Frequently Asked Questions

### What triggers the plugin validation pipeline?

The pipeline triggers on every pull request and every push to the `main` branch via GitHub Actions workflow definitions in [`.github/workflows/validate-plugins.yml`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/workflows/validate-plugins.yml). This ensures continuous validation without manual intervention.

### Can I validate my plugin without opening a pull request?

Yes. Install the Claude CLI locally and run `claude plugin validate .claude-plugin/plugin.json` from your plugin directory. For full pipeline replication, execute the individual Bash scripts under `.github/actions/validate-plugins/scripts/` with appropriate environment variables set.

### What happens if external plugin sources become unavailable?

Stage 3 ([`30-validate-cli-external.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/30-validate-cli-external.sh)) validates all external manifests on every run. If a URL returns 404 or a git submodule fails to fetch, the validation fails and blocks the PR. This prevents the Marketplace from advertising broken integrations.

### How does the pipeline handle version conflicts?

The [`11-validate-invariants.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/11-validate-invariants.sh) script specifically checks for **proper version bumping** and **unique plugin names**. It compares the proposed changes against `BASE_REF` to ensure semantic versioning rules are followed and no naming collisions are introduced.