plugin-creator skill

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>

The scaffold starts with valid defaults and must not contain [TODO: ...] placeholders.

1. Edit /.codex-plugin/plugin.json when the request gives specific metadata.

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

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

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

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

~/.agents/plugins/marketplace.json, with plugins generally being stored in ~/plugins//.

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

• Creates plugin root at ///.
• Always creates ///.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.
• 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/

Marketplace workflow

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

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

when the user specifically requests it.

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

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

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

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

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

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.

• 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/readmarketplacename.py; stop if

install commands.

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

• In either location, the generated source path remains ./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.

{
  "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 the target marketplace file 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": "personal",
  "interface": {
    "displayName": "Personal"
  },
  "plugins": [
    {
      "name": "plugin-name",
      "source": {
        "source": "local",
        "path": "./plugins/plugin-name"
      },
      "policy": {
        "installation": "AVAILABLE",
        "authentication": "ON_INSTALL"
      },
      "category": "Productivity"
    }
  ]
}

Required behavior

personal because that name is already taken or installed elsewhere.

• 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.
• Do not leave [TODO: ...] placeholders in plugin manifests.
• Keep apps and mcpServers out of plugin.json unless their companion files are actually created.
• Omit unsupported plugin manifest fields that validation rejects, including hooks.
• 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 the selected marketplace root as ./plugins/.
• Only use --marketplace-name when creating a new marketplace file whose name should not be

proceeding. If the user prefers to run the write themselves, provide the exact scaffold command and then continue from validation or subsequent plugin edits instead of leaving the workflow vague.

• If Codex would need approval to write the marketplace file, ask for that approval before

or marketplace.json. Use the update flow documented in references/installing-and-updating.md and scripts/updateplugincachebuster.py.

• For updates to an existing local plugin during development, do not hand-edit marketplace config

flow. That command is for explicit non-default marketplace configuration, not for the standard ~/.agents/plugins/marketplace.json path.

• Do not tell the user to run codex plugin marketplace add for the default personal-marketplace

before giving reinstall instructions. Use codex plugin marketplace add when that explicit marketplace has not been configured yet.

• If the user provided a non-default --marketplace-path, make sure that marketplace is installed

response with a short Codex app handoff. Say To view this in the Codex app: and write View and Share as Markdown links, not raw URLs or code spans.

• When the workflow created or updated a marketplace-backed plugin, end the final user-facing

The Share deeplink uses the same URL with &mode=share.

• The View deeplink uses codex://plugins/?marketplacePath=.

path from the scaffolded plugin. URL-encode the path segment and query value when needed.

• Replace the placeholders with the real normalized plugin name and absolute marketplace.json