Create and scaffold plugin directories for Codex with a required `.codex-plugin/plugin.json`, optional plugin folders/files, and baseline placeholders you can edit before publishing or testing. Use when Codex needs to create a new local plugin, add optional plugin structure, or generate or update repo-root `.agents/plugins/marketplace.json` entries for plugin ordering and availability metadata.
# 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>
Open <plugin-path>/.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 <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 as the root and use:
<home>python3 .agents/skills/plugin-creator/scripts/create_basic_plugin.py my-plugin \
--path ~/plugins \
--marketplace-path ~/.agents/plugins/marketplace.json \
--with-marketplace
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).
/<parent-plugin-directory>/<plugin-name>/./<parent-plugin-directory>/<plugin-name>/.codex-plugin/plugin.json.interface section.<repo-root>/.agents/plugins/marketplace.json when --with-marketplace is set.
name plus interface.displayName placeholders before adding the first plugin entry.<plugin-name> is normalized using skill-creator naming rules:
My Plugin → my-pluginMy--Plugin → my-plugin-skills/hooks/scripts/assets/.mcp.json.app.jsonmarketplace.json always lives at <repo-root>/.agents/plugins/marketplace.json.<home> as the root:
~/.agents/plugins/marketplace.json plus ./plugins/<plugin-name>.name plus optional interface.displayName.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.policy.installationpolicy.authenticationcategorypolicy.installation: "AVAILABLE"policy.authentication: "ON_INSTALL"policy.installation values:
NOT_AVAILABLEAVAILABLEINSTALLED_BY_DEFAULTpolicy.authentication values:
ON_INSTALLON_USEpolicy.products as an override. Omit it unless the user explicitly requests product gating.{
"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"
}
]
}
plugin.json "name" are always the same normalized plugin name..codex-plugin/plugin.json present.--force only when overwrite is intentional.interface.displayName.policy.installation, policy.authentication, and category even if their values are defaults.policy.products only when the user explicitly asks for that override.source.path relative to repo root as ./plugins/<plugin-name>.For the exact canonical sample JSON for both plugin manifests and marketplace entries, use:
references/plugin-json-spec.mdAfter editing SKILL.md, run:
python3 <path-to-skill-creator>/scripts/quick_validate.py .agents/skills/plugin-creator