What Is the Minimum Required File for a Codex Plugin?

The minimum required file for a Codex plugin is the manifest file located at .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 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

According to the source code in the openai/plugins repository, a Codex plugin is identified solely by the presence of .codex-plugin/plugin.json at the plugin root. In 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 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 files), but the .codex-plugin/plugin.json file alone satisfies the minimum requirement for plugin recognition.

Complete Minimal plugin.json Example

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

{
  "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:

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

This command invokes the evaluator defined in plugins/plugin-eval/src/evaluators/plugin.js, which first confirms the existence of .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 file is the sole minimum required file for any Codex plugin.
• The evaluator in 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 is missing?

The evaluator will flag an error and terminate immediately. As implemented in 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?

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, which verifies the manifest exists and contains all required fields before processing any skills.

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