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 <repo_root>/plugins/<plugin-name>.
python3 .agents/skills/plugin-creator/scripts/create_basic_plugin.py <plugin-name>

2. Open

   <plugin-path>/.codex-plugin/plugin.json

   and replace

   [TODO: ...]

   placeholders.

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

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

For a home-local plugin, treat

<home>

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

4. Generate/adjust optional companion folders as needed:

python3 .agents/skills/plugin-creator/scripts/create_basic_plugin.py my-plugin --path <parent-plugin-directory> \
  --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

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

  /<parent-plugin-directory>/<plugin-name>/

  .
• Always creates

  /<parent-plugin-directory>/<plugin-name>/.codex-plugin/plugin.json

  .
• Fills the manifest with the full schema shape, placeholder values, and the complete

  interface

  section.
• Creates or updates

  <repo-root>/.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.

• <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

• marketplace.json

  always lives at

  <repo-root>/.agents/plugins/marketplace.json

  .
• For a home-local plugin, use the same convention with

  <home>

  as the root:

  ~/.agents/plugins/marketplace.json

  plus

  ./plugins/<plugin-name>

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

  <repo-root>/.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/<plugin-name>

  .

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 <path-to-skill-creator>/scripts/quick_validate.py .agents/skills/plugin-creator