# How to Create a Minimal plugin.json for OpenAI Codex Plugins

> Learn to create a minimal plugin.json for your OpenAI Codex plugin. Discover the seven essential fields and how to structure your repository for easy integration.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: how-to-guide
- Published: 2026-09-11

---

**A minimal [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) requires exactly seven fields—`name`, `version`, `description`, `interface.displayName`, `interface.shortDescription`, `interface.capabilities`, and `interface.defaultPrompt`—placed inside a `.codex-plugin` folder at your repository root.**

The [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) manifest serves as the entry point for every Codex plugin in the `openai/plugins` ecosystem. This JSON file tells the Codex runtime how to discover your plugin, what capabilities it exposes, and how to render it within the ChatGPT interface. Creating a valid minimal manifest ensures your plugin passes the repository's built-in validation while remaining lean enough for rapid iteration.

## Required Fields for a Minimal plugin.json

According to the [plugin.json specification](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/references/plugin-json-spec.md) located at [`.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), the validator enforces seven mandatory fields. All other metadata—such as `author`, `homepage`, or UI assets—can be omitted for a bare-bones implementation.

- **`name`** (string): A unique, kebab-case identifier that must match your plugin's folder name.
- **`version`** (string): Semantic version (e.g., `0.1.0`) so Codex can track updates and compatibility.
- **`description`** (string): Short human-readable purpose displayed in the plugin list.
- **`interface.displayName`** (string): The user-facing title rendered in the ChatGPT interface.
- **`interface.shortDescription`** (string): Subtitle text appearing beneath the display name.
- **`interface.capabilities`** (array): Declares functional abilities such as `Write` or `Interactive`.
- **`interface.defaultPrompt`** (array): Up to three starter prompts that populate the composer UI.

The validation logic in [`plugins/plugin-eval/src/evaluators/plugin.js`](https://github.com/openai/plugins/blob/main/plugins/plugin-eval/src/evaluators/plugin.js) explicitly checks for the presence of these fields during the plugin evaluation phase.

## Minimal plugin.json Example

Place the following JSON inside [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json). This example satisfies the validator while omitting all optional fields.

```json
{
  "name": "my-sample-plugin",
  "version": "0.1.0",
  "description": "A demo plugin that showcases the minimal manifest.",
  "interface": {
    "displayName": "My Sample Plugin",
    "shortDescription": "Demo plugin with only required fields",
    "capabilities": ["Write"],
    "defaultPrompt": [
      "Summarize the latest project updates."
    ]
  }
}

```

The `name` field must use kebab-case and match your repository folder name exactly. The `version` field expects semantic versioning to ensure proper update tracking across the Codex runtime.

## Directory Structure and File Placement

The Codex runtime searches for the manifest inside a hidden folder at your repository root. You must create `.codex-plugin/` and save the manifest as [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) within it.

```

my-sample-plugin/
├─ .codex-plugin/
│   └─ plugin.json    ← minimal manifest location
└─ skills/
    └─ ...            ← skill implementations

```

As implemented in `openai/plugins`, the runtime recursively scans for this specific path to identify valid plugin packages. The helper script at [`.agents/skills/plugin-creator/scripts/create_basic_plugin.py`](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/scripts/create_basic_plugin.py) automatically generates this directory structure when scaffolding new plugins.

## Validation and Schema Enforcement

The repository enforces manifest compliance through [`plugins/plugin-eval/src/evaluators/plugin.js`](https://github.com/openai/plugins/blob/main/plugins/plugin-eval/src/evaluators/plugin.js). This evaluator throws validation errors if any required fields are missing or malformed. For instance, the script checks that `interface.capabilities` is a non-empty array and that `interface.defaultPrompt` contains no more than three entries.

Running the repository's validation suite against your [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) confirms it meets the minimal requirements before deployment.

## Optional Fields for Enhanced UI

While not required for functionality, you can enrich the user interface by adding UI assets to the `interface` object. All asset paths are relative to the plugin root and must use PNG format for screenshots.

```json
{
  "name": "my-sample-plugin",
  "version": "0.1.0",
  "description": "A demo plugin with UI assets.",
  "interface": {
    "displayName": "My Sample Plugin",
    "shortDescription": "Enhanced demo with branding",
    "capabilities": ["Write"],
    "defaultPrompt": ["Generate a project summary."],
    "brandColor": "#3B82F6",
    "composerIcon": "./assets/icon.png",
    "logo": "./assets/logo.png",
    "screenshots": [
      "./assets/screenshot1.png",
      "./assets/screenshot2.png"
    ]
  }
}

```

Fields like `brandColor` and `screenshots` improve discoverability but are safely omitted when creating a minimal viable plugin.

## Summary

- A minimal [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) requires **seven specific fields**: `name`, `version`, `description`, and four nested under `interface` (`displayName`, `shortDescription`, `capabilities`, `defaultPrompt`).
- Place the manifest inside a **`.codex-plugin/`** folder at your repository root.
- The validator at [`plugins/plugin-eval/src/evaluators/plugin.js`](https://github.com/openai/plugins/blob/main/plugins/plugin-eval/src/evaluators/plugin.js) enforces these requirements during the evaluation pipeline.
- Use the scaffolding script at [`.agents/skills/plugin-creator/scripts/create_basic_plugin.py`](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/scripts/create_basic_plugin.py) to generate compliant templates automatically.
- UI assets and metadata like `author` or `homepage` are optional and do not affect core functionality.

## Frequently Asked Questions

### What is the exact file path for plugin.json in a Codex plugin?

The manifest must reside at [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) relative to your repository root. The Codex runtime specifically searches this hidden directory to load plugin metadata, as documented in the [plugin.json spec](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/references/plugin-json-spec.md).

### Can I use YAML instead of JSON for the plugin manifest?

No. The validator in [`plugins/plugin-eval/src/evaluators/plugin.js`](https://github.com/openai/plugins/blob/main/plugins/plugin-eval/src/evaluators/plugin.js) strictly expects a [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) file using valid JSON syntax. The runtime parses this file directly during plugin discovery and does not support YAML or alternative configuration formats.

### How does the name field in plugin.json relate to my repository?

The `name` field must use kebab-case formatting (lowercase with hyphens) and match your plugin's folder name exactly. This requirement ensures unique identification across the `openai/plugins` ecosystem and prevents namespace collisions during runtime resolution.

### What happens if I omit optional fields like author or homepage?

Omitting optional fields does not break plugin functionality. The validator only checks for the seven required fields listed in the specification. You can safely exclude `author`, `homepage`, `license`, and UI assets when creating a minimal plugin, then add them later as your project matures.