# How to Get Started with OpenAI Plugin Developer Documentation: A Complete Guide

> Get started with OpenAI plugin developer documentation. Clone the openai/plugins repo and use the scaffold script to create your first manifest-driven plugin. Learn more now.

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

---

**Clone the openai/plugins repository and run 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 a manifest-driven plugin skeleton that Codex recognizes.**

The openai/plugins repository serves as the definitive reference for OpenAI plugin developer documentation, providing a curated collection of ready-to-run Codex plugin examples. Each plugin follows a strict manifest-driven layout under `plugins/<name>/` that the Codex runtime expects, making it easy to extend AI capabilities with custom skills.

## Understanding the Plugin Architecture

OpenAI plugins rely on a standardized directory structure that separates metadata from executable code. The system expects four core components to be present before Codex can detect and load your extension.

### The Plugin Manifest

Every plugin requires a **plugin manifest** stored at `plugins/<plugin>/.codex-plugin/plugin.json`. This JSON file is the single source of truth for Codex, describing the plugin's name, version, author, interface capabilities, and UI text. Examine the Box plugin example at [`plugins/box/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/box/.codex-plugin/plugin.json) to see a production-ready implementation that defines authentication policies and required permissions.

### The Skills Directory

Executable logic lives in the **skills directory** at `plugins/<plugin>/skills/`. Each skill contains functions that Codex can invoke, such as REST API wrappers or file-based scripts. For instance, the Box plugin implements its core functionality in [`plugins/box/skills/box/scripts/box_rest.py`](https://github.com/openai/plugins/blob/main/plugins/box/skills/box/scripts/box_rest.py), demonstrating how to structure Python scripts that handle external API calls.

### Marketplace Configuration

The **marketplace metadata** file at [`.agents/plugins/marketplace.json`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json) controls which plugins appear in the Codex UI and determines their installation policy, authentication requirements, and category ordering. This file can exist at the personal level (`~/.agents/plugins/marketplace.json`) or repository-wide ([`./.agents/plugins/marketplace.json`](https://github.com/openai/plugins/blob/main/./.agents/plugins/marketplace.json)), allowing you to manage plugin visibility across different environments.

## Step-by-Step Setup Guide

Follow these steps to move from repository clone to functioning plugin.

1. **Clone the repository**

   ```bash
   git clone https://github.com/openai/plugins.git
   cd plugins
   ```

2. **Explore an existing example**

   Study the Box plugin structure to understand the relationship between manifest and code. Review [`plugins/box/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/box/.codex-plugin/plugin.json) for the metadata schema and [`plugins/box/skills/box/scripts/box_rest.py`](https://github.com/openai/plugins/blob/main/plugins/box/skills/box/scripts/box_rest.py) for the implementation pattern.

3. **Scaffold a new plugin**

   Use the built-in creator script to generate a complete skeleton:

   ```bash
   python3 .agents/skills/plugin-creator/scripts/create_basic_plugin.py \
     my-awesome-plugin \
     --with-skills \
     --with-assets \
     --with-marketplace
   ```

   This command normalizes the plugin name, creates [`plugins/my-awesome-plugin/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/my-awesome-plugin/.codex-plugin/plugin.json) with placeholder values, and updates your local marketplace file automatically.

4. **Edit the manifest**

   Replace the `[TODO: ...]` placeholders in [`plugins/my-awesome-plugin/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/my-awesome-plugin/.codex-plugin/plugin.json) with real values for name, description, author, and capabilities. The `interface` section defines what UI elements Codex displays, while the `capabilities` array declares what permissions your plugin requires.

5. **Add executable skills**

   Create Python or JavaScript files in `plugins/my-awesome-plugin/skills/` and expose them via a [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) file that Codex discovers at runtime.

6. **Test locally**

   Run your plugin using the Codex runtime tooling to verify that the manifest parses correctly and skills execute without errors.

7. **Publish**

   Commit your new plugin directory and the updated marketplace entry. Codex automatically surfaces the plugin under *My Plugins* when it detects the marketplace file changes.

## Creating Your First Plugin

### Scaffold a Plugin Programmatically

You can invoke the scaffold script from Python when building automation workflows:

```python
import subprocess
import shlex

cmd = """
python3 .agents/skills/plugin-creator/scripts/create_basic_plugin.py \
  my-awesome-plugin \
  --path ./plugins \
  --with-skills \
  --with-assets \
  --with-marketplace
"""
subprocess.check_call(shlex.split(cmd))

```

This generates:
- [`plugins/my-awesome-plugin/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/my-awesome-plugin/.codex-plugin/plugin.json) with normalized placeholders
- Empty `skills/` and `assets/` directories ready for your code
- An entry in [`./.agents/plugins/marketplace.json`](https://github.com/openai/plugins/blob/main/./.agents/plugins/marketplace.json) with default installation and authentication policies

### Implement a Minimal Skill

Create [`plugins/my-awesome-plugin/skills/hello/hello.py`](https://github.com/openai/plugins/blob/main/plugins/my-awesome-plugin/skills/hello/hello.py):

```python
def hello(name: str) -> str:
    """Return a friendly greeting."""
    return f"Hello, {name}! 👋"

```

Then expose it to Codex by creating [`plugins/my-awesome-plugin/skills/hello/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/my-awesome-plugin/skills/hello/SKILL.md):

```markdown
---
name: hello
description: Simple greeting skill
---

```python
def hello(name: str) -> str:
    """Return a friendly greeting."""
    return f"Hello, {name}! 👋"

```

```

### Update Marketplace Metadata Manually

If you need custom ordering beyond what the scaffold provides, edit [`.agents/plugins/marketplace.json`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json) directly:

```json
{
  "name": "my-awesome-plugin",
  "source": { "source": "local", "path": "./plugins/my-awesome-plugin" },
  "policy": {
    "installation": "AVAILABLE",
    "authentication": "ON_INSTALL"
  },
  "category": "Productivity"
}

```

The `policy.installation` field controls whether the plugin appears as available, required, or hidden, while `policy.authentication` determines when the user must provide credentials.

## Summary

- The openai/plugins repository provides the canonical **OpenAI plugin developer documentation** and working examples.
- Every plugin requires a manifest at [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) and executable code in a `skills/` directory.
- Use [`.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 compliant plugin skeletons without manual boilerplate.
- The marketplace file at [`.agents/plugins/marketplace.json`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json) governs UI visibility and permission policies.
- Reference the plugin specification at [`.agents/skills/plugin-creator/references/plugin-json-spec.md`](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/references/plugin-json-spec.md) for complete schema details.

## Frequently Asked Questions

### What is the purpose of the plugin.json manifest file?

The [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) manifest serves as the single source of truth that Codex reads to understand your plugin's metadata, interface capabilities, and required permissions. Located at `plugins/<name>/.codex-plugin/plugin.json`, this file tells the runtime what UI text to display, which icons to use, and what authentication flows to initiate before invoking your skills.

### How do I add executable skills to my plugin?

Place your Python, JavaScript, or other executable scripts inside the `plugins/<name>/skills/` directory, then expose them via a [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) file in the same folder. Codex scans these directories at runtime to discover available functions, passing arguments according to the type signatures defined in your skill files.

### Where does the marketplace.json file live and what does it control?

The marketplace file lives at [`.agents/plugins/marketplace.json`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json) (either in your home directory for personal plugins or at the repository root for project-wide distribution). It controls which plugins appear in the Codex UI, their category grouping, installation policies, and authentication requirements, effectively serving as the curator for what the AI assistant can access.

### Can I create a plugin without using the scaffold script?

Yes, you can manually create the directory structure and write the [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) manifest by following the specification in [`.agents/skills/plugin-creator/references/plugin-json-spec.md`](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/references/plugin-json-spec.md). However, using [`create_basic_plugin.py`](https://github.com/openai/plugins/blob/main/create_basic_plugin.py) ensures your plugin follows the exact naming conventions and schema requirements, reducing the risk of runtime errors due to malformed manifests or missing required fields.