How to Create a New Codex Plugin with Manifest Files: A Complete Guide

To create a new Codex plugin with manifest files, you must create a service-specific .app.json file and a Codex-level .codex-plugin/plugin.json manifest, then populate a skills/ directory with skill bundles that Codex can discover.

A Codex plugin is a self-contained package that enables Codex to interact with external services like Zoom, Notion, or Figma. In the openai/plugins repository, every plugin follows a standardized two-file manifest structure that defines the plugin's identity, capabilities, and entry points. This guide walks through the exact files, directory structure, and configuration required to build a compliant plugin.

Understanding the Two-File Manifest Structure

Every Codex plugin in the repository relies on two core manifest files that serve distinct purposes:

• .app.json – Stores service-specific identifiers such as OAuth client IDs and app credentials required by the service connector. Located at the plugin root (e.g., plugins/zoom/.app.json).
• .codex-plugin/plugin.json – Supplies Codex-level metadata including the plugin name, version, description, author information, UI configuration, and paths to skill collections. Located at plugins/zoom/.codex-plugin/plugin.json.

These files work together to authenticate with external APIs while presenting a unified interface to Codex users.

Step-by-Step Creation Workflow

1. Create the Plugin Directory

Start by creating a top-level folder for your plugin within the plugins/ directory:

mkdir plugins/my-service

2. Add the Service-Specific Manifest

Create .app.json at the plugin root. This file contains an "apps" object keyed by your service name, holding credentials like app IDs:

{
  "apps": {
    "my-service": {
      "id": "asdk_app_1234567890abcdef"
    }
  }
}

3. Configure the Codex Plugin Manifest

Create .codex-plugin/plugin.json with the required metadata fields. This is the authoritative source Codex reads when installing your plugin:

{
  "name": "my-service",
  "version": "0.1.0",
  "description": "Expose My Service APIs to Codex.",
  "author": {
    "name": "My Company",
    "url": "https://github.com/my-company"
  },
  "homepage": "https://myservice.com",
  "repository": "https://github.com/my-company/my-service-plugin",
  "license": "MIT",
  "keywords": [
    "my-service",
    "codex-plugin",
    "connector"
  ],
  "apps": "./.app.json",
  "skills": "./skills/",
  "interface": {
    "displayName": "My Service",
    "shortDescription": "Interact with My Service from Codex.",
    "longDescription": "This plugin lets Codex read and write data in My Service, providing commands, skills, and webhooks for automation.",
    "developerName": "My Company",
    "category": "Productivity",
    "capabilities": ["Read", "Write"],
    "websiteURL": "https://myservice.com",
    "privacyPolicyURL": "https://myservice.com/privacy",
    "termsOfServiceURL": "https://myservice.com/terms",
    "defaultPrompt": [
      "Show me the latest reports from My Service.",
      "Create a new project named 'Alpha' in My Service."
    ],
    "brandColor": "#FF6600",
    "composerIcon": "./assets/icon.svg",
    "logo": "./assets/logo.png",
    "screenshots": [
      "./assets/screenshot-1.png",
      "./assets/screenshot-2.png"
    ]
  }
}

4. Add Assets

Create an optional assets/ folder for icons and screenshots referenced in the interface field. The Zoom plugin stores SVG icons and PNG screenshots under plugins/zoom/assets/.

5. Define Skills

Create a skills/ directory containing skill bundles. Each skill resides in its own subfolder and must contain a SKILL.md file with YAML front-matter describing the skill's purpose, intent aliases, and required tooling:

---
name: "example"
description: "A simple example skill for My Service."
retrieval:
  aliases: ["example", "demo"]
  intents: ["example"]
  entities: []
---

# Example Skill

This skill demonstrates how to call the My Service API.

Using the Scaffold Helper Script

The repository includes a utility script to automate the skeleton creation. Located at .agents/skills/plugin-creator/scripts/create_basic_plugin.py, this script generates the folder structure, manifest files, and placeholder assets:

python3 .agents/skills/plugin-creator/scripts/create_basic_plugin.py \
    --name my-service \
    --author "My Company" \
    --description "Connect Codex to My Service"

The script creates:

• The plugin root directory
• .app.json with stub configuration
• .codex-plugin/plugin.json with default metadata
• assets/ folder with placeholder icons
• skills/example/ directory with a sample SKILL.md

Directory Structure Overview

After completing the steps above, your plugin structure should match this layout:

plugins/my-service/
├─ .app.json
├─ .codex-plugin/
│  └─ plugin.json
├─ assets/
│  ├─ icon.svg
│  └─ logo.png
└─ skills/
   └─ example/
      └─ SKILL.md

Summary

• Create a new Codex plugin with manifest files by establishing a two-file configuration: .app.json for service credentials and .codex-plugin/plugin.json for Codex metadata.
• Place skill definitions in a skills/ directory, with each skill containing a SKILL.md file featuring YAML front-matter for discovery.
• Use the scaffold script at .agents/skills/plugin-creator/scripts/create_basic_plugin.py to generate boilerplate files automatically.
• Store visual assets in an assets/ folder and reference them in the interface configuration of plugin.json.
• Commit the complete folder structure to the openai/plugins repository to make the plugin discoverable.

Frequently Asked Questions

What is the difference between .app.json and plugin.json?

The .app.json file contains service-specific identifiers like OAuth client IDs and app credentials required to authenticate with the external API, while the .codex-plugin/plugin.json file defines the plugin's metadata, UI presentation, and skill locations for Codex consumption. According to the openai/plugins source code, Codex reads plugin.json as the authoritative manifest during installation, which then references .app.json for authentication details.

How do I define skills for my Codex plugin?

Skills reside in the skills/ directory, with each skill in its own subfolder containing a SKILL.md file. This file must include YAML front-matter specifying the skill name, description, retrieval aliases, intents, and entities. Codex uses this front-matter to discover and invoke the appropriate capabilities when users interact with your plugin.

Can I automate the creation of a new Codex plugin?

Yes. The repository provides a scaffold helper script at .agents/skills/plugin-creator/scripts/create_basic_plugin.py that accepts --name, --author, and --description arguments to generate the complete directory structure, manifest files, and placeholder assets. This script ensures your plugin follows the canonical structure used by existing plugins like Zoom in the repository.

What fields are required in the plugin.json interface configuration?

The interface object in plugin.json requires displayName, shortDescription, category, capabilities, and brandColor at minimum, though production plugins should also include privacyPolicyURL, termsOfServiceURL, composerIcon, and screenshots for marketplace compliance. As implemented in openai/plugins, these fields control how the plugin appears in the Codex interface and marketplace listings.

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