How to Create an OpenAI Plugin Manifest File (`.codex-plugin/plugin.json`)

The OpenAI plugin manifest is a JSON configuration file located at .codex-plugin/plugin.json that tells the Codex platform how to discover, load, and present your plugin through metadata, interface definitions, and component paths.

Every plugin in the openai/plugins repository requires this manifest file at its root to integrate with the Codex ecosystem. This document serves as the single source of truth for plugin identification, versioning, and UI presentation. The manifest follows a strict JSON schema defined in the repository's specification file.

Required File Structure and Location

The manifest must reside at a specific path relative to your plugin's root directory. Create a hidden folder named .codex-plugin and place a file named exactly plugin.json inside it.

The name field must match the containing folder name using kebab-case formatting without spaces. This alignment ensures Codex can correctly index your plugin during the discovery phase. All path values in the manifest must be relative to the plugin root and start with ./ (for example, ./assets/icon.png).

Top-Level Metadata Fields

The root of the JSON object contains essential identifiers and publication details. These fields declare the plugin's version, authorship, licensing, and repository location.

Key top-level fields include:

• name – The plugin identifier matching the folder name
• version – Semantic versioning string (e.g., "0.1.0")
• description – Brief summary of functionality
• author – Object containing name, email, and url
• homepage and repository – URLs for documentation and source code
• license – SPDX license identifier
• keywords – Array of searchable tags

Interface Configuration for UI Presentation

The interface object drives the plugin card displayed in the Codex marketplace. This block contains user-facing metadata that determines how your plugin appears in search results and detail pages.

Required interface fields include:

• displayName – Human-readable title shown in the UI
• shortDescription – One-line subtitle for plugin cards
• longDescription – Detailed explanation of capabilities and use cases
• developerName – Organization or individual responsible for the plugin
• category – Classification for marketplace filtering (e.g., "Productivity")
• capabilities – Array of features (e.g., ["Interactive", "Write"])
• brandColor – Hex color code for UI theming
• composerIcon and logo – Paths to PNG assets under ./assets/

The defaultPrompt field provides up to three prompt strings that appear in the Codex interface to guide users. Only the first three entries are displayed, and each string must not exceed 128 characters. All visual assets must be PNG files stored under ./assets/ relative to the plugin root.

Legal and support URLs must also be specified:

• websiteURL
• privacyPolicyURL
• termsOfServiceURL

Optional Component Paths

The manifest supports optional keys pointing to additional plugin components:

• skills – Path to directory containing skill definitions (e.g., "./skills/")
• apps – Path to application configuration (e.g., "./.app.json")
• hooks – Path to lifecycle hook implementations
• mcpServers – Path to Model Context Protocol server configurations

When a user invokes a skill, Codex loads the corresponding files referenced by these paths relative to the manifest location.

Complete Manifest Example

Below is a minimal, production-ready manifest that demonstrates proper field structure and relative path formatting. This example includes all required top-level fields and a comprehensive interface block.

{
  "name": "my-awesome-plugin",
  "version": "0.1.0",
  "description": "A brief description of what the plugin does",
  "author": {
    "name": "Your Name or Org",
    "email": "[email protected]",
    "url": "https://github.com/your-org"
  },
  "homepage": "https://github.com/your-org/my-awesome-plugin",
  "repository": "https://github.com/your-org/my-awesome-plugin",
  "license": "MIT",
  "keywords": ["myplugin", "example"],
  "skills": "./skills/",
  "apps": "./.app.json",
  "interface": {
    "displayName": "My Awesome Plugin",
    "shortDescription": "One-line subtitle",
    "longDescription": "A longer description that appears on the details page, explaining capabilities and use-cases.",
    "developerName": "Your Name or Org",
    "category": "Productivity",
    "capabilities": ["Interactive", "Write"],
    "websiteURL": "https://your-plugin.example.com",
    "privacyPolicyURL": "https://your-plugin.example.com/privacy",
    "termsOfServiceURL": "https://your-plugin.example.com/terms",
    "defaultPrompt": [
      "Summarize the latest report",
      "Generate a quick draft"
    ],
    "brandColor": "#5A67D8",
    "composerIcon": "./assets/icon.png",
    "logo": "./assets/logo.png",
    "screenshots": [
      "./assets/screenshot1.png",
      "./assets/screenshot2.png"
    ]
  }
}

Real-World Reference Files

Study existing implementations in the openai/plugins repository to understand practical conventions:

• .agents/skills/plugin-creator/references/plugin-json-spec.md – The canonical JSON schema specification defining every field type and validation rule
• plugins/finn/.codex-plugin/plugin.json – A fully-featured implementation demonstrating all optional fields, dark-mode assets, and the apps configuration
• plugins/brand24/.codex-plugin/plugin.json – A concise example focusing on minimal required UI metadata and branding assets

Summary

• Place your manifest file at .codex-plugin/plugin.json relative to the plugin root
• Match the name field exactly to the containing folder using kebab-case
• Store all PNG assets under ./assets/ and reference them with relative paths starting with ./
• Include only the first three strings in defaultPrompt, each limited to 128 characters
• Define the interface block completely to ensure proper rendering in the Codex marketplace
• Reference the specification at .agents/skills/plugin-creator/references/plugin-json-spec.md for validation rules

Frequently Asked Questions

What is the exact file path for the OpenAI plugin manifest?

The manifest must be located at .codex-plugin/plugin.json relative to the plugin's root directory. Codex specifically scans for this hidden folder and file name pattern during the discovery phase, as implemented in the openai/plugins repository indexing logic.

How does the name field relate to the folder structure?

The name field must exactly match the containing folder name using kebab-case formatting without spaces. This alignment ensures Codex can correctly index and reference your plugin within the marketplace without path resolution errors.

What are the requirements for plugin images and screenshots?

All visual assets must be PNG files stored under ./assets/ relative to the plugin root. The interface block references these using relative paths starting with ./, including composerIcon, logo, and items in the screenshots array.

What is the purpose of the defaultPrompt field?

This field provides up to three prompt strings that appear in the Codex interface to guide users on plugin capabilities. Only the first three entries are displayed, and each string must not exceed 128 characters according to the official specification.

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