Prerequisites for Building an OpenAI Plugin: Complete Developer Guide

To build an OpenAI plugin, you need Node.js ≥ 14, a properly structured directory under plugins/<name>/, a .codex-plugin/plugin.json manifest file, and an OpenAI API key for testing. Optional companion files like .app.json, .mcp.json, and skill definitions in skills/ extend functionality but follow strict naming conventions.

The openai/plugins repository defines a strict framework for creating Codex plugins that integrate with the OpenAI ecosystem. Before writing any logic, developers must satisfy several structural and environmental prerequisites that the discovery engine enforces. This guide covers the essential technical requirements based on the actual source code implementation.

Core Runtime and Structural Requirements

Node.js Runtime Environment

All plugin tooling is written in JavaScript/TypeScript and requires Node.js ≥ 14 (or a compatible JavaScript runtime). The build scripts, validation tools, and scaffolding utilities all depend on Node.js to execute, as documented in the repository overview.

Conventional Directory Structure

The repository expects a specific layout. Each plugin must live under plugins/<name>/ with required sub-folders. As documented in the root README.md, this convention allows the discovery engine to locate manifests and assets programmatically. The folder name becomes the plugin's identifier in the marketplace.

The plugin.json Manifest

Every plugin requires a .codex-plugin/plugin.json file. This JSON manifest declares metadata including the plugin name, version, description, capabilities, required permissions, and repository URL. According to the OpenAI Developers plugin example in plugins/openai-developers/.codex-plugin/plugin.json, this file serves as the single source of truth for the marketplace and must adhere to the schema defined in the repository.

Optional Companion Files

While not strictly required for basic functionality, the framework checks for optional files that extend capabilities:

• .app.json – UI configuration and application settings
• .mcp.json – Model Context Protocol settings
• assets/ – Static resources like logos and icons
• skills/ – Reusable skill definitions with accompanying SKILL.md files

Authentication and API Requirements

OpenAI Account and API Key

For testing and validation, developers need an OpenAI account and API key. Many plugin skills, such as those defined in plugins/openai-developers/skills/openai-platform-api-key/SKILL.md, interact with the OpenAI Platform to store credentials locally. The validation steps in the root README require these credentials to run tests using node --test.

Git Repository Configuration

The manifest's repository field must point to a valid Git repository (e.g., "repository": "https://github.com/openai/plugins"). The marketplace uses this for versioning and provenance tracking, making version control a de facto prerequisite for distribution.

How to Scaffold a New Plugin

Instead of creating files manually, use the built-in creator skill. From the repository root:

node plugins/.agents/skills/plugin-creator/scripts/create_basic_plugin.js \
  --name my-awesome-plugin \
  --description "A demo OpenAI plugin"

This generates the required structure:

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

├─ skills/
│  └─ example/
│     └─ SKILL.md       # sample skill

└─ assets/
   └─ logo.png

The minimal plugin.json must include specific fields:

{
  "name": "my-awesome-plugin",
  "version": "0.1.0",
  "description": "A demo OpenAI plugin",
  "author": "Your Name",
  "repository": "https://github.com/yourusername/my-awesome-plugin",
  "capabilities": ["skill"],
  "permissions": []
}

Adding Skills and Testing

Create skills by adding a SKILL.md file in the skills/ directory. For example, create plugins/my-awesome-plugin/skills/hello-world/SKILL.md:

# Hello World Skill

description: |
  Returns a greeting.

type: tool

input:
  name: string

output:
  greeting: string

code: |
  export async function run({ name }) {
    return { greeting: `Hello, ${name}!` };
  }

Test locally using:

node --test plugins/my-awesome-plugin/tests/hello-world.test.mjs

Validation Before Submission

Validate your plugin structure using the distribution validator at plugins/internal-distribution/scripts/validate_distribution.py:

python plugins/internal-distribution/scripts/validate_distribution.py \
  --plugin-dir plugins/my-awesome-plugin

This script checks for the manifest, required folders, and optional assets. It exits with status 0 if all prerequisites are met.

Summary

• Node.js ≥ 14 is required for all build tooling and validation scripts according to the repository documentation
• Plugins must reside in plugins/<name>/ with the exact directory structure enforced by the discovery engine
• The .codex-plugin/plugin.json manifest is mandatory and defines the plugin's metadata, capabilities, and permissions
• Optional files (.app.json, .mcp.json, assets/, skills/) extend functionality but must follow strict naming conventions
• An OpenAI API key is necessary for testing skills that interact with the OpenAI Platform
• The validation script at plugins/internal-distribution/scripts/validate_distribution.py verifies all prerequisites before marketplace submission

Frequently Asked Questions

What Node.js version is required to build an OpenAI plugin?

Node.js version 14 or higher is required. The plugin tooling, including the scaffold script at plugins/.agents/skills/plugin-creator/scripts/create_basic_plugin.js and validation utilities, are written in JavaScript/TypeScript and depend on Node.js runtime features available in version 14 and above.

Where must the plugin.json file be located?

The manifest must be located at .codex-plugin/plugin.json relative to your plugin root (e.g., plugins/my-awesome-plugin/.codex-plugin/plugin.json). This specific path is hardcoded in the discovery engine and validation scripts, as shown in the OpenAI Developers plugin example.

Can I build an OpenAI plugin without an OpenAI API key?

You can scaffold the directory structure and define basic skills without an API key, but you cannot test or validate plugins that interact with OpenAI services. Skills like openai-platform-api-key defined in plugins/openai-developers/skills/openai-platform-api-key/SKILL.md require valid credentials to function during the validation phase.

How do I validate my plugin before submitting to the marketplace?

Run the Python validation script: python plugins/internal-distribution/scripts/validate_distribution.py --plugin-dir plugins/<your-plugin-name>/. This checks for the manifest, proper folder structure, and optional assets, exiting with status 0 if all prerequisites defined in the source code are satisfied.

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