Plugin Naming Conventions for the OpenAI Plugins Repository

New plugins in the openai/plugins repository must use kebab-case identifiers (lowercase letters, numbers, and hyphens) with no spaces, and the plugin folder name must exactly match the name value in plugin.json.

When developing extensions for the openai/plugins repository, strict adherence to naming conventions is mandatory for automated discovery and CI validation. These rules are formally defined in the plugin JSON specification and enforce consistent namespace alignment between the filesystem and the manifest.

Core Naming Requirements from the Specification

Kebab-Case Formatting Restrictions

According to .agents/skills/plugin-creator/references/plugin-json-spec.md at line 52, the name field is strictly defined as a kebab-case string. This format permits only lowercase letters, numbers, and hyphens while explicitly prohibiting spaces. Uppercase characters and underscores violate this standard.

Folder-to-Manifest Name Alignment

Line 142 of the same specification file mandates that the plugin identifier must match the plugin folder name and the name value in plugin.json. This constraint ensures deterministic namespace resolution and prevents path ambiguity during plugin discovery.

Required File Structure

The manifest must reside in a hidden .codex-plugin directory within the plugin root. For example, the coderabbit plugin uses the path plugins/coderabbit/.codex-plugin/plugin.json. The name field inside this file must exactly mirror the parent directory name.

// Located at: plugins/coderabbit/.codex-plugin/plugin.json
{
  "name": "coderabbit",
  "version": "1.0.0",
  "description": "Example plugin following naming conventions"
}

Validation and CI Enforcement

Repository CI pipelines validate these conventions automatically. The name must be unique across the entire repository, and validation scripts typically enforce the kebab-case pattern using a regex such as ^[a-z0-9]+(-[a-z0-9]+)*$. Mismatches between the folder name and the name field trigger immediate CI failures.

Practical Implementation Examples

Compliant Plugin Structure

my-awesome-plugin/
└── .codex-plugin/
    └── plugin.json

Contents of plugin.json:

{
  "name": "my-awesome-plugin",
  "version": "1.0.0",
  "description": "A valid plugin manifest"
}

Non-Compliant Structure (CI Failure)

If the folder is named MyAwesomePlugin but plugin.json contains "name": "my-awesome-plugin", the validation will fail. Similarly, using underscores or spaces in either the folder name or the JSON value violates the specification.

Summary

• Kebab-case only: Use lowercase letters, numbers, and hyphens in the name field.
• No spaces: The identifier must not contain whitespace characters.
• Folder match: The directory name must exactly equal the name value in plugin.json.
• Manifest location: Place plugin.json inside .<folder>/.codex-plugin/.
• Uniqueness: Names must be unique across the openai/plugins repository.

Frequently Asked Questions

What character format is required for plugin names?

Plugin names must follow kebab-case formatting as defined in line 52 of plugin-json-spec.md. This means lowercase letters, numbers, and hyphens only, with no spaces or uppercase letters allowed.

Does the folder name need to match the plugin.json name field?

Yes, line 142 of the specification explicitly requires the plugin folder name to exactly match the name value in plugin.json. This alignment ensures the Codex system can resolve the plugin namespace correctly.

Where should the plugin.json file be located?

The manifest file must be placed at .<plugin-folder>/.codex-plugin/plugin.json within the plugin directory, following the structure used by existing plugins like coderabbit at plugins/coderabbit/.codex-plugin/plugin.json.

Can I use underscores instead of hyphens?

No, the kebab-case convention strictly requires hyphens as separators. Underscores violate the naming rules defined in the specification and will cause CI validation errors.

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