# How to Define a Plugin Manifest File for OpenAI Plugins

> Learn how to define a plugin manifest file for OpenAI plugins. This crucial JSON file details your plugin's metadata, interface, and capabilities for seamless discovery and loading.

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

---

**The OpenAI plugin manifest is a JSON file located at [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main//.agents/skills/plugin-creator/references/plugin-json-spec.md), the file must be named exactly [`plugin.json`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/./.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:

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

```

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