How to Ensure Your Claude Plugin Name Conforms to Naming Rules

Claude plugin names must match the regular expression ^[a-z0-9][a-z0-9-]{1,63}$, allowing only lowercase letters, numbers, and hyphens, with a length between 2 and 64 characters.

The anthropics/claude-plugins-community repository enforces strict Claude plugin naming rules through automated CI validation to ensure marketplace consistency. When you submit a plugin, the validate-plugins GitHub Action checks that your name field in .claude-plugin/plugin.json satisfies Invariant I11—a regex pattern defined in 11-validate-invariants.sh that guarantees predictable CLI usage and URL-safe slugs.

Claude Plugin Naming Rules and the I11 Invariant

The repository codifies its naming requirements as Invariant I11 in the file /.github/actions/validate-plugins/scripts/11-validate-invariants.sh at line 19. This invariant validates the name field extracted from each plugin's manifest against the pattern:

^[a-z0-9][a-z0-9-]{1,63}$

This pattern enforces four specific constraints:

• Lowercase alphanumerics only – No uppercase letters or special characters like underscores or dots.
• Hyphens permitted – Hyphens may appear between characters but never at the start or end, and never consecutively.
• Minimum length of 2 characters – The first character plus at least one additional character.
• Maximum length of 64 characters – The first character plus up to 63 additional characters.

When validation fails, the CI job emits an error formatted as:

::error file=.../marketplace.json,line=…::invariant I11: <name>: name does not match ^[a-z0-9][a-z0-9-]{1,63}$

Validating Your Plugin Name Locally

You can verify name compliance before submitting a PR by running local checks against your .claude-plugin/plugin.json file.

Bash Regex Validation

Use a bash script to test your proposed name against the I11 pattern:

#!/usr/bin/env bash

# Verify a plugin name before committing

PLUGIN_NAME="my-awesome-plugin"

if [[ "$PLUGIN_NAME" =~ ^[a-z0-9][a-z0-9-]{1,63}$ ]]; then
  echo "✅ Name is valid"
else
  echo "❌ Invalid name – must match ^[a-z0-9][a-z0-9-]{1,63}$"
  exit 1
fi

Add this script to your pre-commit hooks to catch naming errors before they reach CI.

Validating plugin.json with jq

To check the actual manifest file used by your plugin (e.g., tres-finance-plugin/.claude-plugin/plugin.json), extract the name field with jq and validate it:

#!/usr/bin/env bash

# Validate the name field inside plugin.json

FILE="tres-finance-plugin/.claude-plugin/plugin.json"
NAME=$(jq -r '.name' "$FILE")

if [[ "$NAME" =~ ^[a-z0-9][a-z0-9-]{1,63}$ ]]; then
  echo "✅ $NAME passes I11 naming rule"
else
  echo "❌ $NAME fails I11 naming rule"
  exit 1
fi

How CI Enforcement Works in the Repository

The repository automates name validation through the .github/workflows/validate-plugins.yml workflow. This job invokes 11-validate-invariants.sh on every PR that adds or updates plugin definitions.

Because the validation runs against the assembled marketplace.json (the consolidated registry of all plugins), any violation blocks the PR from merging. This ensures that every plugin published to the Claude marketplace adheres to the Claude plugin naming rules without requiring manual review of each name.

Summary

• Claude plugin names must match the regex ^[a-z0-9][a-z0-9-]{1,63}$ as defined in Invariant I11.
• Valid characters include lowercase letters, digits, and hyphens (but not as the first or last character).
• Length constraints require between 2 and 64 characters total.
• CI enforcement occurs automatically via /.github/actions/validate-plugins/scripts/11-validate-invariants.sh when you open a PR.
• Local validation is possible using bash regex or jq to check your .claude-plugin/plugin.json before submission.

Frequently Asked Questions

Can I use underscores or uppercase letters in my Claude plugin name?

No. The I11 invariant explicitly restricts names to lowercase alphanumeric characters and hyphens only. Uppercase letters, underscores, dots, and other special characters will cause the CI validation to fail with an error referencing the regex pattern ^[a-z0-9][a-z0-9-]{1,63}$.

What happens if my plugin name is exactly one character long?

The validation will fail. The regex requires a minimum of two characters: the first character must be alphanumeric ([a-z0-9]), followed by 1 to 63 additional characters ([a-z0-9-]{1,63}). Single-character names do not satisfy the {1,63} quantifier requirement.

Does the CI check run on every pull request?

Yes. The workflow defined in .github/workflows/validate-plugins.yml executes the 11-validate-invariants.sh script automatically on PRs that modify plugin files. This check validates all entries in the consolidated marketplace.json, ensuring that no non-conforming names enter the repository even if you skip local validation.

Where is the exact regex pattern defined in the source code?

The regex is hardcoded at line 19 of /.github/actions/validate-plugins/scripts/11-validate-invariants.sh as part of the I11 invariant check. This script is the authoritative source for the naming rule, and any changes to the pattern would be reflected in that file.

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