# How to Migrate from Legacy Plugin Format to the New OpenAI Plugins Structure

> Easily migrate your legacy OpenAI plugins to the new structure. Move your skills, create a manifest.json or openai.yaml, update paths, and validate your plugin.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: migration-guide
- Published: 2026-07-04

---

**To migrate from the legacy Codex format to the new OpenAI Plugins structure, move your existing `skills/` directory into a new `plugins/<name>/` folder, create a modern [`manifest.json`](https://github.com/openai/plugins/blob/main/manifest.json) (or [`openai.yaml`](https://github.com/openai/plugins/blob/main/openai.yaml)) file, update relative import paths, and validate against the repository's schema tests.**

The `openai/plugins` repository has transitioned from the legacy **Codex plugin format** to a standardized architecture that separates plugins into a dedicated `plugins/` directory with structured manifests. If you maintain a legacy plugin, you will need to relocate your skill files and update your configuration to match the new specification.

## Understanding the Legacy Codex Format

Legacy plugins followed a simple folder structure containing a `skills/` directory with one-off skill files and minimal metadata. As noted in [`plugins/remotion/README.md`](https://github.com/openai/plugins/blob/main/plugins/remotion/README.md), the legacy format was characterized by a direct copy of skills into a local `skills/` directory without the modern plugin encapsulation.

## Step-by-Step Migration Process

### 1. Locate Your Legacy Plugin

Identify your existing plugin code. According to the repository's migration examples, legacy plugins typically resemble the structure described in the Remotion documentation: *"This copies skills from `packages/skills/skills/` into the `skills/` directory in the **Codex plugin format**."*

### 2. Create the New Plugin Structure

Create a new directory under the top-level `plugins/` folder using your plugin name:

```bash
mkdir -p plugins/my-plugin/skills

```

### 3. Copy the Skills Directory

Preserve your existing logic by copying the legacy `skills/` subtree into the new location. Maintain the relative file layout; the skill files themselves do not require modification.

```bash
cp -r legacy-plugin/skills/* plugins/my-plugin/skills/

```

### 4. Add a Modern Manifest

Create a [`manifest.json`](https://github.com/openai/plugins/blob/main/manifest.json) (or [`openai.yaml`](https://github.com/openai/plugins/blob/main/openai.yaml)) file that declares the plugin's name, description, authentication type, and exported skills. The **Zoom SDK migration guide** at [`plugins/zoom/skills/zoom-apps-sdk/troubleshooting/migration.md`](https://github.com/openai/plugins/blob/main/plugins/zoom/skills/zoom-apps-sdk/troubleshooting/migration.md) provides the authoritative checklist for required fields.

```json
{
  "name": "my-plugin",
  "description": "My plugin migrated to the new OpenAI format",
  "auth": {
    "type": "none"
  },
  "skills": [
    "skills/*"
  ]
}

```

### 5. Update Import Paths

Modify any code that referenced old root-level skill files. All imports should now be relative to `plugins/<plugin-name>/skills/`.

Old import pattern:

```javascript
import { someUtil } from '../../utils.js';

```

New import pattern:

```javascript
import { someUtil } from '../../plugins/my-plugin/skills/utils.js';

```

### 6. Remove Legacy Artifacts

Delete obsolete helper scripts, deprecated [`package.json`](https://github.com/openai/plugins/blob/main/package.json) entries, and legacy [`openai.yaml`](https://github.com/openai/plugins/blob/main/openai.yaml) fragments that are no longer needed. The migration guide advises removing any "legacy-only" entries (such as deprecated environment variables) once the new manifest is active.

### 7. Validate with Repository Tests

Run the repository's test suite or plugin-specific skill tests to confirm proper loading. The CI pipelines for plugins (such as Zoom and Vercel) automatically validate the manifest against the OpenAI Plugin schema.

### 8. Commit the Migration

Stage the new `plugins/<plugin>/` tree and remove the legacy folder once the plugin builds successfully and passes all tests.

### 9. Document the Changes

Update your plugin's [`README.md`](https://github.com/openai/plugins/blob/main/README.md) to reflect the new structure, ensuring future maintainers understand the expected layout.

## Key Migration Files and References

| File | Purpose |
|------|---------|
| [`plugins/remotion/README.md`](https://github.com/openai/plugins/blob/main/plugins/remotion/README.md) | Demonstrates the legacy Codex plugin layout and the copy-into-`skills/` step. |
| [`plugins/zoom/skills/zoom-apps-sdk/troubleshooting/migration.md`](https://github.com/openai/plugins/blob/main/plugins/zoom/skills/zoom-apps-sdk/troubleshooting/migration.md) | Authoritative migration checklist for moving from legacy to the new manifest-based structure. |
| `plugins/<your-plugin>/manifest.json` | Required new-format descriptor that replaces the old Codex metadata. |
| `plugins/<your-plugin>/skills/` | Destination for all original skill files; the core of the migrated plugin. |

## Summary

- **Migrate skills first**: Copy your existing `skills/` directory into `plugins/<name>/skills/` without modifying the skill file contents.
- **Add required metadata**: Create a [`manifest.json`](https://github.com/openai/plugins/blob/main/manifest.json) (or [`openai.yaml`](https://github.com/openai/plugins/blob/main/openai.yaml)) with name, description, auth configuration, and skill exports.
- **Fix imports**: Update all relative import paths to reference the new `plugins/<name>/` location.
- **Validate thoroughly**: Use the repository's CI pipelines to verify manifest compliance before removing legacy files.

## Frequently Asked Questions

### What is the Codex plugin format?

The **Codex plugin format** is the legacy structure used by early OpenAI plugins, consisting of a simple folder containing a `skills/` directory with individual skill files and minimal configuration. This format has been superseded by the current `plugins/` directory structure which requires a standardized manifest.

### Where should I place the manifest.json file in the new structure?

Place the [`manifest.json`](https://github.com/openai/plugins/blob/main/manifest.json) (or [`openai.yaml`](https://github.com/openai/plugins/blob/main/openai.yaml)) file at the root of your new plugin directory at `plugins/<your-plugin-name>/manifest.json`. This file must sit alongside the `skills/` directory, not inside it.

### Do I need to modify the actual skill files content during migration?

No, the skill files themselves generally do not need modification. However, you must update any **relative import paths** within those files to reflect their new location under `plugins/<your-plugin>/skills/`. The core logic and skill implementations remain unchanged.

### How do I validate that my migrated plugin works correctly?

Run the repository's test suite or plugin-specific skill tests as implemented in the CI pipelines. The automated tests validate your [`manifest.json`](https://github.com/openai/plugins/blob/main/manifest.json) against the OpenAI Plugin schema and verify that all skills load correctly from the new `plugins/<your-plugin>/skills/` path.