How Plugin Names Are Validated in the Claude Plugin Directory

Plugin names in the Claude plugin directory must match the strict regex ^[a-z0-9][a-z0-9-]{1,63}$, must be 2–64 characters long, and the containing folder name must exactly match the name field declared in plugin.json.

The anthropics/claude-plugins-community repository enforces these constraints through automated CI gates to guarantee that every identifier is URL-safe and globally unique. The validation logic is implemented in shell scripts that execute on every pull request, rejecting any plugin that violates the I11 invariant—the specific rule governing name shape and syntax.

The I11 Invariant: Core Naming Rules

The definitive source for name validation resides in .github/actions/validate-plugins/scripts/11-validate-invariants.sh. Lines 19–21 define the I11 invariant, which mandates that the name field in every plugin.json conform to a precise regular expression.

The required pattern is:

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

This single expression encodes three rigid constraints:

• Character set – Only lowercase ASCII letters (a-z), digits (0-9), and hyphens (-) are permitted.
• Length – The name must be between 2 and 64 characters inclusive (one leading character plus 1–63 trailing characters).
• Prefix rule – The first character must be alphanumeric; hyphens cannot lead.

If a plugin name fails this check, the CI workflow aborts with the error:

name: name does not match ^[a-z0-9][a-z0-9-]{1,63}$

Filename Consistency Enforcement

Beyond character validation, the repository requires that the physical folder name mirror the logical plugin name. Line 112 of 11-validate-invariants.sh implements this by comparing the directory basename against the name field inside the manifest.

If a developer creates a folder named quickdesign-plugin but the plugin.json declares "name": "quickdesign", the CI emits an I6 error:

I6 filename != name: quickdesign-plugin vs quickdesign

This rule prevents aliasing ambiguities and guarantees that the filesystem path always matches the canonical identifier referenced by the Claude platform.

Safety Guards Against Unsafe Characters

Lines 70–73 of the validation script implement a shape guard that preemptively rejects names containing whitespace, glob-metacharacters (such as * or ?), or other shell-sensitive symbols. These checks run before the regex test to sanitize input and prevent injection vectors in downstream CI steps.

The whitelist approach ensures that only "word-sized" identifiers—clean tokens that require no escaping—are accepted into the ecosystem.

Practical Validation Examples

The following patterns demonstrate passing and failing configurations as processed by the invariant tests in .github/actions/validate-plugins/test-invariants.sh.

Valid plugin.json Structure

This manifest satisfies the I11 invariant:

{
  "name": "quickdesign",
  "description": "Generative video-design assistant",
  "version": "1.0.0",
  "author": "Anthropic"
}

• Length: 11 characters (within 2–64 range)
• Characters: All lowercase, no spaces
• Consistency: Folder must be named quickdesign

Invalid plugin.json (Uppercase and Space)

This configuration fails validation:

{
  "name": "Quick Design",
  "description": "Invalid because of uppercase and space",
  "version": "1.0.0",
  "author": "Anthropic"
}

Running the validation script produces:

Quick Design: name does not match ^[a-z0-9][a-z0-9-]{1,63}$

CI Error for Filename Mismatch

When the folder name diverges from the manifest name, the invariant checker raises an I6 violation. For example, if the folder is quickdesign-plugin but plugin.json contains "name": "quickdesign", the error logged is:

I6 filename != name: quickdesign-plugin vs quickdesign

Summary

• Regex Rule: All names must match ^[a-z0-9][a-z0-9-]{1,63}$ as enforced in .github/actions/validate-plugins/scripts/11-validate-invariants.sh.
• Character Set: Only lowercase letters, digits, and hyphens are allowed; no underscores or uppercase letters permitted.
• Length Limit: Strict 2–64 character boundary.
• Folder Sync: The directory name must identically match the name field in plugin.json (line 112).
• Safety First: Lines 70–73 reject whitespace and glob-metacharacters before regex evaluation.
• CI Gate: .github/workflows/validate-plugins.yml executes these checks on every pull request.

Frequently Asked Questions

What is the maximum length for a Claude plugin name?

The upper limit is 64 characters. The regex ^[a-z0-9][a-z0-9-]{1,63}$ allows one leading alphanumeric character followed by up to 63 additional valid characters, totaling 64.

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

No. The I11 invariant explicitly restricts the character set to lowercase ASCII letters (a-z), digits (0-9), and hyphens (-). Uppercase letters and underscores violate the regex pattern defined on lines 19–21 of 11-validate-invariants.sh.

Why must the folder name match the plugin name?

This constraint prevents aliasing and ensures filesystem paths remain predictable. Line 112 of the validation script enforces that the directory basename equals the name value in plugin.json, guaranteeing that the Claude platform can resolve plugins unambiguously by their canonical identifiers.

Where can I find the validation script if I want to test locally?

The shell script is located at .github/actions/validate-plugins/scripts/11-validate-invariants.sh in the anthropics/claude-plugins-community repository. You can execute it manually against your plugin directory to verify compliance before submitting a pull request, or run the full test suite in .github/actions/validate-plugins/test-invariants.sh.

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