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

> Learn to create a new Codex plugin with manifest files. This guide details setting up manifest files and populating a skills directory for discoverable integration.

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

---

**To create a new Codex plugin with manifest files, you must create a service-specific [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) file and a Codex-level [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/plugins/zoom/.app.json)).
- **[`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/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:

```bash
mkdir plugins/my-service

```

### 2. Add the Service-Specific Manifest

Create [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) at the plugin root. This file contains an `"apps"` object keyed by your service name, holding credentials like app IDs:

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

```

### 3. Configure the Codex Plugin Manifest

Create [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) with the required metadata fields. This is the authoritative source Codex reads when installing your plugin:

```json
{
  "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`](https://github.com/openai/plugins/blob/main/SKILL.md) file with YAML front-matter describing the skill's purpose, intent aliases, and required tooling:

```markdown
---
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`](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/scripts/create_basic_plugin.py), this script generates the folder structure, manifest files, and placeholder assets:

```bash
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`](https://github.com/openai/plugins/blob/main/.app.json) with stub configuration
- [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) with default metadata
- `assets/` folder with placeholder icons
- `skills/example/` directory with a sample [`SKILL.md`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.app.json) for service credentials and [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) for Codex metadata.
- Place skill definitions in a `skills/` directory, with each skill containing a [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) file featuring YAML front-matter for discovery.
- Use the scaffold script at [`.agents/skills/plugin-creator/scripts/create_basic_plugin.py`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.app.json) and [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json)?

The [`.app.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/plugin.json) as the authoritative manifest during installation, which then references [`.app.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/plugin.json) interface configuration?

The `interface` object in [`plugin.json`](https://github.com/openai/plugins/blob/main/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.