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

A minimal 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 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 located at .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 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. This example satisfies the validator while omitting all optional fields.

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

{
  "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 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 enforces these requirements during the evaluation pipeline.
• Use the scaffolding script at .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 relative to your repository root. The Codex runtime specifically searches this hidden directory to load plugin metadata, as documented in the plugin.json spec.

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

No. The validator in plugins/plugin-eval/src/evaluators/plugin.js strictly expects a 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.

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