Creating a .codex-plugin/plugin.json Manifest File for OpenAI Codex Plugins

A Codex plugin requires a .codex-plugin/plugin.json manifest file that defines the plugin's metadata, UI presentation, and capabilities according to the JSON schema specification in the OpenAI Plugins repository.

The OpenAI Plugins repository provides a standardized framework for building custom Codex plugins. Every plugin must include a .codex-plugin/plugin.json manifest file that enables the Codex runtime to discover, render, and execute the plugin's functionality. This guide walks through the directory structure, schema requirements, and automation tools available in the openai/plugins repository.

Required Directory Structure

Create a dedicated folder under plugins/ with your chosen plugin name. The repository requires a specific layout where the manifest file lives inside a hidden .codex-plugin/ directory.

plugins/<my-plugin>/
    .codex-plugin/
        plugin.json
    assets/               # optional UI assets (icons, screenshots)

    skills/               # optional skill implementations

    .app.json             # optional app integration manifest

    .mcp.json             # optional MCP server descriptor

The repository's README.md describes this layout and confirms that the .codex-plugin/plugin.json file is mandatory for the Codex runtime to recognize the plugin.

Manifest Schema and Required Fields

The manifest must follow the JSON schema documented in .agents/skills/plugin-creator/references/plugin-json-spec.md. The top-level fields include:

• name: Kebab-case identifier (e.g., my-plugin).
• version: Semantic version string.
• description: Short purpose summary.
• author: Object with name, email, and url.
• homepage: Documentation URL.
• repository: Source-code URL.
• license: SPDX license identifier.
• keywords: Search tags for discovery.
• apps: Path to the optional .app.json file.
• interface: UI-presentation block containing display names, descriptions, icons, and categories.

Interface Configuration

The interface object contains the fields that the Codex UI reads to render the plugin in the marketplace and composer. Required sub-fields include:

• displayName: Human-readable name shown in the UI.
• shortDescription: One-line subtitle.
• longDescription: Detailed markdown description of capabilities.
• category: Classification such as Research or Productivity.
• defaultPrompt: Array of suggested prompts to help users get started.
• composerIcon: Relative path to the icon displayed in the composer (e.g., ./assets/app-icon.png).
• logo: Relative path to the logo used in the marketplace.

Additional fields include developerName, capabilities, screenshots, websiteURL, privacyPolicyURL, and termsOfServiceURL.

Real-World Examples from the Repository

The openai/plugins repository provides production-ready examples that demonstrate the schema in practice.

Readwise Plugin Example

The Readwise plugin at plugins/readwise/.codex-plugin/plugin.json implements a complete Research category manifest:

{
  "name": "readwise",
  "version": "1.0.1",
  "description": "The official app for Readwise and Reader.",
  "author": {
    "name": "Readwise Inc.",
    "url": "https://readwise.io"
  },
  "repository": "https://github.com/openai/plugins",
  "license": "MIT",
  "keywords": [],
  "apps": "./.app.json",
  "interface": {
    "displayName": "Readwise",
    "shortDescription": "The official app for Readwise and Reader.",
    "longDescription": "The official app for Readwise and Reader. \n\nThis app allows you to have Codex semantically search through all of your highlights, and any content saved to your Reader library.\n\nMore than that, it can do basically anything you can do in Reader! Triage your inbox, organize your library, catch up on your feed, and much more -- just ask :)",
    "developerName": "Readwise Inc.",
    "category": "Research",
    "capabilities": [],
    "defaultPrompt": [
      "Find the most relevant highlights in Readwise"
    ],
    "screenshots": [],
    "websiteURL": "https://readwise.io",
    "privacyPolicyURL": "https://readwise.io/privacy",
    "termsOfServiceURL": "https://readwise.io/tos",
    "composerIcon": "./assets/app-icon.png",
    "logo": "./assets/app-icon.png"
  },
  "homepage": "https://readwise.io"
}

Monday.com Plugin Example

The Monday.com plugin at plugins/monday-com/.codex-plugin/plugin.json shows a Productivity category implementation:

{
  "name": "monday-com",
  "version": "1.0.1",
  "description": "A powerful MCP connector enabling AI agents to seamlessly interact with monday.com.",
  "author": {
    "url": "https://monday.com",
    "name": "Monday.com"
  },
  "homepage": "https://monday.com",
  "repository": "https://github.com/openai/plugins",
  "license": "MIT",
  "keywords": [],
  "apps": "./.app.json",
  "interface": {
    "displayName": "Monday.com",
    "shortDescription": "A powerful MCP connector enabling AI agents to seamlessly interact with monday.com.",
    "longDescription": "...",
    "category": "Productivity",
    "capabilities": [],
    "websiteURL": "https://monday.com",
    "privacyPolicyURL": "https://monday.com/l/privacy/privacy-policy/",
    "defaultPrompt": [
      "Check the marketing campaign status in monday.com"
    ],
    "screenshots": [],
    "composerIcon": "./assets/app-icon.png",
    "logo": "./assets/app-icon.png",
    "developerName": "Monday.com"
  }
}

Automating Plugin Creation with the Scaffold Script

The repository ships a helper script at .agents/skills/plugin-creator/scripts/create_basic_plugin.py that automates the creation of the directory structure and manifest file.

The script performs the following actions:

1. Normalizes and validates the plugin name.
2. Creates the directory tree including optional skills/, assets/, .mcp.json, and .app.json files.
3. Writes a placeholder .codex-plugin/plugin.json populated with the fields outlined in the specification.
4. Optionally updates a marketplace.json file for discovery.

Run the script from the repository root:

python3 .agents/skills/plugin-creator/scripts/create_basic_plugin.py my-plugin \
  --with-assets --with-skills --with-apps --with-marketplace

After execution, edit the generated plugins/my-plugin/.codex-plugin/plugin.json to replace the [TODO] placeholders with your actual metadata.

Asset Handling and Path References

If you provide UI assets such as icons, logos, or screenshots, place them under the assets/ directory and reference them relative to the plugin root. The Readwise and Monday.com examples both use "./assets/app-icon.png" for the composerIcon and logo fields. These assets are bundled with the plugin and displayed in the Codex plugin marketplace.

Registering Your Plugin in the Marketplace

For a plugin to be discoverable by Codex, its entry must appear in a marketplace.json file. The scaffold script can automatically insert an entry with the appropriate installPolicy, authPolicy, and category. The marketplace registration connects your .codex-plugin/plugin.json manifest to the Codex UI discovery system.

Summary

• Create a directory under plugins/<name>/ with a .codex-plugin/ subdirectory.
• Add a plugin.json file that follows the schema defined in .agents/skills/plugin-creator/references/plugin-json-spec.md.
• Include required metadata: name, version, description, author, interface, and asset paths.
• Use the scaffold script .agents/skills/plugin-creator/scripts/create_basic_plugin.py to generate boilerplate automatically.
• Register in marketplace.json to make the plugin discoverable in the Codex UI.

Frequently Asked Questions

What is the purpose of the .codex-plugin/plugin.json file?

The .codex-plugin/plugin.json file serves as the mandatory metadata manifest that allows the Codex runtime to discover your plugin, understand its capabilities, and render it properly in the user interface. Without this file in the correct location, the Codex system cannot recognize or load your plugin.

Can I create a Codex plugin without using the scaffold script?

Yes, you can manually create the directory structure and write the JSON file. However, using .agents/skills/plugin-creator/scripts/create_basic_plugin.py ensures you follow the correct naming conventions, directory layout, and schema requirements while generating placeholder values that guide you through the required fields.

Where should I place icons and images for my plugin?

Place all UI assets in an assets/ folder at the root of your plugin directory. Reference these files in your plugin.json using relative paths such as "./assets/app-icon.png" for the composerIcon and logo fields, as demonstrated in the Readwise and Monday.com examples.

What fields are required in the interface object of the manifest?

The interface object requires displayName, shortDescription, longDescription, category, defaultPrompt, composerIcon, and logo to properly render in the Codex UI. You should also include developerName, websiteURL, and privacyPolicyURL to meet the marketplace listing requirements specified in the plugin JSON schema.

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