Data & analysis

plugin-creator

Try it

Scaffolds Codex plugin directories with manifest files and optional marketplace entries.

What it does

Generates a normalized plugin folder containing the required .codex-plugin/plugin.json with schema-compliant placeholders. Optionally creates companion directories like skills, hooks, scripts, assets, MCP, and apps. Can also initialize or update .agents/plugins/marketplace.json with default policy and category metadata for UI ordering.

When to use it

  • Starting a new local Codex plugin from scratch
  • Adding optional plugin subdirectories to an existing scaffold
  • Registering a plugin in the repo or home marketplace file
  • Normalizing plugin names to lower-case hyphen-case

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 files are always created?
The skill always creates the plugin root folder and .codex-plugin/plugin.json with full schema placeholders. Companion folders and marketplace entries are only added when explicitly requested via flags.
How are plugin names handled?
Names are normalized to lower-case hyphen-case with consecutive hyphens collapsed, limited to 64 characters. The outer folder name and plugin.json name field always match this normalized value.
What defaults apply to new marketplace entries?
New entries default to policy.installation AVAILABLE, policy.authentication ON_INSTALL, and category Productivity. These fields are always written even when using defaults, and policy.products is omitted unless explicitly requested.

Related skills

Maps git history to security ownership, bus factor, and file co-change clusters with CSV/JSON exports.

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

Scaffolds ChatGPT Apps SDK projects with MCP servers and widget UIs grounded in current official documentation.

by OpenAI28.8k stars

Builds or updates full Figma screens using published design system components, variables, and styles instead of hardcoded primitives.

by OpenAI28.8k stars

Orchestrates multi-phase Figma design system builds from codebases with mandatory validation checkpoints.

by OpenAI28.8k stars

figma-use

Official

Enforces mandatory Figma Plugin API rules and incremental workflows for safe script execution.

by OpenAI28.8k stars

hatch-pet

Official

Generates Codex-compatible animated pet spritesheets and packaging from concepts, brand cues, or reference images.

by OpenAI28.8k stars

imagegen

Official

Generate or edit raster images for projects, including photos, mockups, sprites, and transparent cutouts.

by OpenAI28.8k stars