Plugin Creator Quick Start 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 < plugin-name
Open
/.codex-plugin/plugin.json and replace [TODO: ...] placeholders. 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
\ --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 < path-to-skill-creator /scripts/quick_validate.py .agents/skills/plugin-creator