How to Update an Existing OpenAI Plugin: A Complete Guide

Updating an OpenAI plugin requires modifying the manifest in .codex-plugin/plugin.json, refreshing skill definitions and connector mappings, bumping the semantic version, and republishing via the OpenAI Developer Console.

The openai/plugins repository hosts Codex plugins that extend LLM capabilities through a structured directory layout. Each plugin resides in plugins/<plugin-id>/ and contains a .codex-plugin directory, skill folders, and implementation scripts that define how the model interacts with external APIs. When updating an existing plugin, you must modify specific configuration files and code while maintaining strict schema compliance with the Codex runtime.

Step 1: Update the Plugin Manifest

The manifest file at plugins/<plugin-id>/.codex-plugin/plugin.json tells the Codex runtime how to load the plugin and which endpoints are exposed.

Increment the version field (e.g., from 1.2.0 to 1.3.0) and verify that api_spec, icon, author, and repository URLs reference the current resources. For example, updating the Zoom plugin would involve editing plugins/zoom/.codex-plugin/plugin.json:

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

Step 2: Refresh Connector Mappings

If your external service's endpoints, authentication flow, or data model changed, update the connector documentation. This typically lives in plugins/<plugin-id>/README.md or a dedicated mapping file, and bridges LLM-side skill calls to third-party APIs.

Adjust the URL paths, authentication scopes, and parameter mappings to ensure the Codex runtime routes calls correctly.

Step 3: Revise Skill Definitions

Skills are the primary entry points the LLM uses, defined in SKILL.md files within plugins/<plugin-id>/skills/<skill-name>/. When adding or modifying capabilities, update the skill description, parameters, and expected output format.

For example, creating a new meeting scheduler skill in 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

Step 4: Update Implementation Scripts

The actual logic resides in plugins/<plugin-id>/skills/<skill-name>/scripts/. These scripts are executed by the Codex runtime and must match the descriptions in the corresponding SKILL.md files.

When updating existing logic, modify the script files directly. For example, updating plugins/zoom/skills/video-sdk/web/scripts/get_participants.js to use paginated endpoints:

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

Make scripts executable (e.g., chmod +x scripts/schedule.py for Python files) if they contain new entry points.

Step 5: Validate Changes Locally

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

codex-cli check plugins/zoom

This command reports missing assets, schema errors, or safety violations defined in the reviewer agents (e.g., plugins/zoom/agents/zoom-integration-reviewer.md). Fix any issues to ensure the plugin passes the platform's safety checks.

Step 6: Commit, Tag, and Publish

After validating your changes:

1. Commit the modified files to the repository
2. Create a Git tag matching the version in plugin.json (e.g., v1.3.0)
3. Push the tag to the remote

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

Finally, submit the update through the OpenAI Developer Console by navigating to the Plugins section, selecting Add new version, and choosing the tag v1.3.0. Include a changelog describing the modifications (e.g., "Added meeting-scheduler skill, refreshed Zoom OAuth scopes").

Summary

• Update the manifest in plugins/<plugin-id>/.codex-plugin/plugin.json with the new version and metadata
• Refresh connector mappings in the plugin's README or dedicated mapping files if external APIs changed
• Revise skill definitions in plugins/<plugin-id>/skills/<skill-name>/SKILL.md to reflect new capabilities
• Update implementation scripts in the corresponding scripts/ directories to match the skill contracts
• Run local validation using codex-cli check to ensure schema compliance
• Commit and tag the release with a Git tag matching the version string in plugin.json
• Publish via the OpenAI Developer Console by selecting the new tag and submitting for review

Frequently Asked Questions

How do I version my OpenAI plugin update?

Increment the version field in plugins/<plugin-id>/.codex-plugin/plugin.json using semantic versioning (e.g., 1.2.0 to 1.3.0). After committing changes, create a Git tag that matches this version string exactly (e.g., git tag v1.3.0), as the OpenAI platform uses this tag to fetch the specific release.

What files must I update when changing a skill's behavior?

You must synchronize three components: the skill definition in plugins/<plugin-id>/skills/<skill-name>/SKILL.md (documenting parameters and returns), the implementation script in plugins/<plugin-id>/skills/<skill-name>/scripts/* (containing executable logic), and the reviewer agent files in plugins/<plugin-id>/agents/ if the change affects safety constraints or API usage patterns.

Can I validate my plugin updates before submitting to OpenAI?

Yes. Run codex-cli check plugins/<plugin-id> from the repository root to verify schema compliance, detect missing assets, and flag unsafe API calls. This local validation ensures the plugin passes the platform's safety checks before you commit and tag the release.

How does the OpenAI platform detect my plugin update?

The platform detects updates through Git tags that match the version string in your plugin.json. After you push a tag (e.g., v1.3.0), the OpenAI Developer Console can fetch this specific release, or you can create a pull request to the main repository to trigger the update process and make the new version available to users.

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