# Prerequisites for Building an OpenAI Plugin: Complete Developer Guide

> Build an OpenAI plugin with this developer guide. Learn the essential Node.js, manifest file, and API key prerequisites required for successful plugin development. Get started today.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: how-to-guide
- Published: 2026-06-14

---

**To build an OpenAI plugin, you need Node.js ≥ 14, a properly structured directory under `plugins/<name>/`, a [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) manifest file, and an OpenAI API key for testing.** Optional companion files like [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json), [`.mcp.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.app.json)** – UI configuration and application settings
- **[`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json)** – Model Context Protocol settings
- **`assets/`** – Static resources like logos and icons
- **`skills/`** – Reusable skill definitions with accompanying [`SKILL.md`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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:

```bash
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`](https://github.com/openai/plugins/blob/main/plugin.json) must include specific fields:

```json
{
  "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`](https://github.com/openai/plugins/blob/main/SKILL.md) file in the `skills/` directory. For example, create [`plugins/my-awesome-plugin/skills/hello-world/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/my-awesome-plugin/skills/hello-world/SKILL.md):

```markdown

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

```bash
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`](https://github.com/openai/plugins/blob/main/plugins/internal-distribution/scripts/validate_distribution.py):

```bash
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`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) manifest is mandatory and defines the plugin's metadata, capabilities, and permissions
- Optional files ([`.app.json`](https://github.com/openai/plugins/blob/main/.app.json), [`.mcp.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) relative to your plugin root (e.g., [`plugins/my-awesome-plugin/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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.