/plugin-creator

name: plugin-creator
description: Create and scaffold plugin directories for Codex with a required `.codex-plugin/plugin.json`, optional plugin folders/files, valid manifest defaults, and personal-marketplace entries by default. Use when Codex needs to create a new personal plugin, add optional plugin structure, generate or update marketplace entries for plugin ordering and availability metadata, or update an existing local plugin during development with the CLI-driven cachebuster and reinstall flow.

Plugin Creator

Quick Start

1. Run the scaffold script:

# Plugin names are normalized to lower-case hyphen-case and must be <= 64 chars.
# The generated folder and plugin.json name are always the same.
# Run from the skill root (the directory containing this `SKILL.md`).
# By default creates in `~/plugins/<plugin-name>`.
python3 scripts/create_basic_plugin.py <plugin-name>

2. Edit `<plugin-path>/.codex-plugin/plugin.json` when the request gives specific metadata. The scaffold starts with valid defaults and must not contain `[TODO: ...]` placeholders.

3. Generate or update the personal marketplace entry when the plugin should appear in Codex UI ordering:

# Personal marketplace entries default to `~/.agents/plugins/marketplace.json`.
python3 scripts/create_basic_plugin.py my-plugin --with-marketplace

Only specify `--marketplace-name <name>` when the default `personal` marketplace name is already taken or installed and you need to seed a different new marketplace file:

python3 scripts/create_basic_plugin.py my-plugin \
  --with-marketplace \
  --marketplace-name team-local

Only use a repo/team marketplace when the user specifically asks for that destination:

python3 scripts/create_basic_plugin.py my-plugin \
  --path <repo-root>/plugins \
  --marketplace-path <repo-root>/.agents/plugins/marketplace.json \
  --with-marketplace

When the user specifies a marketplace path, make sure that marketplace is actually installed before telling the user to reinstall from it. The default personal marketplace file at `~/.agents/plugins/marketplace.json` is discovered implicitly, but other marketplace paths are not. On Windows, use the equivalent path under the user profile.

4. Generate/adjust optional companion folders as needed:

python3 scripts/create_basic_plugin.py my-plugin \
  --path <parent-plugin-directory> \
  --marketplace-path <marketplace-json-path> \
  --with-skills --with-hooks --with-scripts --with-assets --with-mcp --with-apps --with-marketplace

`<parent-plugin-directory>` is the directory where the plugin folder `<plugin-name>` will be created (for example `~/plugins`).

5. Before handing back a generated plugin, run:

python3 scripts/validate_plugin.py <plugin-path>

For updates to an existing local plugin during development, keep the scaffold flow as-is and use the reference instead of hand-editing marketplace files:

python3 scripts/read_marketplace_name.py
python3 scripts/update_plugin_cachebuster.py <plugin-path>

For a repo/team marketplace, pass `--marketplace-path <marketplace-json-path>` to the first command. Prefer the helper default cachebuster unless the user explicitly asks for a specific override. See `references/installing-and-updating.md` for the expected cachebuster and reinstall flow while iterating on an existing local plugin.

What this skill creates

• Default marketplace-backed scaffolds use the personal marketplace file at

`~/.agents/plugins/marketplace.json`, with plugins generally being stored in `~/plugins/<plugin-name>/`.

• Creates plugin root at `/<parent-plugin-directory>/<plugin-name>/`.
• Always creates `/<parent-plugin-directory>/<plugin-name>/.codex-plugin/plugin.json`.
• Fills the manifest with the validated schema shape that the ingestion path accepts.
• Creates or updates `~/.agents/plugins/marketplace.json` when `--with-marketplace` is set.
• If the marketplace file does not exist yet, seed a personal marketplace root before adding the first plugin entry.
• `<plugin-name>` is normalized using skill-creator naming rules:
• `My Plugin` → `my-plugin`
• `My--Plugin` → `my-plugin`
• underscores, spaces, and punctuation are converted to `-`
• result is lower-case hyphen-delimited with consecutive hyphens collapsed
• Supports optional creation of:
• `skills/`
• `hooks/`
• `scripts/`
• `assets/`
• `.mcp.json`
• `.app.json`

Marketplace workflow

• Personal-marketplace creation defaults to `~/.agents/plugins/marketplace.json`. Here,

"personal marketplace" means the marketplace whose file is at that path.

• Repo/team marketplace creation is opt-in through both `--path` and `--marketplace-path`, only

when the user specifically requests it.

• `--marketplace-name` is an exception path. Use it only when the default `personal` marketplace

name is already taken and you need to seed a different new marketplace file.

• Do not use `--marketplace-name` to rename an existing marketplace file in place. If the file

already exists, its top-level `name` must already match.

• If the user specifies a different marketplace path, treat that marketplace as needing explicit installation via `codex plugin marketplace add`.
• Plugin names must match `[A-Za-z0-9_-]+(\.[A-Za-z0-9_-]+)*`.
• Marketplace names must match `[A-Za-z0-9_-]+`.
• For existing marketplaces, always validate names with `scripts/read_marketplace_name.py`; stop if

validation fails. With no argument it reads the default personal marketplace; with an explicit path it works for repo/team marketplaces too. The scaffold validates new marketplaces itself.

• Before updating existing plugins, validate both identifiers before changing files or constructing

install commands.

• In either location, the generated source path remains `./plugins/<plugin-name>`.
• Marketplace root metadata supports top-level `name` plus optional `interface.displayName`.
• Treat plugin order in `pl