# OpenAI Plugin Development Requirements: The Complete Technical Guide

> Learn OpenAI plugin development requirements including Nodejs, directory structure, and the essential plugin.json manifest. Build your AI application now.

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

---

**Developing an OpenAI plugin requires Node.js ≥ 14, a properly structured directory under `plugins/<name>/`, a mandatory [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/plugin.json) contains:

```json
"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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/plugins/openai-developers/.codex-plugin/plugin.json), a minimal valid manifest requires:

```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 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`](https://github.com/openai/plugins/blob/main/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`](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}!` };
  }

```

The `build-chatgpt-app` skill in [`plugins/openai-developers/skills/build-chatgpt-app/SKILL.md`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.app.json) and [`.mcp.json`](https://github.com/openai/plugins/blob/main/.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:

```bash
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`](https://github.com/openai/plugins/blob/main/plugin.json)
- A sample [`skills/example/SKILL.md`](https://github.com/openai/plugins/blob/main/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:

```bash
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`](https://github.com/openai/plugins/blob/main/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:

```bash
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`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) manifest at its root.
- **Optional components** include `skills/`, `assets/`, [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json), and [`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json) for extended functionality.
- **Validation** is performed via [`plugins/internal-distribution/scripts/validate_distribution.py`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/plugins/internal-distribution/scripts/validate_distribution.py) to verify your manifest and directory structure meet repository requirements.