plugin-creator
Create and scaffold plugin directories for Codex with a required `.codex-plugin/plugin.json`, optional plugin folders/files, valid manifest defaults, and personal-marketplace entries by default. Use when Codex needs to create a new personal plugin, add optional plugin structure, generate or update marketplace entries for plugin ordering and availability metadata, or update an existing local plugin during development with the CLI-driven cachebuster and reinstall flow.
- License 许可
- Apache-2.0
- 所属仓库
- iokaio/vcp
- 最近更新
- 2026-10-06
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- plugin-creator
- description
- Create and scaffold plugin directories for Codex with a required `.codex-plugin/plugin.json`, optional plugin folders/files, valid manifest defaults, and personal-marketplace entries by default. Use when Codex needs to create a new personal plugin, add optional plugin structure, generate or update marketplace entries for plugin ordering and availability metadata, or update an existing local plugin during development with the CLI-driven cachebuster and reinstall flow.
02 资源文件 10
- 参考文档agents/openai.yaml339 B
- 资产文件assets/plugin-creator-small.svg1.3 KB
- 资产文件assets/plugin-creator.png1.5 KB
- 参考文档references/installing-and-updating.md5.9 KB
- 参考文档references/plugin-json-spec.md9.0 KB
- 脚本scripts/create_basic_plugin.py11.5 KB
- 脚本scripts/identifier_validation.py784 B
- 脚本scripts/read_marketplace_name.py1.6 KB
- 脚本scripts/update_plugin_cachebuster.py3.0 KB
- 脚本scripts/validate_plugin.py21.2 KB
03 SKILL.md 正文
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 the skill root (the directory containing this `SKILL.md`).
# By default creates in `~/plugins/<plugin-name>`.
python3 scripts/create_basic_plugin.py <plugin-name>
-
Edit
<plugin-path>/.codex-plugin/plugin.jsonwhen the request gives specific metadata. The scaffold starts with valid defaults and must not contain[TODO: ...]placeholders. -
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 <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.
- 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
<parent-plugin-directory> is the directory where the plugin folder <plugin-name> will be
created (for example ~/plugins).
- 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 <marketplace-json-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
- Default marketplace-backed scaffolds use the personal marketplace file at
~/.agents/plugins/marketplace.json, with plugins generally being stored in~/plugins/<plugin-name>/. - 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 validated schema shape that the ingestion path accepts.
- Creates or updates
~/.agents/plugins/marketplace.jsonwhen--with-marketplaceis set.- If the marketplace file does not exist yet, seed a personal marketplace root before adding the first plugin entry.
<plugin-name>is normalized using skill-creator naming rules:My Plugin→my-pluginMy--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
- Personal-marketplace creation defaults to
~/.agents/plugins/marketplace.json. Here, "personal marketplace" means the marketplace whose file is at that path. - Repo/team marketplace creation is opt-in through both
--pathand--marketplace-path, only when the user specifically requests it. --marketplace-nameis an exception path. Use it only when the defaultpersonalmarketplace name is already taken and you need to seed a different new marketplace file.- Do not use
--marketplace-nameto rename an existing marketplace file in place. If the file already exists, its top-levelnamemust already match. - 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/read_marketplace_name.py; stop if 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. - Before updating existing plugins, validate both identifiers before changing files or constructing install commands.
- In either location, the generated source path remains
./plugins/<plugin-name>. - Marketplace root metadata supports top-level
nameplus optionalinterface.displayName. - Treat plugin order in
plugins[]as render order in Codex. Append new entries unless a user explicitly asks to reorder the list. displayNamebelongs inside the marketplaceinterfaceobject, not individualplugins[]entries.- Each generated marketplace entry must include all of:
policy.installationpolicy.authenticationcategory
- Default new entries to:
policy.installation: "AVAILABLE"policy.authentication: "ON_INSTALL"
- Override defaults only when the user explicitly specifies another allowed value.
- Allowed
policy.installationvalues:NOT_AVAILABLEAVAILABLEINSTALLED_BY_DEFAULT
- Allowed
policy.authenticationvalues:ON_INSTALLON_USE
- Treat
policy.productsas 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
--forceonly 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 apluginsarray, 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
- Outer folder name and
plugin.json"name"are always the same normalized plugin name. - Do not remove required structure; keep
.codex-plugin/plugin.jsonpresent. - Do not leave
[TODO: ...]placeholders in plugin manifests. - Keep
appsandmcpServersout ofplugin.jsonunless 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
--forceonly when overwrite is intentional. - Preserve any existing marketplace
interface.displayName. - When generating marketplace entries, always write
policy.installation,policy.authentication, andcategoryeven if their values are defaults. - Add
policy.productsonly when the user explicitly asks for that override. - Keep marketplace
source.pathrelative to the selected marketplace root as./plugins/<plugin-name>. - Only use
--marketplace-namewhen creating a new marketplace file whose name should not bepersonalbecause that name is already taken or installed elsewhere. - If Codex would need approval to write the marketplace file, ask for that approval before 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.
- For updates to an existing local plugin during development, do not hand-edit marketplace config
or
marketplace.json. Use the update flow documented inreferences/installing-and-updating.mdandscripts/update_plugin_cachebuster.py. - Do not tell the user to run
codex plugin marketplace addfor the default personal-marketplace flow. That command is for explicit non-default marketplace configuration, not for the standard~/.agents/plugins/marketplace.jsonpath. - If the user provided a non-default
--marketplace-path, make sure that marketplace is installed before giving reinstall instructions. Usecodex plugin marketplace add <path-to-marketplace-root>when that explicit marketplace has not been configured yet. - When the workflow created or updated a marketplace-backed plugin, end the final user-facing
response with a short Codex app handoff. Say
To view this in the Codex app:and writeView <normalized plugin name>andShare <normalized plugin name>as Markdown links, not raw URLs or code spans. - The View deeplink uses
codex://plugins/<normalized plugin name>?marketplacePath=<absolute marketplace.json path>. The Share deeplink uses the same URL with&mode=share. - Replace the placeholders with the real normalized plugin name and absolute
marketplace.jsonpath from the scaffolded plugin. URL-encode the path segment and query value when needed. - Do not add
pluginNameorhostIdquery parameters to these deeplinks. Codex derives both after the user clicks the link. - Do not emit the
View <normalized plugin name>orShare <normalized plugin name>links when no marketplace entry was created or updated.
Reference to exact spec sample
For the exact canonical sample JSON for both plugin manifests and marketplace entries, use:
references/plugin-json-spec.mdreferences/installing-and-updating.mdfor update/reinstall guidance while iterating on an existing local plugin, plus the new-thread pickup behavior after reinstall
Validation
After editing SKILL.md, run:
python3 ../skill-creator/scripts/quick_validate.py .
Before handing back a generated plugin, run:
python3 scripts/validate_plugin.py <plugin-path>
04 同仓库更多 Skills
skill-installer
Install Codex skills into $CODEX_HOME/skills from a curated list or a GitHub repo path. Use when a user asks to list installable skills, install a curated skill, or install a skill from another repo (including private repos).
skill-creator
Create or update a Codex skill with appropriately scoped instructions and any needed supporting resources.
review-agent
Perform a read-only, defect-first review of a specified code change and return every actionable finding. Use when another agent delegates review of uncommitted changes, a base-branch diff, a commit, or custom review instructions.
openai-docs
Use for Codex models/pricing, scheduled tasks, skills, settings, setup, troubleshooting, customization, automations, and self-knowledge—including 'you,' 'your,' 'this app,' or 'this coding agent' when they refer to Codex—and for OpenAI APIs/products and ChatGPT Work. Also use for model choice/migration, prompting, SDKs, Responses, Realtime, agents, evals, and Chat/Work/Codex comparisons. Do not use for generic app/software tasks that merely mention Codex.
imagegen
Generate or edit raster images when the task benefits from AI-created bitmap visuals such as photos, illustrations, textures, sprites, mockups, or transparent-background cutouts. Use when Codex should create a brand-new image, transform an existing image, or derive visual variants from references, and the output should be a bitmap asset rather than repo-native code or vector. Do not use when the task is better handled by editing existing SVG/vector/code-native assets, extending an established icon or logo system, or building the visual directly in HTML/CSS/canvas.
webapp-testing
暂无简介