Agent Skills
› openai/plugins
› plugin-creator
plugin-creator
GitHub用于为 Codex 创建和生成插件目录结构。自动创建包含占位符的 plugin.json，支持添加 skills、hooks 等可选组件，并管理个人及仓库级的 marketplace 元数据条目。
Trigger Scenarios
用户需要创建新的 Codex 插件
用户希望初始化或更新插件目录结构
用户需要生成或修改 marketplace.json 以配置插件排序和可用性
Install
npx skills add openai/plugins --skill plugin-creator -g -y
SKILL.md
Frontmatter
{
"name": "plugin-creator",
"description": "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 personal plugin, add optional plugin structure, or generate or update personal or repo-root `.agents\/plugins\/marketplace.json` entries for plugin ordering and availability metadata."
}
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/<plugin-name>.
python3 .agents/skills/plugin-creator/scripts/create_basic_plugin.py <plugin-name>
-
Open
<plugin-path>/.codex-plugin/plugin.jsonand replace[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 .agents/skills/plugin-creator/scripts/create_basic_plugin.py my-plugin --with-marketplace
If the current Git repo already has .agents/plugins/marketplace.json and the user has not said
whether the plugin is personal or shared with their team, ask before generating a marketplace entry.
When they choose the repo marketplace, use:
python3 .agents/skills/plugin-creator/scripts/create_basic_plugin.py my-plugin \
--path ./plugins \
--marketplace-path ./.agents/plugins/marketplace.json \
--with-marketplace
- Generate/adjust optional companion folders as needed:
python3 .agents/skills/plugin-creator/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 ~/code/plugins).
What this skill creates
- Default marketplace-backed scaffolds are personal:
~/plugins/<plugin-name>/plus~/.agents/plugins/marketplace.json. - If the current Git repo already has
.agents/plugins/marketplace.jsonand the user has not said personal vs team, ask which marketplace to update before generating a marketplace entry. - 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
interfacesection. - Creates or updates the selected marketplace when
--with-marketplaceis set.- If the marketplace file does not exist yet, seed top-level
nameplusinterface.displayNameplaceholders before adding the first plugin entry.
- If the marketplace file does not exist yet, seed top-level
<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 plugins use
~/.agents/plugins/marketplace.json. - Repo/team plugins use
<repo-root>/.agents/plugins/marketplace.json. - 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 selected 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": "[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.jsonpresent. - Keep manifest values as placeholders until a human or follow-up step explicitly fills them.
- 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>. - 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.md
Validation
After editing SKILL.md, run:
python3 <path-to-skill-creator>/scripts/quick_validate.py .agents/skills/plugin-creator
Version History
- 11c74d6 Current 2026-07-19 09:27
