# Claude Plugins Community validate-plugins.yml GitHub Actions Workflow Explained

> Understand the validate-plugins.yml GitHub Actions workflow, the automated gatekeeper for the Claude Plugins Community marketplace, ensuring plugin integrity and correctness before merging.

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

---

**The [`validate-plugins.yml`](https://github.com/anthropics/claude-plugins-community/blob/main/validate-plugins.yml) GitHub Actions workflow serves as the automated gatekeeper for the Claude Plugins Community marketplace, executing seven distinct validation suites on every pull request to ensure plugin metadata integrity, SHA-pinning correctness, and owner liveness before any changes reach the main branch.**

The `anthropics/claude-plugins-community` repository maintains a curated marketplace of community-built Claude plugins defined in [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json). According to the source code in [`.github/workflows/validate-plugins.yml`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/workflows/validate-plugins.yml), the [`validate-plugins.yml`](https://github.com/anthropics/claude-plugins-community/blob/main/validate-plugins.yml) GitHub Actions workflow functions as the continuous integration backbone, automatically triggering whenever contributors modify plugin definitions or validation logic to prevent malformed or insecure plugins from entering the ecosystem.

## Workflow Triggers and Execution Context

The workflow activates on three specific events defined in [`.github/workflows/validate-plugins.yml`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/workflows/validate-plugins.yml):

- Pull requests that modify files under `.claude-plugin/**` (plugin definitions)
- Pull requests that modify `.github/actions/**` (the validation logic itself)
- Direct pushes to the `main` branch

This trigger configuration ensures that any change affecting the marketplace or its validation infrastructure undergoes mandatory automated scrutiny before merging. If any validation step fails, the workflow marks the pull request as failing and blocks merges until all invariants pass.

## The Seven Core Validation Suites

The workflow orchestrates seven discrete test scripts, each targeting a specific quality or security invariant.

### 1. Static Invariant Tests

The workflow executes [`test-invariants.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/test-invariants.sh) from the `.github/actions/validate-plugins/` directory to verify that all plugins obey static metadata rules. This script validates **required fields**, **naming conventions**, and schema compliance in plugin definitions. Catching malformed metadata at this stage prevents broken plugins from reaching the public marketplace.

### 2. Version Bump Logic Verification

Using [`test-bump.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/test-bump.sh) located in `.github/actions/bump-plugin-shas/`, the workflow validates the "skip" and "freeze" logic for version bumps. This ensures that **SHA-pinning** for releases behaves deterministically, allowing maintainers to control exactly which plugin versions appear in the marketplace without unexpected automatic updates.

### 3. Manifest Synthesis Tests

The [`test-bump-manifest.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/test-bump-manifest.sh) script validates the generated marketplace manifest after a bump operation. This step confirms that the public [`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json) file remains internally consistent and properly formatted when the automation synthesizes new plugin versions, guaranteeing that the final artifact matches the expected schema.

### 4. Owner Liveness Sweep

The workflow runs [`test-sweep.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/test-sweep.sh) from `.github/actions/owner-liveness-sweep/` to verify that plugin owners remain active. This prevents **abandoned plugins** from lingering in the marketplace, ensuring that every listed plugin has a maintainer who can respond to security issues or API changes.

### 5. External Manifest Resolution

Executing [`test-external-manifest.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/test-external-manifest.sh) from `.github/actions/validate-plugins/`, the workflow checks that external plugin manifests can be fetched and parsed correctly. This guarantees reliable **cross-repository plugin discovery**, ensuring that plugins hosted outside the main repository remain accessible and valid.

### 6. Pin-Check Golden Vector Tests

The [`test-pin-check.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/test-pin-check.sh) script located in `.github/actions/scan-plugins/` compares current pin-check results against known good "golden" vectors. This **regression detection** mechanism ensures that the static pin-check logic remains stable and does not accidentally flag valid plugins as insecure or miss compromised dependencies.

### 7. Dog-Food Validation

Finally, the workflow invokes the repository's own `./.github/actions/validate-plugins` composite action against the live [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json) file using parameters `--marketplace-path`, `--skip-local-folders true`, and `--scope-errors-to-changed true`. This self-testing step ensures the validation action works correctly on real production data and enforces that external consumers must pin a specific SHA when referencing the action (as documented in the action's README).

## Local Development and Testing

Contributors can run the same validation suites locally before opening pull requests to reduce CI turnaround time.

To execute the static invariant tests manually:

```bash
cd claude-plugins-community
bash .github/actions/validate-plugins/test-invariants.sh

```

To run the full validation action locally (mirroring the final CI step):

```bash
./.github/actions/validate-plugins/action.yml \
  --marketplace-path .claude-plugin/marketplace.json \
  --skip-local-folders true \
  --scope-errors-to-changed true

```

For a complete Docker-based simulation of the CI environment, use the `act` tool:

```bash

# Install act (https://github.com/nektos/act)

brew install act

# Run the validate job locally

act -j validate

```

These local execution paths allow developers to catch failures early without waiting for GitHub Actions runners.

## Implementation Architecture and Key Files

The validation pipeline relies on several critical components:

- **[`.github/workflows/validate-plugins.yml`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/workflows/validate-plugins.yml)** - The orchestration layer that defines trigger conditions and step sequences
- **[`.github/actions/validate-plugins/action.yml`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/validate-plugins/action.yml)** - The reusable composite action entrypoint implementing core validation logic
- **[`.github/actions/validate-plugins/lib/common.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/validate-plugins/lib/common.sh)** - Shared utility functions used across test scripts
- **[`test-invariants.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/test-invariants.sh)** - Schema and metadata validation for plugin definitions
- **[`test-bump.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/test-bump.sh)** - SHA-pinning and version bump logic verification (in `bump-plugin-shas` action)
- **[`test-sweep.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/test-sweep.sh)** - Owner account activity verification (in `owner-liveness-sweep` action)
- **[`test-external-manifest.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/test-external-manifest.sh)** - Cross-repository manifest resolution testing
- **[`test-pin-check.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/test-pin-check.sh)** - Static analysis regression testing against golden vectors (in `scan-plugins` action)

This modular architecture separates concerns between workflow orchestration, reusable action logic, and specific test implementations, making the system maintainable as the marketplace scales.

## Summary

- The [`validate-plugins.yml`](https://github.com/anthropics/claude-plugins-community/blob/main/validate-plugins.yml) workflow automatically gates every change to the Claude Plugins Community marketplace through seven specialized test suites
- Validation covers static metadata integrity, version bump logic, manifest synthesis, owner liveness, external resolution capabilities, regression testing, and self-validation
- Execution triggers include PRs affecting `.claude-plugin/` or `.github/actions/` and all pushes to `main`
- Local execution via shell scripts or the `act` tool enables pre-commit validation
- The workflow enforces SHA-pinning requirements for security and prevents abandoned plugins from persisting in the marketplace

## Frequently Asked Questions

### When does the validate-plugins.yml workflow trigger?

The workflow activates on pull requests that modify files in `.claude-plugin/**` (plugin definitions) or `.github/actions/**` (validation logic), as well as on every push to the `main` branch. This ensures both plugin changes and tooling updates undergo mandatory validation according to the workflow definition in [`.github/workflows/validate-plugins.yml`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/workflows/validate-plugins.yml).

### How does the workflow prevent broken plugins from entering the marketplace?

The workflow runs [`test-invariants.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/test-invariants.sh) to enforce static metadata rules and schema compliance. If a plugin definition lacks required fields or violates naming conventions, the test fails and blocks the pull request from merging until the metadata is corrected, catching malformed entries before they reach the public [`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json).

### What is the purpose of the "dog-food" validation step?

The dog-food step invokes the repository's own `validate-plugins` action against the live [`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json) file with flags like `--scope-errors-to-changed`. This ensures the validation logic works correctly on real production data and verifies that the action can be safely consumed by external repositories that pin specific SHA versions.

### Can I run these validations locally before submitting a PR?

Yes. Contributors can execute individual test scripts like `bash .github/actions/validate-plugins/test-invariants.sh` or use the `act` tool (`act -j validate`) to simulate the full GitHub Actions environment locally. This allows catching errors early without waiting for remote CI execution.