How to Update an Existing OpenAI Plugin: A Complete Developer Guide

Update an existing OpenAI plugin by incrementing the version in .codex-plugin/plugin.json, modifying skill definitions and implementation scripts in the skills/ directory, validating with the Codex CLI, and submitting the new release via the OpenAI Developer Console.

OpenAI plugins are packaged as Codex plugins within a predictable directory hierarchy defined in the openai/plugins repository. Whether you are adding new capabilities or patching existing endpoints, updating a plugin requires precise changes to metadata, skill definitions, and runtime scripts. This guide walks through the exact file locations and commands needed to safely publish a new version.

Update the Plugin Manifest

Every plugin update begins with the manifest file located at plugins/<plugin-id>/.codex-plugin/plugin.json. This JSON file declares the plugin's identity, version, and entry points to the Codex runtime.

Key fields to modify when you update an existing OpenAI plugin include:

• version: Increment following semantic versioning (e.g., 1.2.0 to 1.3.0)
• api_spec: Update if your OpenAPI specification filename or location changed
• description or icon: Refresh if branding or functionality scope changes

{
  "name": "Zoom",
  "description": "Zoom meeting and video integration.",
  "version": "1.3.0",
  "api_spec": "openapi.yaml",
  "icon": "assets/icon.png",
  "repository": "https://github.com/openai/plugins"
}

After editing, save the file at plugins/<plugin-id>/.codex-plugin/plugin.json before proceeding to skill updates.

Modify Skills and Connector Mapping

Skills are the primary entry points the LLM uses to interact with your plugin. Each skill resides in its own subdirectory under plugins/<plugin-id>/skills/<skill-name>/.

Update Skill Documentation

The SKILL.md file defines the interface contract. When updating functionality, ensure this file reflects new parameters or return types. For example, when adding a meeting scheduler skill to the Zoom plugin, create plugins/zoom/skills/meeting-scheduler/SKILL.md:

description: "Schedule a Zoom meeting from the LLM."
parameters:
  - name: topic
    type: string
    description: "Meeting title"
  - name: start_time
    type: string
    format: date-time
    description: "When the meeting should start"
returns:
  type: object
  properties:
    meeting_id:
      type: string
    join_url:
      type: string

Update Implementation Scripts

Scripts located in plugins/<plugin-id>/skills/<skill-name>/scripts/ contain the executable logic. For example, updating the Zoom participants retrieval logic requires editing plugins/zoom/skills/video-sdk/web/scripts/get_participants.js:

// Updated to use paginated endpoint with increased page size
await fetch(`https://api.zoom.us/v2/meetings/${meetingId}/participants?page_size=300`, {
  headers: { Authorization: `Bearer ${token}` },
});

Ensure scripts remain executable (chmod +x scripts/<filename>) and match the interface defined in the corresponding SKILL.md.

Refresh Assets and Reviewer Agents

Update static resources in plugins/<plugin-id>/assets/ (such as icon.png) to reflect branding changes. Additionally, verify that reviewer agents in plugins/<plugin-id>/agents/ (e.g., zoom-integration-reviewer.md) still enforce appropriate safety constraints for your updated functionality.

Validate Changes Locally

Before committing, run the Codex CLI linter to verify schema compliance and detect unsafe API calls:

codex-cli check plugins/<plugin-id>

This command validates the manifest structure, skill definitions, and script permissions against the platform's safety requirements. Fix any reported errors before proceeding to publication.

Version, Tag, and Publish

Commit and Tag

Increment the version in plugin.json, then commit and push a Git tag matching the new version:

git add plugins/zoom/.codex-plugin/plugin.json plugins/zoom/skills/meeting-scheduler/
git commit -m "Add meeting-scheduler skill, bump version to 1.3.0"
git tag v1.3.0
git push origin main --tags

The OpenAI platform uses this tag to fetch the exact release.

Submit via Developer Console

1. Navigate to the Plugins section of the OpenAI Developer Console.
2. Select Add new version and choose the tag (e.g., v1.3.0).
3. Provide a changelog describing the updates.
4. Submit for review.

Once approved, the updated plugin becomes available to users.

Summary

• Manifest updates: Modify plugins/<plugin-id>/.codex-plugin/plugin.json to bump versions and refresh metadata.
• Skill changes: Update SKILL.md documentation and implementation scripts in plugins/<plugin-id>/skills/<skill-name>/.
• Local validation: Run codex-cli check to ensure compliance before submission.
• Version control: Commit changes and push a Git tag (e.g., v1.3.0) to trigger the release.
• Publication: Submit the tagged release through the OpenAI Developer Console.

Frequently Asked Questions

How do I add a new skill to an existing OpenAI plugin?

Create a new directory under plugins/<plugin-id>/skills/<skill-name>/ containing a SKILL.md file describing the interface and a scripts/ subdirectory with the executable implementation. Update the plugin manifest version to reflect the new capability before submitting.

What files must I update when changing an API endpoint?

You must update the connector mapping (typically documented in the plugin's README.md), the affected SKILL.md files to reflect new parameters or endpoints, and the implementation scripts in skills/<skill-name>/scripts/. Finally, increment the version in .codex-plugin/plugin.json.

How does the OpenAI platform detect a new plugin version?

The platform detects new versions via Git tags. After incrementing the version field in plugin.json, commit your changes and push a tag matching the version number (e.g., git tag v1.3.0). The OpenAI Developer Console uses this tag to fetch the specific release.

Can I update a plugin without using the Codex CLI?

While you can manually edit files, the Codex CLI (codex-cli check) is required to validate schema compliance and safety constraints before the platform accepts your submission. Skipping validation may result in rejection during the review phase.

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