How to Get Started with Developing OpenAI Plugins: A Complete Guide for 2024

Developing OpenAI plugins requires creating a manifest-driven package in the plugins/<plugin-name>/ directory, complete with a .codex-plugin/plugin.json file and optional skills, hooks, or assets folders that integrate with the Codex runtime.

The openai/plugins repository provides the official framework and scaffolding tools for building extensions that enhance ChatGPT and Codex capabilities. Every plugin follows a standardized architecture where a JSON manifest defines metadata, capabilities, and UI integration points, while modular components handle specific functionality like API calls or event-driven actions.

Understanding the OpenAI Plugin Architecture

OpenAI plugins operate on a manifest-driven architecture that separates configuration from implementation. Each plugin resides in its own folder under plugins/<plugin-name>/ and must contain a .codex-plugin/plugin.json file describing its metadata, assets, and capabilities.

The architecture supports five optional component types:

• Skills (plugins/<plugin-name>/skills/) — JSON or YAML-defined actions that expose API calls to the Codex runtime
• Hooks (plugins/<plugin-name>/hooks.json) — Event-driven callbacks triggered during lifecycle events like installation or authentication
• MCP servers (plugins/<plugin-name>/.mcp.json) — Multi-Channel-Protocol definitions for connecting external services
• Apps (plugins/<plugin-name>/.app.json) — UI integrations for the Composer interface or custom widgets
• Assets (plugins/<plugin-name>/assets/) — Icons, logos, and screenshots referenced by the manifest

The plugin.json manifest follows the Plugin JSON spec and includes an interface object that controls how the plugin appears in the Codex UI, including display names, descriptions, icons, and default prompts.

Scaffolding Your First OpenAI Plugin

OpenAI provides a Plugin-Creator skill that automates boilerplate generation. Located at .agents/skills/plugin-creator/scripts/create_basic_plugin.py, this script generates the complete folder structure and placeholder files required for a valid plugin.

Run the scaffold command from the repository root:

python3 .agents/skills/plugin-creator/scripts/create_basic_plugin.py my-plugin

The script normalizes the plugin name to kebab-case (my-plugin) and creates the mandatory .codex-plugin/plugin.json with placeholder values for every required field. You can extend the scaffold with optional flags:

• --with-marketplace — Adds or updates the marketplace configuration file
• --with-skills — Creates the skills/ subdirectory for skill definitions
• --with-hooks — Generates the hooks.json for event callbacks
• --with-assets — Initializes the assets/ folder for icons and images

The scaffold also generates deep-link URLs in the format codex://plugins/<name>?marketplacePath=…, allowing direct sharing and installation from the Codex app.

Building Skills for Your Plugin

Skills are the functional units that enable Codex to interact with external APIs. Each skill lives in plugins/<plugin-name>/skills/<skill-name>/ and requires an agents/openai.yaml file defining the OpenAI-compatible JSON schema for inputs and outputs.

A minimal skill directory structure looks like this:

plugins/my-plugin/skills/hello-world/
├─ agents/
│  └─ openai.yaml   # Schema definition

└─ scripts/
   └─ hello.py      # Implementation

The openai.yaml defines the contract between Codex and your code:

name: get_current_weather
description: Retrieve the current weather for a city.
input:
  type: object
  required: [city]
  properties:
    city:
      type: string
      description: Name of the city
output:
  type: object
  properties:
    temperature:
      type: number
      description: Temperature in Celsius
    condition:
      type: string
      description: Weather description

Implementation scripts can use any programming language. Python implementations read JSON from stdin and write results to stdout:

import sys, json

def main():
    data = json.load(sys.stdin)
    city = data["city"]
    # Implementation logic here

    print(json.dumps({
        "temperature": 22,
        "condition": "Sunny"
    }))

if __name__ == "__main__":
    main()

After creating skills, reference them in your plugin.json by adding the skills property pointing to your skills directory:

"skills": "./skills/"

Validating and Testing Locally

Before publishing, validate your plugin manifest and skill definitions using the built-in validator:

python3 .agents/skills/plugin-creator/scripts/quick_validate.py \
  .agents/skills/plugin-creator

Codex automatically loads any plugin located under the plugins/ directory, enabling immediate local testing. Iterate by editing the placeholder fields in .codex-plugin/plugin.json and refining your skill implementation scripts until the integration behaves as expected.

Publishing to the Plugin Marketplace

Plugins can be distributed as personal installations or team-wide deployments. Personal plugins install to ~/.agents/plugins/marketplace.json, while team plugins reside in the repository's .agents/plugins/marketplace.json.

The marketplace file enumerates available plugins and defines installation policies (such as AVAILABLE or ON_INSTALL). To publish, copy your plugin folder to the appropriate marketplace location, update the marketplace JSON to include your plugin entry, and commit the changes. Once indexed, the plugin becomes discoverable to all Codex users with access to that marketplace.

Summary

• Developing OpenAI plugins centers on creating a .codex-plugin/plugin.json manifest in a dedicated folder under plugins/<name>/
• Use the Plugin-Creator skill at .agents/skills/plugin-creator/scripts/create_basic_plugin.py to scaffold new projects with optional skills, hooks, and assets
• Skills require an agents/openai.yaml schema file and implementation scripts that communicate via stdin/stdout
• Validate plugins using quick_validate.py before deployment
• Publish by adding the plugin to either personal (~/.agents/plugins/) or team (.agents/plugins/) marketplace configurations

Frequently Asked Questions

What file format does the OpenAI plugin manifest use?

The plugin manifest uses JSON format and must be named plugin.json located in .codex-plugin/ within your plugin directory. It follows the Plugin JSON spec which defines required fields including name, version, description, author, and an interface object for UI rendering.

Can I build OpenAI plugins in languages other than Python?

Yes. While the scaffolding tools and validation scripts use Python, skill implementations can use any programming language (Node.js, Go, Rust, etc.) as long as the executable reads input JSON from stdin and writes valid JSON to stdout. The agents/openai.yaml schema defines the contract independently of implementation language.

How do I share my plugin with other Codex users?

Share your plugin by generating a deep-link URL in the format codex://plugins/<plugin-name>?marketplacePath=<path> after scaffolding with the --with-marketplace flag. Alternatively, commit the plugin to a shared repository's .agents/plugins/marketplace.json to make it available team-wide, or distribute the folder for manual installation to ~/.agents/plugins/ for personal use.

What is the difference between hooks and skills in OpenAI plugins?

Skills define callable actions that Codex invokes to perform tasks (like API calls), while hooks define event-driven callbacks specified in hooks.json that trigger during lifecycle events such as plugin installation, authentication, or uninstallation. Skills are for functionality; hooks are for lifecycle management.

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