Claude Plugins Invariant Rules (I1–I9): Validation Requirements for the Community Marketplace

Claude community plugins must satisfy nine static invariant checks (I1–I9) defined in the validate-plugins GitHub Action, including unique naming constraints (I2) and strict description formatting rules (I3), before being accepted into the marketplace.

The Claude plugins invariant rules form the automated validation layer for the anthropics/claude-plugins-community repository. These static checks run against .claude-plugin/marketplace.json to ensure every plugin entry meets structural and formatting standards before deployment.

What Are the Claude Plugin Invariant Rules?

The invariant rules (I1–I9) are hard-coded validation constraints enforced by the validate-plugins action. According to the source code in .github/actions/validate-plugins/README.md, these checks prevent malformed entries from entering the canonical marketplace list. While the complete set includes nine distinct validations, the rules designated II (I2) and III (I3) specifically govern unique identification and metadata formatting.

Rule I2: Unique Plugin Names

Invariant I2 enforces that every plugin entry must have a globally unique name field within the marketplace JSON.

Duplicate name values trigger immediate validation failures. The name field serves as the primary identifier for plugins in the ecosystem, and collisions would break lookup mechanisms and installation procedures.

Invalid Example (Duplicate Names)

The following JSON snippet violates I2 because both entries share the identical name "example-plugin":

{
  "name": "example-plugin",
  "description": "A valid description of sufficient length.",
  "source": { "url": "https://github.com/user/example.git", "sha": "1234abcd…" }
},
{
  "name": "example-plugin",
  "description": "Another valid description.",
  "source": { "url": "https://github.com/other/other.git", "sha": "deadbeef…" }
}

Valid Example (Unique Names)

To satisfy I2, append distinguishing identifiers to create unique names:

{
  "name": "example-plugin",
  "description": "A concise, well‑written description.",
  "source": { "url": "https://github.com/user/example.git", "sha": "1234abcd…" }
},
{
  "name": "example-plugin-2",
  "description": "Another valid plugin description.",
  "source": { "url": "https://github.com/other/other.git", "sha": "deadbeef…" }
}

Rule I3: Description Length and Whitespace Constraints

Invariant I3 mandates that the description field must contain between 10 and 2000 characters and must not include leading or trailing whitespace.

This rule ensures consistent rendering in the Claude interface while preventing empty or spam-length descriptions that degrade user experience.

Invalid Example (Length and Whitespace Violations)

This entry fails I3 on two counts: the description is shorter than 10 characters and contains surrounding whitespace:

{
  "name": "short-plugin",
  "description": "  Too short  ",
  "source": { "url": "https://github.com/user/example.git", "sha": "1234abcd…" }
}

Valid Example (Proper Description Format)

Correct descriptions strip whitespace and meet the minimum character threshold:

{
  "name": "short-plugin",
  "description": "A concise, well‑written description (≥10 chars, no surrounding whitespace).",
  "source": { "url": "https://github.com/user/example.git", "sha": "1234abcd…" }
}

Where Invariant Rules Are Defined

The complete invariant reference table lives in .github/actions/validate-plugins/README.md at lines 41–46. This documentation specifies the static checks applied to every submission targeting .claude-plugin/marketplace.json.

The validation action runs automatically on pull requests, parsing the marketplace JSON and asserting that all nine invariants (I1–I9) pass before maintainers review the submission.

Summary

• Invariant rules I1–I9 are static validations enforced by the validate-plugins action in anthropics/claude-plugins-community.
• Rule I2 requires unique name values across all entries in the marketplace JSON to prevent identifier collisions.
• Rule I3 restricts descriptions to 10–2000 characters and prohibits leading or trailing whitespace.
• Violations are detected in .github/actions/validate-plugins/README.md and block acceptance into .claude-plugin/marketplace.json.

Frequently Asked Questions

What happens if my plugin name duplicates an existing entry?

The validate-plugins action will reject your pull request with a validation error indicating that the name field must be unique. You must modify your plugin's name in the marketplace JSON to resolve the conflict before resubmission.

Are HTML or Markdown tags allowed in the description field?

The invariant rules specify character length and whitespace constraints but do not explicitly forbid markup. However, descriptions are treated as plain text strings in the validation logic, so tags count toward the 2000-character limit and may render literally in the Claude interface.

How can I check my plugin against invariant rules before submitting?

Review the "Invariants reference" table in .github/actions/validate-plugins/README.md and manually verify your JSON entry satisfies I2 (unique name) and I3 (description formatting). While there is no local CLI tool mentioned in the repository, ensuring your name is unique against the current marketplace.json and your description meets length requirements will satisfy the primary blockers.

Do the invariant rules apply to private plugin repositories?

The I1–I9 rules apply specifically to entries submitted to the public .claude-plugin/marketplace.json file in the community repository. Private plugins not listed in the official marketplace are not subject to these automated validation checks.

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