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

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, 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, 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 containing structured data for downstream consumption and assembles a temporary marketplace.json by merging per-file entries if ENTRIES_DIR mode is active.

# 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 script invokes the official Claude CLI command:

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 fetches and validates each remote definition:

# 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 script walks each changed plugin folder identified in stage 1 and runs:

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 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 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 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, consolidates all validation results into 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:

# 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:

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

Key Files in the Validation Pipeline

File Path	Responsibility
.github/workflows/validate-plugins.yml	Workflow definition and job orchestration
.github/actions/validate-plugins/lib/common.sh	Shared utilities (group_start, log, die)
.github/actions/validate-plugins/scripts/00-detect-changes.sh	Change detection and marketplace assembly
.github/actions/validate-plugins/scripts/20-validate-cli-marketplace.sh	Full manifest validation
.github/actions/validate-plugins/scripts/30-validate-cli-external.sh	External source verification
.github/actions/validate-plugins/scripts/40-validate-cli-local.sh	In-repo plugin validation
.github/actions/validate-plugins/scripts/41-validate-aux-files.sh	Asset compliance checks
.github/actions/validate-plugins/scripts/11-validate-invariants.sh	Repository-wide constraint enforcement
.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
• Change detection (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) enforce asset quality standards for icons, screenshots, and documentation
• Invariant enforcement (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. 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) 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 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.

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