# Validation Invariants for Claude Plugins: CI Rules and Marketplace Requirements

> Understand validation invariants for Claude plugins. Learn about CI rules and marketplace requirements for structural integrity and consistency in plugin development.

- Repository: [Anthropic/claude-plugins-community](https://github.com/anthropics/claude-plugins-community)
- Tags: best-practices
- Published: 2026-08-31

---

**The validation invariants for Claude plugins enforce strict structural rules—including alphabetical ordering, filename consistency, source path validation, and required field presence—through the `validate-plugins` GitHub Action in the `anthropics/claude-plugins-community` repository.**

The `anthropics/claude-plugins-community` repository maintains a curated marketplace of Claude plugins through automated continuous integration checks. These **validation invariants** govern everything from JSON schema compliance to repository structure, ensuring that only consistent, secure, and properly formatted plugins are published. Every pull request is validated against these rules in [`.github/actions/validate-plugins/README.md`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/validate-plugins/README.md) before merging.

## Core Validation Invariants

The CI pipeline enforces specific numbered invariants that cover marketplace ordering, file naming, source integrity, and mandatory metadata.

### I1 – Alphabetical Ordering in marketplace.json

The top-level `plugins` array inside [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json) must be sorted alphabetically by the `name` field. This invariant ensures the marketplace remains searchable and deterministic. Any out-of-order entries cause the validation action to exit with an error.

[View invariant definition in source](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/validate-plugins/README.md)

### I5 – SHA Exemption Handling

Plugins listed in the `sha-exempt` configuration array may optionally omit the `source.sha` field. However, if a SHA is provided, it must be well-formed; malformed SHAs trigger validation failures regardless of exemption status. This allows flexbility for development workflows while maintaining integrity for published versions.

### I6 – Filename-to-Name Consistency

Every plugin file stored at `.claude-plugin/plugins/<slug>.json` must contain a `name` field that exactly matches the filename `<slug>`. For example, a file named [`my-cool-plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/my-cool-plugin.json) must contain `"name": "my-cool-plugin"`. This invariant prevents mismatched metadata and broken references.

### I8 – Vendored Source Path Validation

When a plugin specifies a `source.path` pointing to a vendored directory, that path must exist and contain a valid [`.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json) manifest. The validator checks file system presence and schema compliance, ensuring that local plugin copies are complete and deployable.

### Required Fields (I10)

Every [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) manifest must include the mandatory keys: `name`, `version`, `description`, and `entrypoints`. Missing any of these fields results in an immediate validation error. The `entrypoints` object defines the plugin's capabilities and must conform to the expected schema structure.

## Validation Pipeline Stages

The `validate-plugins` action applies these invariants across three distinct stages during CI execution.

**Marketplace Validation**

The validator first checks the global [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json) file for structural correctness, primarily enforcing **I1** (alphabetical ordering) and global schema compliance.

**External Plugin Validation**

For plugins referencing external repositories, the action clones the code at the pinned `source.sha` and executes `claude plugin validate`. This enforces **I5** (SHA handling) and **I8** (source path validity) while ensuring the external code matches the declared manifest.

**Local Plugin Validation**

Any plugins modified within the pull request are validated locally using `claude plugin validate`. This catches **I6** (naming consistency) and **I10** (required fields) errors before they reach the marketplace merge.

## Practical Examples

The following examples demonstrate valid structures that satisfy all validation invariants.

### Valid plugin.json Manifest

```json
{
  "name": "tres-finance-plugin",
  "version": "1.2.3",
  "description": "A Claude plugin for DeFi portfolio analysis.",
  "entrypoints": {
    "analyzePortfolio": {
      "type": "skill",
      "path": "skills/analyzePortfolio/SKILL.md"
    }
  },
  "source": {
    "path": "tres-finance-plugin",
    "sha": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0"
  }
}

```

### Valid marketplace.json Entry

```json
{
  "plugins": [
    {
      "name": "alpha-helper",
      "source": {
        "path": "./alpha-helper",
        "sha": "d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8g9h0i1j2k3"
      }
    },
    {
      "name": "tres-finance-plugin",
      "source": {
        "path": "./tres-finance-plugin",
        "sha": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0"
      }
    },
    {
      "name": "zeta-search",
      "source": {
        "path": "./zeta-search",
        "sha": "9z8y7x6w5v4u3t2s1r0q9p8o7n6m5l4k3j2i1h0g"
      }
    }
  ]
}

```

In this example, the `plugins` array follows **I1** (alphabetical order: "alpha-helper", "tres-finance-plugin", "zeta-search"). The [`tres-finance-plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/tres-finance-plugin.json) filename matches the `name` field exactly (**I6**), and the `source.path` points to a directory containing the manifest shown above (**I8**).

## Key Source Files

| File | Purpose | Link |
|------|---------|------|
| [`.github/actions/validate-plugins/README.md`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/validate-plugins/README.md) | Documents all validation invariants (I1–I10) and CI logic | [Source](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/validate-plugins/README.md) |
| [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json) | Global marketplace manifest; must pass **I1** sorting checks | [Source](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json) |
| `.claude-plugin/plugins/<slug>.json` | Individual plugin metadata; must satisfy **I6** naming rules | [Example](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugins/tres-finance-plugin.json) |
| [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) (in plugin source) | Core manifest requiring `name`, `version`, `description`, `entrypoints` (**I10**) | [Example](https://github.com/anthropics/claude-plugins-community/blob/main/tres-finance-plugin/.claude-plugin/plugin.json) |
| [`.github/workflows/validate-plugins.yml`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/workflows/validate-plugins.yml) | CI workflow orchestrating the three validation stages | [Source](https://github.com/anthropics/claude-plugins-community/blob/main/.github/workflows/validate-plugins.yml) |

## Summary

- **Alphabetical ordering** (**I1**) requires the `plugins` array in [`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json) to be sorted by name.
- **Filename consistency** (**I6**) mandates that `.claude-plugin/plugins/<slug>.json` files match their internal `name` field.
- **Source validation** (**I8**) ensures vendored paths exist and contain valid [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) manifests.
- **SHA exemptions** (**I5**) allow specific plugins to omit commit SHAs, but malformed SHAs still fail.
- **Required fields** (**I10**) include `name`, `version`, `description`, and `entrypoints` in every plugin manifest.
- The CI pipeline runs three stages: marketplace, external, and local validation.

## Frequently Asked Questions

### What happens if the marketplace.json file is not alphabetically sorted?

The `validate-plugins` action will fail with an error citing **I1**. The pull request checks will block merging until the `plugins` array is reordered alphabetically by the `name` field.

### Can a development plugin omit the source.sha field?

Yes, but only if the plugin identifier is explicitly listed in the `sha-exempt` configuration array. If listed, the validator skips the SHA requirement (**I5**). However, if a SHA is provided, it must be a valid commit hash; malformed values always trigger failures.

### How does the CI differentiate between external and local plugin validation?

External validation clones remote repositories at the pinned `sha` and runs `claude plugin validate` against the downloaded code. Local validation runs the same command on files that exist within the `anthropics/claude-plugins-community` repository itself, typically checking plugins under `.claude-plugin/plugins/`.

### Where are the validation invariants defined in the source code?

The invariants are documented in the README at [`.github/actions/validate-plugins/README.md`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/validate-plugins/README.md), while the implementation logic resides in the action's entrypoint scripts within the same directory. The CI workflow in [`.github/workflows/validate-plugins.yml`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/workflows/validate-plugins.yml) orchestrates when these checks run.