# Prerequisites for Developing OpenAI Plugins: Complete Setup Guide

> Learn the prerequisites for developing OpenAI plugins. Set up Node.js, create a plugin directory, and understand the manifest file for your OpenAI plugin development.

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

---

**Developing OpenAI plugins requires Node.js 14 or higher, a valid plugin directory under `plugins/<name>/`, a mandatory [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/plugins/openai-developers/.codex-plugin/plugin.json), the manifest structure follows this pattern:

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

```

## 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`](https://github.com/openai/plugins/blob/main/.app.json)** and **[`.mcp.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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:

```bash
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`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) manifest, a sample `skills/` subdirectory, and an `assets/` folder.

### Create a Skill Definition

Add functionality by creating a [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) file in your plugin's `skills/` directory. For example, [`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}!` };
  }

```

### Run the Validation Script

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

```bash
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`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) manifest file
- The manifest must include a `repository` field pointing to your Git repository
- Optional files like [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json), [`.mcp.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/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.