How to Start Developing OpenAI Plugins: A Complete Developer Guide

To start developing an OpenAI plugin, scaffold a manifest-driven package using the Plugin-Creator skill, which generates the required .codex-plugin/plugin.json file and optional skill directories, then implement your logic in any programming language while defining schemas in YAML.

OpenAI plugins extend the Codex runtime through a manifest-driven architecture that lives in the openai/plugins repository. Every plugin resides in its own folder under plugins/<plugin-name>/ and requires a structured configuration to expose capabilities to the AI. This guide walks you through the exact file structure, scaffolding commands, and implementation patterns used in the official codebase.

Understanding the OpenAI Plugin Architecture

OpenAI plugins follow a strict folder convention that separates configuration from implementation. The system requires a central manifest file and supports optional components for skills, hooks, and UI integrations.

The Manifest-Driven Structure

Every plugin must contain a .codex-plugin/plugin.json file describing metadata, assets, and capabilities. Optional subfolders add functionality:

• Skills: plugins/<plugin-name>/skills/ — JSON or YAML definitions exposing API calls to Codex
• Hooks: plugins/<plugin-name>/hooks.json — Event-driven callbacks for installation or authentication events
• MCP Servers: plugins/<plugin-name>/.mcp.json — Multi-Channel-Protocol definitions for external services
• Apps: plugins/<plugin-name>/.app.json — UI integrations for Composer or custom widgets
• Assets: plugins/<plugin-name>/assets/ — Icons, logos, and screenshots referenced by the manifest

The plugin.json follows the Plugin JSON spec and contains an interface object driving how the plugin appears in the Codex UI, including displayName, description, brandColor, and composerIcon paths.

Personal vs. Team-Wide Distribution

Plugins install through a marketplace system governed by marketplace.json files. You can deploy plugins in two scopes:

• Personal: Installed in ~/.agents/plugins/marketplace.json in the user's home directory
• Team-wide: Stored in the repository's .agents/plugins/marketplace.json

The marketplace file enumerates available plugins and defines installation policies such as AVAILABLE or ON_INSTALL, controlling how users discover and authenticate with your plugin.

Scaffolding Your First Plugin

The repository provides a Plugin-Creator skill that automates boilerplate generation and ensures your plugin structure matches the specification exactly.

Using the Plugin-Creator Skill

Run the scaffold script from the repository root to create a new plugin:

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

The script performs several operations:

1. Creates the plugin folder with normalized kebab-case naming (my-plugin)
2. Generates .codex-plugin/plugin.json populated with required placeholder fields
3. Writes deep-link URLs (codex://plugins/<name>?marketplacePath=…) for direct Codex app access

Add optional components using flags:

• --with-marketplace — Adds or updates the marketplace entry (personal by default)
• --with-skills — Creates the skills/ subdirectory
• --with-hooks — Generates hooks.json template
• --with-assets — Prepares the assets/ folder for icons and logos

Generated Directory Structure

After scaffolding with skill support, your plugin contains:

plugins/my-plugin/
├─ .codex-plugin/
│  └─ plugin.json      # Required manifest

├─ skills/             # Optional skill definitions

├─ assets/             # Optional UI assets

└─ hooks.json          # Optional lifecycle callbacks

The generated plugin.json includes placeholder values for all required fields:

{
  "name": "my-plugin",
  "version": "0.1.0",
  "description": "[TODO: brief description]",
  "author": {
    "name": "[TODO: author name]"
  },
  "interface": {
    "displayName": "My Plugin",
    "shortDescription": "[TODO: subtitle]",
    "longDescription": "[TODO: full description]",
    "category": "Productivity",
    "capabilities": [],
    "defaultPrompt": [],
    "brandColor": "#3B82F6",
    "composerIcon": "./assets/icon.png",
    "logo": "./assets/logo.png",
    "screenshots": []
  }
}

Building Skills for Codex Integration

Skills are the functional core of your plugin—discrete actions that Codex can invoke through defined schemas.

Defining Skill Schemas with openai.yaml

Each skill lives in plugins/<plugin-name>/skills/<skill-name>/ and requires an agents/openai.yaml file specifying the OpenAI-compatible JSON schema for inputs and outputs.

Create the schema definition:

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: Short weather description

Implementing Skill Logic

The implementation can use any programming language. Python scripts are common and follow a simple stdin/stdout contract:

import sys
import json
import requests

def main():
    data = json.load(sys.stdin)
    city = data["city"]
    # Replace with actual API integration

    response = requests.get(f"https://api.example.com/weather?q={city}")
    weather = response.json()
    print(json.dumps({
        "temperature": weather["temp_c"],
        "condition": weather["condition"]["text"]
    }))

if __name__ == "__main__":
    main()

Store the implementation in skills/<skill-name>/scripts/ and reference it from your skill configuration. Update plugin.json to include the skills directory:

{
  "skills": "./skills/"
}

Codex automatically discovers and invokes get_current_weather when users request weather data.

Testing and Publishing

Before distributing your plugin, validate the manifest and test locally within the Codex environment.

Local Validation

Run the official validator against your plugin directory:

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

This script checks plugin.json syntax, verifies required fields, and ensures skill schemas are valid YAML. Codex automatically loads any plugin under the plugins/ directory during development, allowing immediate iteration without installation steps.

Marketplace Registration

To make your plugin discoverable:

1. Copy the plugin folder to your personal ~/.agents/plugins/ directory or the team-wide .agents/plugins/ location
2. Ensure the marketplace.json entry exists (generated automatically if you used --with-marketplace)
3. Commit changes to the repository for team-wide access

The marketplace entry links your plugin to the Codex UI, enabling deep-link sharing and installation workflows.

Summary

• Scaffold new plugins using python3 .agents/skills/plugin-creator/scripts/create_basic_plugin.py with flags for marketplace, skills, and assets
• Structure requires .codex-plugin/plugin.json as the central manifest, with optional skills/, assets/, and configuration files
• Define capabilities in agents/openai.yaml using OpenAI-compatible JSON schemas for type-safe AI interactions
• Implement logic in any language, reading from stdin and writing JSON to stdout according to your schema
• Validate using quick_validate.py and deploy by placing plugins in personal (~/.agents/plugins/) or team (.agents/plugins/) marketplace locations

Frequently Asked Questions

What programming languages can I use to build OpenAI plugin skills?

You can use any programming language for skill implementation. The Codex runtime invokes your script as a subprocess and communicates via stdin/stdout using JSON. Python, Node.js, and Bash scripts are common choices, but compiled binaries or Go programs work equally well as long as they parse the input schema and return valid JSON matching your openai.yaml output definition.

Where does the plugin manifest file need to be located?

The manifest must reside at plugins/<plugin-name>/.codex-plugin/plugin.json relative to the repository root. This location is hard-coded in the Codex runtime loader. The file must contain valid JSON following the Plugin JSON spec, including required fields like name, version, description, and the interface object for UI rendering.

How do I share my plugin with other Codex users?

Share plugins through the marketplace system. For personal distribution, place the plugin in ~/.agents/plugins/ and update your local marketplace.json. For team-wide distribution, commit the plugin to the repository's .agents/plugins/ directory. Use the --with-marketplace flag when scaffolding to automatically generate the marketplace entry and deep-link URL (codex://plugins/<name>?marketplacePath=…).

What is the difference between skills and hooks in the OpenAI plugin system?

Skills are user-facing actions defined in skills/ with YAML schemas that Codex invokes to perform tasks like API calls or data processing. Hooks are lifecycle callbacks defined in hooks.json that trigger during system events such as plugin installation, authentication, or uninstallation. Skills answer user queries; hooks manage plugin state and setup requirements.

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