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

> Learn how to create an OpenAI plugin manifest file (.codex-plugin/plugin.json). This JSON config guides the Codex platform to discover, load, and present your plugin effectively.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: how-to-guide
- Published: 2026-06-27

---

**The OpenAI plugin manifest is a JSON configuration file located at [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/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.

```json
{
  "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"
    ]
  }
}

```

## 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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.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.