OpenAI Plugin Development Requirements: The Complete Technical Guide

Developing an OpenAI plugin requires Node.js ≥ 14, a properly structured directory under plugins/<name>/, a mandatory .codex-plugin/plugin.json manifest, and optionally assets and skills folders that define your plugin's capabilities.

The openai/plugins repository provides the official framework for building Codex plugins that integrate with the OpenAI ecosystem. Before your plugin can be validated, tested, or published to the marketplace, it must adhere to specific structural conventions and runtime dependencies enforced by the discovery engine.

Runtime Prerequisites

All plugin tooling in the repository is written in JavaScript/TypeScript and requires a compatible runtime environment.

Node.js Version Requirements

You must have Node.js version 14 or higher installed. The build scripts, validation tools, and local testing harnesses all depend on Node.js APIs. According to the repository overview in README.md, this is the baseline runtime for all plugin operations.

Git Repository Configuration

Your plugin must be committed to a Git repository. The manifest file includes a repository field that points to the source URL, which the marketplace uses for versioning and provenance tracking. Ensure your plugin.json contains:

"repository": "https://github.com/yourusername/your-repo-name"

Required Directory Structure

The repository enforces a conventional layout so the discovery engine can locate manifests and assets.

The Plugin Directory Convention

Every plugin must live under plugins/<name>/ where <name> is your plugin's identifier. As documented in the root README.md, this convention allows the tooling to distinguish plugin packages from other repository contents. A valid structure looks like:

plugins/my-awesome-plugin/
├─ .codex-plugin/
│  └─ plugin.json
├─ skills/
└─ assets/

The plugin.json Manifest

The .codex-plugin/plugin.json file serves as the single source of truth for plugin metadata. Located at this specific path within your plugin directory, it declares the name, version, description, capabilities, and required permissions.

According to the example in plugins/openai-developers/.codex-plugin/plugin.json, a minimal valid manifest requires:

{
  "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 Components for Extended Functionality

While the manifest is mandatory, several optional files expose additional capabilities to the Codex framework.

Skills and Assets

The skills/ directory contains subfolders with SKILL.md files that define reusable capabilities. Each skill follows a structured format declaring inputs, outputs, and execution logic. 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}!` };
  }

The build-chatgpt-app skill in plugins/openai-developers/skills/build-chatgpt-app/SKILL.md provides a more complex template for reference.

The assets/ folder stores UI resources like logos and icons referenced by the marketplace.

Configuration Files

You can include .app.json and .mcp.json files at the plugin root to expose additional functionality, such as the OpenAI Platform connector. These configuration files are read when the plugin loads, but are not strictly required for basic operation.

Development and Validation Workflow

The repository provides automation scripts to scaffold and verify plugins.

Scaffolding a New Plugin

Use the built-in creator skill to generate the required folder structure and boilerplate files. From the repository root, run:

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

This script automatically creates:

• The plugins/my-awesome-plugin/.codex-plugin/ directory with a template plugin.json
• A sample skills/example/SKILL.md file
• An assets/ folder with placeholder logo.png

Validating Plugin Structure

Before submission, validate that all prerequisites are present using the distribution validator:

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

This Python script checks for the manifest file, required folders, and optional assets. It exits with status 0 if the plugin structure is valid.

Testing Requirements and API Access

For plugins that interact with OpenAI services, additional credentials are required.

OpenAI Platform Integration

Many plugin skills, such as openai-platform-api-key documented in plugins/openai-developers/skills/openai-platform-api-key/SKILL.md, need to store credentials locally to call the OpenAI Platform. You must have a valid OpenAI account and API key to test these capabilities during development.

Run local tests using Node's built-in test runner:

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

Summary

• Node.js ≥ 14 is required for all plugin tooling and validation scripts located in the repository.
• Directory structure must follow the plugins/<name>/ convention with a .codex-plugin/plugin.json manifest at its root.
• Optional components include skills/, assets/, .app.json, and .mcp.json for extended functionality.
• Validation is performed via plugins/internal-distribution/scripts/validate_distribution.py to ensure compliance with marketplace requirements.
• Git repository must be configured in the manifest's repository field for proper versioning and provenance tracking.

Frequently Asked Questions

What is the minimum Node.js version for OpenAI plugin development?

You need Node.js version 14 or higher. The repository's tooling and validation scripts are written in JavaScript and depend on Node.js runtime features. The root README.md specifies this requirement for all plugin operations.

Can I develop an OpenAI plugin without using the scaffold script?

Yes, though using plugins/.agents/skills/plugin-creator/scripts/create_basic_plugin.js is recommended. You can manually create the plugins/<name>/.codex-plugin/plugin.json manifest and required directories, but the scaffold ensures you include all mandatory fields and folder structures that the validation script checks.

What permissions do I need to declare in the plugin manifest?

Permissions are declared in the permissions array within plugin.json. The specific permissions depend on your plugin's capabilities—for example, skills that access the OpenAI Platform require appropriate scopes. Consult the plugins/openai-developers/.codex-plugin/plugin.json example for the correct schema.

How do I test my plugin locally before submitting to the marketplace?

Use the Node.js test runner to execute skill tests with node --test plugins/<your-plugin>/tests/. Additionally, run the Python validation script plugins/internal-distribution/scripts/validate_distribution.py to verify your manifest and directory structure meet repository requirements.

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