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

> Easily update an existing OpenAI plugin. Learn to increment versions, modify skill definitions and scripts, validate with the CLI, and submit your new release. Follow our developer guide.

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

---

**Update an existing OpenAI plugin by incrementing the version in [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.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

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

```

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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/plugins/zoom/skills/meeting-scheduler/SKILL.md):

```markdown
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`](https://github.com/openai/plugins/blob/main/plugins/zoom/skills/video-sdk/web/scripts/get_participants.js):

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

```bash
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`](https://github.com/openai/plugins/blob/main/plugin.json), then commit and push a Git tag matching the new version:

```bash
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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/README.md)), the affected [`SKILL.md`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/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.