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

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.

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.

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, you should run the create_basic_plugin.py script to generate a normalized, kebab-case plugin directory with the mandatory manifest and optional skeleton folders.

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/:

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 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 with real values for name, description, and interface. You must also create any 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, contributors must:

• Keep every 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.

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

If validation fails, review the error output, adjust the 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.

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 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 to scaffold the mandatory directory layout and .codex-plugin/plugin.json manifest.
• Populate the manifest and any 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 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 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 manifest, as defined in the top-level README.md. You should also provide a 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 script located at .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.

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. This central JSON file serves as the default marketplace index that Codex uses to discover publicly available plugins.

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