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

Clone the openai/plugins repository and run the scaffold script at .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 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, demonstrating how to structure Python scripts that handle external API calls.

Marketplace Configuration

The marketplace metadata file at .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), 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

   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 for the metadata schema and 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:

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

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 with normalized placeholders
• Empty skills/ and assets/ directories ready for your code
• An entry in ./.agents/plugins/marketplace.json with default installation and authentication policies

Implement a Minimal Skill

Create plugins/my-awesome-plugin/skills/hello/hello.py:

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:

---
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 and executable code in a skills/ directory.
• Use .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 governs UI visibility and permission policies.
• Reference the plugin specification at .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 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 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 (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 manifest by following the specification in .agents/skills/plugin-creator/references/plugin-json-spec.md. However, using 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.

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