# How to Start Developing OpenAI Plugins: A Complete Developer Guide

> Learn to build your own OpenAI plugin. This guide covers scaffolding with Plugin-Creator, implementing logic, and defining YAML schemas. Start your development journey today.

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

---

**To start developing an OpenAI plugin, scaffold a manifest-driven package using the Plugin-Creator skill, which generates the required [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](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`, 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:

```bash
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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/plugin.json) includes placeholder values for all required fields:

```json
{
  "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`](https://github.com/openai/plugins/blob/main/agents/openai.yaml) file specifying the OpenAI-compatible JSON schema for inputs and outputs.

Create the schema definition:

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

```

### Implementing Skill Logic

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

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

```json
{
  "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:

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

```

This script checks [`plugin.json`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) as the central manifest, with optional `skills/`, `assets/`, and configuration files
- **Define** capabilities in [`agents/openai.yaml`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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.