# How to Use the Plugin Creator Skill in Codex: Complete Scaffold Guide

> Master the Plugin Creator skill in Codex with this guide. Automate scaffolding for manifest, resources, and marketplace registration. Get started building your Codex plugin today.

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

---

**The Plugin Creator skill automates the scaffolding of a new Codex plugin—including its manifest, optional resources (skills, hooks, scripts, assets, MCP, and App files), and optional marketplace registration.**

The Plugin Creator skill in Codex serves as a thin wrapper around the Python script [`create_basic_plugin.py`](https://github.com/openai/plugins/blob/main/create_basic_plugin.py) in the `openai/plugins` repository. When you invoke this skill from Codex or run the script directly, it validates your plugin name, creates the directory structure, and generates a complete [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) manifest. You can optionally register the plugin to a personal or team marketplace for easy sharing across your organization.

## Core Workflow and Implementation

The skill delegates all heavy lifting to [`.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). Understanding the internal functions helps you customize the generated scaffold or debug issues.

### Name Normalization and Validation

Before creating files, the script sanitizes your input through [`normalize_plugin_name`](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/scripts/create_basic_plugin.py#L24-L30) (converting to lower-case with hyphen separation) and validates length constraints via [`validate_plugin_name`](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/scripts/create_basic_plugin.py#L33-L41). Invalid names trigger immediate errors before any filesystem changes occur.

### Directory Structure Creation

The scaffolded plugin root defaults to `~/plugins/<plugin-name>` unless you specify an alternate path with `--path`. The script calls `plugin_root.mkdir` at lines 51-53 to create this directory and any necessary parent folders.

### Manifest Generation

At the heart of the skill lies [`build_plugin_json`](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/scripts/create_basic_plugin.py#L43-L85), which writes the [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) manifest. This JSON file contains the full manifest shape required by Codex, including metadata, entry points, and resource declarations.

## Optional Resources and Marketplace Registration

Beyond the basic manifest, the skill can populate additional directories and register your plugin for discovery.

### Creating Optional Resources

Pass any combination of flags to scaffold empty directories and stub files:

- `--with-skills` creates a `skills/` directory
- `--with-hooks` creates a `hooks/` directory  
- `--with-scripts` creates a `scripts/` directory
- `--with-assets` creates an `assets/` directory
- `--with-mcp` creates a stub [`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json) file
- `--with-apps` creates a stub [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) file

### Marketplace Configuration

When you supply `--with-marketplace`, the skill invokes [`update_marketplace_json`](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/scripts/create_basic_plugin.py#L29-L65) to register your plugin.

Two marketplace locations are supported:

**Personal marketplace:** `~/.agents/plugins/marketplace.json` (default).

**Repository or team marketplace:** `<repo-root>/.agents/plugins/marketplace.json` when using `--marketplace-path`.

Each entry includes required fields such as `policy.installation`, `policy.authentication`, and `category`, following the JSON schema documented in [`plugin-json-spec.md`](https://github.com/openai/plugins/blob/main/plugin-json-spec.md).

## Command-Line Usage Examples

While primarily designed for Codex integration, you can invoke the skill directly via Python for CI/CD pipelines or local development.

### Quick Scaffold

Create a personal plugin under the default `~/plugins/` directory:

```bash
python3 .agents/skills/plugin-creator/scripts/create_basic_plugin.py my-awesome-plugin

```

### Scaffold with Optional Resources

Generate a plugin with skills, hooks, assets, and MCP support:

```bash
python3 .agents/skills/plugin-creator/scripts/create_basic_plugin.py \
  my-awesome-plugin \
  --with-skills \
  --with-hooks \
  --with-scripts \
  --with-assets \
  --with-mcp \
  --with-apps

```

### Register to Personal Marketplace

Create a plugin and immediately add it to your personal marketplace:

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

```

### Repository-Scoped Plugin with Team Marketplace

Target a specific directory and update the repo's marketplace file:

```bash
python3 .agents/skills/plugin-creator/scripts/create_basic_plugin.py \
  my-repo-plugin \
  --path ./plugins \
  --marketplace-path ./.agents/plugins/marketplace.json \
  --with-marketplace

```

### Force Overwrite Existing Entries

Use caution when updating existing plugins—this will overwrite marketplace entries and manifest files:

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

```

## Safety Mechanisms and Idempotency

The Plugin Creator skill implements defensive checks to prevent accidental data loss.

The script refuses to overwrite an existing marketplace entry unless you explicitly pass `--force`. Similarly, both the manifest ([`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json)) and marketplace files are written via a `write_json` utility that checks for existence before writing. These protections ensure you cannot accidentally destroy working plugin configurations during iterative development.

After successful execution, the script prints the absolute paths to your scaffolded plugin directory, manifest file, and (if applicable) the updated marketplace file. When invoked from Codex, the final UI should present "View <plugin>" and "Share <plugin>" deep-links according to the skill specification, though the underlying script only outputs filesystem paths.

## Summary

- The **Plugin Creator skill** wraps [`create_basic_plugin.py`](https://github.com/openai/plugins/blob/main/create_basic_plugin.py) to automate Codex plugin scaffolding.
- It validates plugin names via `normalize_plugin_name` and `validate_plugin_name` before creating directories.
- The **manifest** at [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) is generated by `build_plugin_json` with full schema compliance.
- Optional flags create **resources** directories (skills, hooks, scripts, assets) and stub configuration files (MCP, Apps).
- **Marketplace registration** supports both personal (`~/.agents/plugins/marketplace.json`) and repository-scoped paths via `--marketplace-path`.
- The `--force` flag bypasses overwrite protection for idempotent updates to existing plugins.

## Frequently Asked Questions

### What is the default installation path for scaffolded plugins?

By default, the Plugin Creator skill installs new plugins to `~/plugins/<plugin-name>/`. You can override this destination using the `--path` argument to specify any filesystem location or repository-relative directory.

### Does the skill support updating existing plugins or only creating new ones?

The skill supports updating existing plugins, but only when you explicitly provide the `--force` flag. Without this flag, the script prevents overwriting existing manifest files and marketplace entries to protect against accidental configuration loss.

### What marketplace fields are required when using --with-marketplace?

When registering to a marketplace, the entry must include `policy.installation`, `policy.authentication`, and `category` fields. These follow the canonical JSON schema defined in [`.agents/skills/plugin-creator/references/plugin-json-spec.md`](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/references/plugin-json-spec.md) within the `openai/plugins` repository.

### Can I use the Plugin Creator skill outside of the Codex interface?

Yes. While designed for Codex integration, the underlying [`create_basic_plugin.py`](https://github.com/openai/plugins/blob/main/create_basic_plugin.py) script functions as a standalone Python CLI tool. You can invoke it directly in shell scripts, CI/CD pipelines, or local development workflows without launching the Codex agent.