Validation Invariants for Claude Plugins: CI Rules and Marketplace Requirements

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

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

{
  "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

{
  "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 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	Documents all validation invariants (I1–I10) and CI logic	Source
.claude-plugin/marketplace.json	Global marketplace manifest; must pass I1 sorting checks	Source
.claude-plugin/plugins/<slug>.json	Individual plugin metadata; must satisfy I6 naming rules	Example
plugin.json (in plugin source)	Core manifest requiring name, version, description, entrypoints (I10)	Example
.github/workflows/validate-plugins.yml	CI workflow orchestrating the three validation stages	Source

Summary

• Alphabetical ordering (I1) requires the plugins array in 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 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, while the implementation logic resides in the action's entrypoint scripts within the same directory. The CI workflow in .github/workflows/validate-plugins.yml orchestrates when these checks run.

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