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

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 (or 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, 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:

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.

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

4. Add a Modern Manifest

Create a manifest.json (or 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 provides the authoritative checklist for required fields.

{
  "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:

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

New import pattern:

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

6. Remove Legacy Artifacts

Delete obsolete helper scripts, deprecated package.json entries, and legacy 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 to reflect the new structure, ensuring future maintainers understand the expected layout.

Key Migration Files and References

File	Purpose
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	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 (or 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 (or 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 against the OpenAI Plugin schema and verify that all skills load correctly from the new plugins/<your-plugin>/skills/ path.

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