# What Is the Minimum Required File for a Codex Plugin?

> Discover the minimum required file for a Codex plugin the manifest file pluginjson. Learn about the essential fields name version description author and interface needed for recognition.

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

---

**The minimum required file for a Codex plugin is the manifest file located at [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json), which must contain the mandatory top-level fields `name`, `version`, `description`, `author`, and `interface` to be recognized by the evaluator.**

The [openai/plugins](https://github.com/openai/plugins) repository defines the Codex plugin architecture, where the entire plugin identity hinges on this single configuration file. Without this manifest, the evaluation system cannot recognize or load your extension. The evaluator explicitly validates the presence and structure of this file before processing any skills or capabilities.

## The Core Manifest: [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json)

According to the source code in the `openai/plugins` repository, a Codex plugin is identified solely by the presence of [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) at the plugin root. In [`plugins/plugin-eval/src/evaluators/plugin.js`](https://github.com/openai/plugins/blob/main/plugins/plugin-eval/src/evaluators/plugin.js) (lines 19–30), the evaluator checks for this file immediately upon initialization. If the manifest is absent, the system flags an error and terminates evaluation, making this file the non-negotiable foundation of every Codex plugin.

The file must reside within a directory named **`.codex-plugin`** placed at the root of your project. This directory structure separates plugin metadata from implementation code and skills.

## Required Fields in the Manifest

The evaluator validates that [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) contains five mandatory top-level fields. Omitting any of these causes validation to fail.

- **`name`**: The unique identifier for your plugin (e.g., `"my-plugin"`).
- **`version`**: Semantic version string (e.g., `"0.1.0"`).
- **`description`**: Short summary of the plugin's purpose.
- **`author`**: Object containing at minimum a `name` property, optionally including `url`.
- **`interface`**: Object defining display metadata, capabilities, and entry points for the Codex system.

Optional fields such as `logo`, `composerIcon`, or additional metadata may be included, but the evaluator only enforces the presence of the five fields above.

## Minimal Directory Structure

A valid Codex plugin requires at minimum the following structure:

```

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

```

You may optionally include a `skills/` directory containing skill definitions ([`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) files), but the [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) file alone satisfies the minimum requirement for plugin recognition.

## Complete Minimal [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) Example

The following JSON satisfies all evaluator requirements for the mandatory fields:

```json
{
  "name": "my-plugin",
  "version": "0.1.0",
  "description": "A simple Codex plugin example",
  "author": { 
    "name": "Your Name", 
    "url": "https://github.com/yourname" 
  },
  "interface": {
    "displayName": "My Plugin",
    "shortDescription": "Demo plugin",
    "longDescription": "Provides a hello-world skill for Codex.",
    "developerName": "Your Name",
    "category": "Utility",
    "capabilities": ["Read", "Write", "Interactive"],
    "websiteURL": "https://github.com/yourname/my-plugin",
    "privacyPolicyURL": "https://example.com/privacy",
    "termsOfServiceURL": "https://example.com/terms",
    "defaultPrompt": ["Say hello"]
  },
  "skills": "./skills/"
}

```

Note that while the `interface` object contains many properties in this example, the evaluator specifically checks for the existence of the `interface` field itself. You should populate all sub-fields according to your plugin's needs while ensuring the top-level required fields are present.

## Validating Your Plugin Locally

To verify that your plugin meets the minimum file requirements, run the plugin evaluator from the plugin root:

```bash
plugin-eval start . --request "List the available skills." --format markdown

```

This command invokes the evaluator defined in [`plugins/plugin-eval/src/evaluators/plugin.js`](https://github.com/openai/plugins/blob/main/plugins/plugin-eval/src/evaluators/plugin.js), which first confirms the existence of [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json), then validates the required fields before listing discoverable skills. If the manifest is missing or malformed, the tool emits an error immediately.

## Summary

- The **[`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json)** file is the sole minimum required file for any Codex plugin.
- The evaluator in [`plugins/plugin-eval/src/evaluators/plugin.js`](https://github.com/openai/plugins/blob/main/plugins/plugin-eval/src/evaluators/plugin.js) (lines 19–30) strictly enforces the presence of this manifest.
- Mandatory top-level fields include **`name`**, **`version`**, **`description`**, **`author`**, and **`interface`**.
- The file must reside inside a **`.codex-plugin/`** directory at the project root.
- Use `plugin-eval start` to validate your plugin structure against the OpenAI Codex requirements.

## Frequently Asked Questions

### What happens if [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) is missing?

The evaluator will flag an error and terminate immediately. As implemented in [`plugins/plugin-eval/src/evaluators/plugin.js`](https://github.com/openai/plugins/blob/main/plugins/plugin-eval/src/evaluators/plugin.js), the absence of this file prevents the plugin from being recognized as a valid Codex extension, regardless of other files present in the directory.

### Which fields are mandatory in the Codex plugin manifest?

The manifest must contain five top-level keys: `name`, `version`, `description`, `author`, and `interface`. The `author` field requires at minimum a `name` property, while `interface` must be a valid object defining the plugin's capabilities and metadata.

### Can I include additional optional fields in [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json)?

Yes. You may include optional fields such as `logo`, `composerIcon`, or custom metadata fields. The evaluator checks only for the required fields, ignoring additional properties that do not conflict with the schema.

### How do I test if my plugin meets the minimum requirements?

Run the `plugin-eval start . --request "List the available skills." --format markdown` command from your plugin root. This executes 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), which verifies the manifest exists and contains all required fields before processing any skills.