# How to Contribute to the openai/plugins Repository: A Step-by-Step Guide

> Learn how to contribute to the openai plugins repository. Follow our step-by-step guide to fork, scaffold, and submit your plugin for inclusion.

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

---

**Contributing to the `openai/plugins` repository requires forking the repo, scaffolding a new plugin directory with the Plugin Creator skill, and submitting a validated pull request that follows the Codex manifest and documentation standards.**

The `openai/plugins` repository hosts the official plugin ecosystem for OpenAI's Codex CLI, and every submission must conform to a strict directory layout and documentation schema. The maintainers provide built-in scaffolding and validation tools—located under `.agents/skills/plugin-creator/`—to ensure that each contribution integrates cleanly with the marketplace and meets the repository's formatting rules.

## Fork the Repository and Create a Feature Branch

Start by creating a personal fork of the repository on GitHub and cloning it locally. All work must happen on a dedicated feature branch rather than directly on `main`.

```bash
git clone https://github.com/your-username/plugins.git
cd plugins
git checkout -b my-new-plugin

```

This follows the standard open-source contribution model used across the repository, as outlined in the example guide at [`plugins/zoom/CONTRIBUTING.md`](https://github.com/openai/plugins/blob/main/plugins/zoom/CONTRIBUTING.md).

## Scaffold a New Plugin with the Plugin Creator Skill

The repository provides a built-in **Plugin Creator** skill that automates directory creation. According to [`.agents/skills/plugin-creator/SKILL.md`](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/SKILL.md), you should run the [`create_basic_plugin.py`](https://github.com/openai/plugins/blob/main/create_basic_plugin.py) script to generate a normalized, kebab-case plugin directory with the mandatory manifest and optional skeleton folders.

```bash
python3 .agents/skills/plugin-creator/scripts/create_basic_plugin.py \
    my-new-plugin \
    --with-marketplace

```

This command creates the following structure under `plugins/my-new-plugin/`:

```text
plugins/my-new-plugin/
 ├─ .codex-plugin/plugin.json   # manifest with placeholder fields

 ├─ skills/
 ├─ assets/
 └─ .app.json (optional)

```

The `--with-marketplace` flag automatically appends an entry to [`.agents/plugins/marketplace.json`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json) so the plugin appears in the default marketplace listing.

## Populate the Plugin Manifest and Documentation

After scaffolding, replace the `[TODO: …]` placeholders in [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) with real values for `name`, `description`, and `interface`. You must also create any [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) files that describe the plugin's capabilities, and include assets, scripts, or hooks as needed.

The repository enforces strict formatting rules for these files. As documented in [`plugins/zoom/CONTRIBUTING.md`](https://github.com/openai/plugins/blob/main/plugins/zoom/CONTRIBUTING.md), contributors must:

- Keep every [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) file to **500 lines or fewer**.
- Use real markdown links rather than placeholder text.
- Reference environment variables for secrets instead of hard-coding them.

These rules ensure that documentation remains concise, secure, and machine-readable across the ecosystem.

## Validate the Plugin Before Submitting

Before committing, run the quick-validation script to verify that the manifest and optional marketplace entry meet the required schema. The validation tool is located at [`.agents/skills/plugin-creator/scripts/quick_validate.py`](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/scripts/quick_validate.py).

```bash
python3 .agents/skills/plugin-creator/scripts/quick_validate.py .agents/skills/plugin-creator

```

If validation fails, review the error output, adjust the [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) manifest or marketplace entry, and rerun the script. Passing this check is a prerequisite for a successful review.

## Open a Pull Request

Once validation passes, stage your changes, commit them, and push the branch to your fork.

```bash
git add plugins/my-new-plugin
git commit -m "Add My New Plugin – Implements X, Y, Z"
git push origin my-new-plugin

```

Open a pull request against the upstream `main` branch. The expectations for the PR depend on the scope of your changes:

- **Small changes**—such as typo fixes or minor documentation edits—only require a straightforward PR with a clear description.
- **Larger changes**—such as new use-cases or additional skills—require you to first open an issue to discuss the design, then submit the PR with a detailed description of the new functionality.

These guidelines are codified in [`plugins/zoom/CONTRIBUTING.md`](https://github.com/openai/plugins/blob/main/plugins/zoom/CONTRIBUTING.md) and help maintainers prioritize reviews and catch architectural issues early.

## Summary

- Fork the `openai/plugins` repository and create a dedicated feature branch before making any changes.
- Use the **Plugin Creator** skill at [`.agents/skills/plugin-creator/scripts/create_basic_plugin.py`](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/scripts/create_basic_plugin.py) to scaffold the mandatory directory layout and [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) manifest.
- Populate the manifest and any [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) files, keeping documentation under 500 lines and avoiding hard-coded secrets.
- Optionally register the plugin in the marketplace by using the `--with-marketplace` flag during scaffolding.
- Run [`.agents/skills/plugin-creator/scripts/quick_validate.py`](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/scripts/quick_validate.py) to enforce schema compliance before pushing.
- Submit small fixes directly via PR; propose large features via an issue first, then follow with a PR referencing the top-level [`README.md`](https://github.com/openai/plugins/blob/main/README.md) directory conventions.

## Frequently Asked Questions

### What files are required when I contribute a new plugin to openai/plugins?

Every plugin must live under `plugins/<name>/` and include a mandatory [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) manifest, as defined in the top-level [`README.md`](https://github.com/openai/plugins/blob/main/README.md). You should also provide a [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) file and an `assets/` directory if your plugin includes icons or screenshots.

### How do I validate my plugin before opening a pull request?

Run the [`quick_validate.py`](https://github.com/openai/plugins/blob/main/quick_validate.py) script located at [`.agents/skills/plugin-creator/scripts/quick_validate.py`](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/scripts/quick_validate.py). This tool checks that the manifest and any marketplace entry conform to the repository's schema requirements and are free of structural errors.

### What is the difference between a small change and a large change in the contribution workflow?

Small changes, such as typo fixes or minor documentation edits, can be submitted directly as a pull request. Larger changes, including new skills or use-cases, require opening a design issue first to discuss the proposal before submitting the PR, according to [`plugins/zoom/CONTRIBUTING.md`](https://github.com/openai/plugins/blob/main/plugins/zoom/CONTRIBUTING.md).

### Where is the marketplace configuration stored for openai/plugins?

When you scaffold with the `--with-marketplace` flag, the creator script automatically updates [`.agents/plugins/marketplace.json`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json). This central JSON file serves as the default marketplace index that Codex uses to discover publicly available plugins.