Prerequisites for Developing OpenAI Plugins: Complete Setup Guide

Developing OpenAI plugins requires Node.js 14 or higher, a valid plugin directory under plugins/<name>/, a mandatory .codex-plugin/plugin.json manifest file, and an OpenAI API key for testing and validation.

The openai/plugins repository houses the reference implementation for Codex-compatible extensions. Before writing any business logic, you must satisfy strict structural and environmental prerequisites that the framework validates through automated tooling. These requirements ensure the discovery engine can locate your plugin and load its assets correctly.

Environment Requirements: Node.js Runtime

All plugin tooling in the repository is written in JavaScript and TypeScript. You must have Node.js version 14 or higher (or a compatible JavaScript runtime) installed to execute the scaffold scripts, validation tools, and test runners. The root README.md documents this requirement as the foundation for interacting with the plugin ecosystem.

Required Directory Structure and Manifest

The repository enforces a conventional layout so the discovery engine can locate your code.

The Plugin Directory Layout

Every plugin must live under plugins/<name>/ where <name> is your plugin identifier. This path is non-negotiable; the framework scans this specific location to find valid extensions. According to the repository overview in README.md, placing your code anywhere else will prevent the marketplace from indexing your plugin.

The Mandatory Manifest File

Inside your plugin directory, you must create a file at .codex-plugin/plugin.json. This JSON manifest is the single source of truth for the marketplace and must include fields such as name, version, description, author, repository, capabilities, and permissions. The repository field must point to a valid Git repository, as the marketplace uses this for versioning and provenance.

As implemented in the reference plugin at plugins/openai-developers/.codex-plugin/plugin.json, the manifest structure follows this pattern:

{
  "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": []
}

Optional Companion Files and Assets

While only the manifest is strictly required, most plugins include additional files that the framework reads at load time. These optional components include:

• .app.json and .mcp.json – Configuration files for the OpenAI Platform connector and Model Context Protocol settings
• assets/ – Directory containing logos and UI resources
• skills/ – Directory containing reusable skill definitions

The plugins/openai-developers/README.md describes these files in its "What Is Included" section, noting that they expose additional functionality when present.

Authentication and API Keys

For plugins that interact with OpenAI services, you need an OpenAI account and API key. The repository includes skills such as openai-platform-api-key (documented in plugins/openai-developers/skills/openai-platform-api-key/SKILL.md) that store credentials locally for testing. Without valid authentication, validation scripts that test platform integration will fail.

Scaffold and Validate Your Plugin

The repository provides automation to ensure you meet all prerequisites.

Generate the Boilerplate

Use the built-in creator skill to scaffold the required directory structure:

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

This script creates plugins/my-awesome-plugin/ with the mandatory .codex-plugin/plugin.json manifest, a sample skills/ subdirectory, and an assets/ folder.

Create a Skill Definition

Add functionality by creating a SKILL.md file in your plugin's skills/ directory. For example, 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}!` };
  }

Run the Validation Script

Before publishing, verify your plugin meets all structural requirements using the Python validation helper:

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

The script checks for the manifest, required folders, and optional assets. An exit status of 0 confirms all prerequisites are satisfied.

Summary

• Node.js ≥ 14 is required to run all plugin tooling in the openai/plugins repository
• Plugins must reside under plugins/<name>/ with a .codex-plugin/plugin.json manifest file
• The manifest must include a repository field pointing to your Git repository
• Optional files like .app.json, .mcp.json, assets/, and skills/ extend functionality but are not mandatory
• An OpenAI API key is necessary for testing platform-dependent skills
• Use plugins/internal-distribution/scripts/validate_distribution.py to verify your setup before submission

Frequently Asked Questions

What Node.js version is required for OpenAI plugin development?

You need Node.js version 14 or higher. The repository's tooling is written in JavaScript and TypeScript, and the validation scripts specifically target this runtime environment.

Where must the plugin.json manifest file be located?

The manifest must reside at plugins/<name>/.codex-plugin/plugin.json relative to the repository root. This specific path is hardcoded into the discovery engine; placing it elsewhere will prevent the marketplace from finding your plugin.

Are Git repositories required for OpenAI plugins?

Yes. The repository field in your .codex-plugin/plugin.json must point to a valid Git repository. The marketplace uses this URL for versioning, provenance tracking, and publishing workflows.

How do I validate that my plugin meets all prerequisites before publishing?

Run the validation script at plugins/internal-distribution/scripts/validate_distribution.py with the --plugin-dir argument pointing to your plugin folder. The script verifies the manifest schema, required directories, and optional assets, exiting with status 0 if all checks pass.

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