# Plugin Naming Conventions for the OpenAI Plugins Repository

> Learn the essential naming conventions for new plugins in the openai plugins repository. Ensure your plugin folder name matches your plugin JSON name for seamless integration.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: best-practices
- Published: 2026-09-10

---

**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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/plugins/coderabbit/.codex-plugin/plugin.json). The `name` field inside this file must exactly mirror the parent directory name.

```json
// 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

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

```

Contents of [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json):

```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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/plugin.json).
- **Manifest location**: Place [`plugin.json`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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.