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

> Begin developing OpenAI plugins in 2024 with this guide. Learn to create manifest-driven packages including plugin JSON and optional assets for seamless integration with the Codex runtime.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: getting-started
- Published: 2026-06-14

---

**Developing OpenAI plugins requires creating a manifest-driven package in the `plugins/<plugin-name>/` directory, complete with a [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.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:

```bash
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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/openai.yaml) defines the contract between Codex and your code:

```yaml
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`:

```python
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`](https://github.com/openai/plugins/blob/main/plugin.json) by adding the `skills` property pointing to your skills directory:

```json
"skills": "./skills/"

```

## Validating and Testing Locally

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

```bash
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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/agents/openai.yaml) schema file and implementation scripts that communicate via stdin/stdout
- Validate plugins using [`quick_validate.py`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/hooks.json) that trigger during lifecycle events such as plugin installation, authentication, or uninstallation. Skills are for functionality; hooks are for lifecycle management.