How to Define a Plugin Manifest File for OpenAI Plugins

The OpenAI plugin manifest is a JSON file located at .codex-plugin/plugin.json that defines the metadata, interface, and capabilities required for the Codex platform to discover, load, and present your plugin.

Every plugin in the openai/plugins repository requires a manifest file to function within the Codex ecosystem. This JSON configuration serves as the single source of truth for how your plugin is identified, displayed, and executed. Understanding how to define a plugin manifest file for OpenAI plugins correctly ensures your integration appears properly in the marketplace and loads without errors.

File Location and Naming Requirements

The manifest must reside in a specific location to be recognized by the Codex discovery system. According to the specification in /.agents/skills/plugin-creator/references/plugin-json-spec.md, the file must be named exactly plugin.json and placed inside a hidden folder named .codex-plugin at the root of your plugin folder.

Key constraints include:

• The name field must match the containing folder name using kebab-case notation (e.g., my-awesome-plugin)
• All path values must be relative to the plugin root and start with ./
• Asset files must reside under ./assets/ and use PNG format

Required Manifest Structure

The manifest follows a strict JSON schema divided into three main sections: top-level metadata, interface configuration, and optional component paths.

Top-Level Metadata Fields

These fields provide basic identification and versioning information:

• name: The plugin identifier (must match folder name, kebab-case, no spaces)
• version: Semantic version string (e.g., 0.1.0)
• description: Brief explanation of plugin functionality
• author: Object containing name, email, and url
• homepage and repository: URLs for project resources
• license: SPDX license identifier
• keywords: Array of searchable tags

The Interface Block

The interface object drives the plugin card shown in the Codex UI. It includes:

• displayName: Human-readable title
• shortDescription: One-line subtitle for listings
• longDescription: Detailed explanation for the details page
• developerName: Organization or individual responsible
• category: Classification (e.g., "Productivity")
• capabilities: Array of features (e.g., ["Interactive", "Write"])
• websiteURL, privacyPolicyURL, termsOfServiceURL: Legal and support links
• defaultPrompt: Array of up to three example prompts (128 characters each)
• brandColor: Hex color code for UI theming
• composerIcon, logo, screenshots: Asset paths under ./assets/

Optional Component Paths

The manifest supports several optional fields pointing to additional functionality:

• skills: Path to skill definitions (e.g., ./skills/)
• apps: Path to app configuration (e.g., ./.app.json)
• hooks: Path to hook implementations
• mcpServers: Path to MCP server configurations

Complete Manifest Example

Below is a minimal, production-ready manifest that satisfies all requirements. This example includes the required fields and a basic interface configuration:

{
  "name": "my-awesome-plugin",
  "version": "0.1.0",
  "description": "A brief description of what the plugin does",
  "author": {
    "name": "Your Name or Org",
    "email": "you@example.com",
    "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"
    ]
  }
}

Asset Requirements and Conventions

Asset management follows strict conventions to ensure consistent rendering across the Codex platform. All visual assets must be stored in the ./assets/ directory relative to the plugin root.

Requirements include:

• Format: All images must be PNG files
• Paths: Must use relative paths starting with ./ (e.g., ./assets/logo.png)
• Screenshots: Array of paths showcasing plugin functionality
• Icons: composerIcon for the composer interface, logo for marketplace listings

The defaultPrompt field accepts an array of strings, but only the first three entries are displayed in the UI, with each entry limited to 128 characters.

Real-World Reference Implementations

The openai/plugins repository contains canonical examples demonstrating various manifest configurations:

• FINN (plugins/finn/.codex-plugin/plugin.json): A comprehensive implementation showing all optional fields, including dark-mode assets and the apps configuration
• Brand24 (plugins/brand24/.codex-plugin/plugin.json): A concise example focusing on essential UI metadata and branding assets
• Specification (/.agents/skills/plugin-creator/references/plugin-json-spec.md): The definitive schema reference containing detailed type notes and validation rules

These files demonstrate how the manifest drives discovery (indexing name and interface fields), loading (resolving skills paths), and presentation (rendering plugin cards from the interface block).

Summary

• Location: Create .codex-plugin/plugin.json at your plugin root
• Naming: Ensure the name field matches your folder name in kebab-case
• Paths: Use relative paths starting with ./ for all file references
• Assets: Store PNG files in ./assets/ and reference them in the interface block
• Interface: Configure displayName, descriptions, and screenshots to control marketplace appearance
• Validation: Reference the spec at /.agents/skills/plugin-creator/references/plugin-json-spec.md for schema details

Frequently Asked Questions

What happens if the plugin name doesn't match the folder name?

The Codex platform uses the folder name as the canonical identifier. If the name field in plugin.json does not match the containing folder name, the plugin may fail validation or not appear in the marketplace discovery system. Always ensure the name value uses kebab-case and exactly matches the directory name.

Can I use absolute URLs for assets or skills paths?

No. The manifest specification requires all path values to be relative to the plugin root and must start with ./. Absolute paths or paths without the ./ prefix will not resolve correctly when the platform loads your plugin components.

How does the defaultPrompt field work in the interface?

The defaultPrompt array provides example prompts that appear in the Codex UI to help users understand your plugin's capabilities. Only the first three strings in the array are displayed, and each entry must not exceed 128 characters. These prompts serve as quick-start suggestions for users interacting with your plugin.

Where can I find the complete schema specification for the manifest?

The complete JSON schema and validation rules are documented in /.agents/skills/plugin-creator/references/plugin-json-spec.md within the openai/plugins repository. This file contains the canonical specification for every field, including type definitions and formatting requirements.

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