Data & analysis

plugin-creator

Try it

Scaffold a Codex plugin directory with a filled-in .codex-plugin/plugin.json and optional marketplace entry.

What it does

Runs a Python scaffold script that creates a plugin folder with a required .codex-plugin/plugin.json manifest, pre-filled with the full schema shape, [TODO: ...] placeholders, and a complete interface section. Plugin names are normalized to lower-case hyphen-case (max 64 chars) and the folder name always matches the manifest name. Optional flags add skills/, hooks/, scripts/, assets/, .mcp.json, .app.json, and a repo-root .agents/plugins/marketplace.json entry with policy and category fields.

When to use it

  • Starting a new local Codex plugin from scratch
  • Adding skills, hooks, scripts, or MCP config folders to an existing plugin
  • Registering a plugin in .agents/plugins/marketplace.json for Codex UI ordering
  • Setting up a home-local plugin under ~/plugins with its own marketplace file

The skill document

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 repo root (or replace .agents/... with the absolute path to this SKILL).
# By default creates in /plugins/.
python3 .agents/skills/plugin-creator/scripts/create_basic_plugin.py 
  1. Open /.codex-plugin/plugin.json and replace [TODO: ...] placeholders.

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

# marketplace.json always lives at /.agents/plugins/marketplace.json
python3 .agents/skills/plugin-creator/scripts/create_basic_plugin.py my-plugin --with-marketplace

For a home-local plugin, treat `` as the root and use:

python3 .agents/skills/plugin-creator/scripts/create_basic_plugin.py my-plugin \
  --path ~/plugins \
  --marketplace-path ~/.agents/plugins/marketplace.json \
  --with-marketplace
  1. Generate/adjust optional companion folders as needed:
python3 .agents/skills/plugin-creator/scripts/create_basic_plugin.py my-plugin --path  \
  --with-skills --with-hooks --with-scripts --with-assets --with-mcp --with-apps --with-marketplace

is the directory where the plugin folder will be created (for example ~/code/plugins).

What this skill creates

  • If the user has not made the plugin location explicit, ask whether they want a repo-local plugin or a home-local plugin before generating marketplace entries.
  • Creates plugin root at ///.
  • Always creates ///.codex-plugin/plugin.json.
  • Fills the manifest with the full schema shape, placeholder values, and the complete interface section.
  • Creates or updates /.agents/plugins/marketplace.json when --with-marketplace is set.
    • If the marketplace file does not exist yet, seed top-level name plus interface.displayName placeholders before adding the first plugin entry.
  • `` 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

  • marketplace.json always lives at /.agents/plugins/marketplace.json.
  • For a home-local plugin, use the same convention with `` as the root: ~/.agents/plugins/marketplace.json plus ./plugins/.
  • Marketplace root metadata supports top-level name plus optional interface.displayName.
  • Treat plugin order in plugins[] as render order in Codex. Append new entries unless a user explicitly asks to reorder the list.
  • displayName belongs inside the marketplace interface object, not individual plugins[] entries.
  • Each generated marketplace entry must include all of:
    • policy.installation
    • policy.authentication
    • category
  • Default new entries to:
    • policy.installation: "AVAILABLE"
    • policy.authentication: "ON_INSTALL"
  • Override defaults only when the user explicitly specifies another allowed value.
  • Allowed policy.installation values:
    • NOT_AVAILABLE
    • AVAILABLE
    • INSTALLED_BY_DEFAULT
  • Allowed policy.authentication values:
    • ON_INSTALL
    • ON_USE
  • Treat policy.products as an override. Omit it unless the user explicitly requests product gating.
  • The generated plugin entry shape is:
{
  "name": "plugin-name",
  "source": {
    "source": "local",
    "path": "./plugins/plugin-name"
  },
  "policy": {
    "installation": "AVAILABLE",
    "authentication": "ON_INSTALL"
  },
  "category": "Productivity"
}
  • Use --force only when intentionally replacing an existing marketplace entry for the same plugin name.

  • If /.agents/plugins/marketplace.json does not exist yet, create it with top-level "name", an "interface" object containing "displayName", and a plugins array, then add the new entry.

  • For a brand-new marketplace file, the root object should look like:

{
  "name": "[TODO: marketplace-name]",
  "interface": {
    "displayName": "[TODO: Marketplace Display Name]"
  },
  "plugins": [
    {
      "name": "plugin-name",
      "source": {
        "source": "local",
        "path": "./plugins/plugin-name"
      },
      "policy": {
        "installation": "AVAILABLE",
        "authentication": "ON_INSTALL"
      },
      "category": "Productivity"
    }
  ]
}

Required behavior

  • Outer folder name and plugin.json "name" are always the same normalized plugin name.
  • Do not remove required structure; keep .codex-plugin/plugin.json present.
  • Keep manifest values as placeholders until a human or follow-up step explicitly fills them.
  • If creating files inside an existing plugin path, use --force only when overwrite is intentional.
  • Preserve any existing marketplace interface.displayName.
  • When generating marketplace entries, always write policy.installation, policy.authentication, and category even if their values are defaults.
  • Add policy.products only when the user explicitly asks for that override.
  • Keep marketplace source.path relative to repo root as ./plugins/.

Reference to exact spec sample

For the exact canonical sample JSON for both plugin manifests and marketplace entries, use:

  • references/plugin-json-spec.md

Validation

After editing SKILL.md, run:

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

Questions people ask

What does the generated plugin.json contain?
It contains the full schema shape with placeholder values and a complete interface section. Placeholders are written as [TODO: ...] and are left for a human or follow-up step to fill in.
How are plugin names handled?
Names are normalized using skill-creator naming rules: underscores, spaces, and punctuation become hyphens, consecutive hyphens collapse, and the result is lower-case and at most 64 characters. The outer folder name and the plugin.json name are always the same.
What does the marketplace entry include?
Each entry has name, a local source path of ./plugins/<name>, policy.installation (default AVAILABLE), policy.authentication (default ON_INSTALL), and a category. policy.products is omitted unless you explicitly ask for product gating.
When should I use --force?
Only when you intentionally want to overwrite files inside an existing plugin path or replace an existing marketplace entry for the same plugin name.

Related skills

Fetch raw ad creative, app, ranking, and revenue data from AdMapix as structured JSON.

by fly0pants4.3k installs296 stars

Generate and edit Draw.io, Mermaid, and Excalidraw diagrams from natural language using a structured JSON spec.

by nssa.io1.0k installs47 stars

Turn git history into a people-to-file ownership graph with bus factor and sensitive-code risk findings.

by OpenAI28.8k stars

Deploy web projects to Netlify using the Netlify CLI (`npx netlify`). Use when the user asks to deploy, host, publish, or link a site/repo on Netlify, including preview and production deploys.

by OpenAI28.8k stars

sentry

Official

Use when the user asks to inspect Sentry issues or events, summarize recent production errors, or pull basic Sentry health data via the Sentry CLI; perform read-only queries using the `sentry` command

by OpenAI28.8k stars

More from OpenAI

Browse all skills

chatgpt-apps

Official

Scaffold, refactor, and debug ChatGPT Apps SDK projects that pair an MCP server with a widget UI.

by OpenAI28.8k stars

Build or update full Figma screens using your published design system's components, variables, and styles.

by OpenAI28.8k stars

Turns a codebase into a matching Figma design system, phase by phase, with approval checkpoints.

by OpenAI28.8k stars

figma-use

Official

Run JavaScript in Figma files through the Plugin API with the rules that keep scripts from failing.

by OpenAI28.8k stars

hatch-pet

Official

Turn a concept, brand cue, or reference image into a validated 8x9 animated Codex pet atlas with pet.json packaging.

by OpenAI28.8k stars

imagegen

Official

Generate or edit raster images in Codex, from hero shots and sprites to transparent-background cutouts.

by OpenAI28.8k stars