前言¶

单个 Agent Skill 很适合封装「一件事怎么做」：一份 SKILL.md、若干脚本和参考资料，Agent 按需加载即可。但团队一旦要把多份 Skill、MCP 连接、生命周期钩子和展示资源一起分发，再靠零散目录复制就不稳了——需要一个有稳定身份、可安装、可进目录展示的打包单元。

在 Codex / ChatGPT 这套体系里，这个单元叫 Plugin。OpenAI 官方内置的 plugin-creator Skill，就是专门用来创建和脚手架 Plugin 目录的：自动生成必填的 .codex-plugin/plugin.json，按需补齐可选组件占位，并能写入本地或仓库级的 marketplace.json，方便你在 Plugins Directory 里测试和分发。

本文依据 OpenAI 官方仓库中的 plugin-creator 原文、plugin.json 规范样例，以及 Build plugins 文档交叉核实后整理。

这是什么¶

plugin-creator 是 OpenAI 维护的系统级 Agent Skill（位于 openai/skills 仓库的 skills/.system/plugin-creator）。.system 目录下的 Skill 会随较新版本的 Codex 自动安装，一般不必再手动拷贝。

按官方描述，它的职责是：

• 为 Codex 创建并脚手架 Plugin 目录；
• 始终生成必填清单 .codex-plugin/plugin.json（含完整 schema 形状与可编辑占位）；
• 按需创建 skills/、hooks/、scripts/、assets/、.mcp.json、.app.json 等可选结构；
• 在需要时生成或更新仓库根（或用户主目录）下的 .agents/plugins/marketplace.json，控制插件在 UI 中的排序与可用性元数据。

一句话定位：Skill 解决「怎么做」；Plugin 解决「怎么打包、安装、分发」；plugin-creator 负责把后者从零搭好架子。

核心功能与亮点¶

结合 SKILL.md、脚手架脚本 scripts/create_basic_plugin.py 与官方构建文档，已核实的能力如下。

1、标准化清单入口
每个 Plugin 的入口都是 .codex-plugin/plugin.json。只有这份清单应放在 .codex-plugin/ 下；skills/、hooks/、assets/、.mcp.json、.app.json 等放在 Plugin 根目录。脚手架会按规范写出完整字段形状（含 interface 展示块），便于你后续替换占位内容。

2、名称规范化
插件名会归一化为小写连字符形式，且长度不超过 64 字符。例如 My Plugin → my-plugin，连续分隔符会折叠。生成的文件夹名与 plugin.json 里的 "name" 必须一致。

3、可选组件一键占位
通过脚本参数可按需创建：

• --with-skills → skills/
• --with-hooks → hooks/
• --with-scripts → scripts/
• --with-assets → assets/
• --with-mcp → .mcp.json（初始为 {"mcpServers": {}}）
• --with-apps → .app.json（初始为 {"apps": {}}）

4、Marketplace 登记
加上 --with-marketplace 后，会创建或更新 marketplace.json。仓库级默认路径是 <repo-root>/.agents/plugins/marketplace.json；个人级常用 ~/.agents/plugins/marketplace.json。新建条目默认：

• policy.installation: "AVAILABLE"
• policy.authentication: "ON_INSTALL"
• category: "Productivity"

plugins[] 的顺序即 Codex 侧的展示顺序；新条目默认追加到列表末尾。

5、对话内也可直接调用
官方构建文档说明：在 ChatGPT Work 模式可用 @plugin-creator，在 Codex 中可用 $plugin-creator。不必先手写目录，把需求（含 MCP 的 plugin_asdk_app... ID、是否要个人 marketplace 等）说清楚即可。

安装与启用¶

在 Codex / ChatGPT 中使用（推荐）¶

plugin-creator 属于系统 Skill，较新的 Codex 会自动带上。日常用法是在对话里显式调用：

• Codex：$plugin-creator
• ChatGPT（Work 模式）：@plugin-creator

官方示例提示词（测试带 MCP 的本地插件时）类似：

@plugin-creator create a plugin for ChatGPT and Codex using my MCP server.
Use plugin_asdk_app_6a4c0062f3b88191855c0a80eac5d53d and name it Acme Support.
Include a personal marketplace entry so I can test it locally.

生成后按文档核对：.app.json 是否指向正确的 plugin_asdk_app... ID；.codex-plugin/plugin.json 的 apps 是否指向 ./.app.json；需要可复用工作流时再在 skills/ 下补充 SKILL.md。

直接跑脚手架脚本¶

若本地已有该 Skill 目录（例如随 Codex 安装到 .agents/skills/plugin-creator，或从官方仓库检出），也可直接执行脚本。仓库版默认在当前仓库下创建 plugins/<plugin-name>：

# 插件名会归一化为小写连字符，且 <= 64 字符
# 默认输出到 <repo_root>/plugins/<plugin-name>
python3 .agents/skills/plugin-creator/scripts/create_basic_plugin.py <plugin-name>

打开生成的 .codex-plugin/plugin.json，把 [TODO: ...] 占位替换成真实元数据。

需要同时写入 marketplace 时：

python3 .agents/skills/plugin-creator/scripts/create_basic_plugin.py my-plugin --with-marketplace

个人主目录下的本地插件，可显式指定路径：

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

覆盖已有文件或同名 marketplace 条目时才使用 --force，避免误覆盖。

关于其他 AI 编程工具¶

plugin-creator 本身是标准 SKILL.md 格式，Cursor、Claude Code 等同样能读取并按说明执行脚手架逻辑。但生成的 Plugin 包（.codex-plugin/plugin.json + marketplace）面向的是 Codex / ChatGPT Plugins Directory；在其他工具里应把它理解为「按 OpenAI Plugin 规范搭目录」，而不是等价于各工具自己的扩展市场。

补充：openai/skills 仓库 README 已提示示例与文档正向 openai/plugins 与 Build plugins 迁移；系统 Skill 的调用方式仍以 Codex / ChatGPT 内置的 $plugin-creator / @plugin-creator 为准。

典型用法示例¶

1. 最小可用 Plugin 结构（手工对照）¶

官方文档给出的最小形态与脚手架目标一致：

mkdir -p my-first-plugin/.codex-plugin
mkdir -p my-first-plugin/skills/hello

.codex-plugin/plugin.json：

{
  "name": "my-first-plugin",
  "version": "1.0.0",
  "description": "Reusable greeting workflow",
  "skills": "./skills/"
}

skills/hello/SKILL.md：

---
name: hello
description: Greet the user with a friendly message.
---

Greet the user warmly and ask how you can help.

再用 @plugin-creator 或手动编辑，把该插件登记进 marketplace。

2. Marketplace 条目形状¶

脚手架写入的插件条目形如：

{
  "name": "plugin-name",
  "source": {
    "source": "local",
    "path": "./plugins/plugin-name"
  },
  "policy": {
    "installation": "AVAILABLE",
    "authentication": "ON_INSTALL"
  },
  "category": "Productivity"
}

全新 marketplace 文件还会带上根级元数据：

{
  "name": "[TODO: marketplace-name]",
  "interface": {
    "displayName": "[TODO: Marketplace Display Name]"
  },
  "plugins": []
}

注意：displayName 属于 marketplace 根上的 interface，不要写进单个 plugins[] 条目。source.path 相对 marketplace 根目录 解析（不是相对 .agents/plugins/ 文件夹本身）。

策略字段允许值（来自 Skill 原文）：

• policy.installation：NOT_AVAILABLE | AVAILABLE | INSTALLED_BY_DEFAULT
• policy.authentication：ON_INSTALL | ON_USE
• policy.products 仅在明确要求按产品门控时再写

3. plugin.json 里常见字段¶

规范样例（references/plugin-json-spec.md）中，除基础身份字段外，常见还有：

• skills / hooks / mcpServers / apps：相对路径，建议以 ./ 开头；
• interface.displayName、shortDescription、longDescription：目录与详情页展示；
• interface.defaultPrompt：最多 3 条，单条建议约 50 字符、上限 128 字符；
• interface 下的图标、截图等资源路径，截图需为 PNG 且放在 ./assets/。

路径类字段是「在默认发现之外的补充」，不会替换默认组件发现规则。

4. 用 CLI 管理 marketplace 源¶

官方文档还提供了不手改配置的 marketplace 管理命令（与脚手架互补）：

codex plugin marketplace add owner/repo
codex plugin marketplace add owner/repo --ref main
codex plugin marketplace add https://github.com/example/plugins.git --sparse .agents/plugins
codex plugin marketplace add ./local-marketplace-root

codex plugin marketplace list
codex plugin marketplace upgrade
codex plugin marketplace remove marketplace-name

本地插件改完后，通常需要重启 ChatGPT 桌面端或按当前环境的刷新流程，才能在 Plugins Directory 看到更新。

适用场景与注意事项¶

适合：

• 要把多份 Skill、MCP、钩子打成「可安装包」给团队复用；
• 想在仓库里维护 .agents/plugins/marketplace.json，给同事统一插件清单；
• 个人本机试验插件，再决定是否发布到公共 Plugin Directory；
• 已有 MCP 连接（含 plugin_asdk_app... ID），需要快速接线成 Plugin。

使用时注意：

1. 先问清落点：Skill 要求在位置不明确时，先确认是仓库内插件还是个人主目录插件，再写 marketplace。
2. 占位不要当成品：仓库版脚手架会留下 [TODO: ...]，发布或认真测试前必须改成真实元数据。
3. 目录约定：仅 plugin.json 放在 .codex-plugin/；其它组件放在插件根目录。
4. 谨慎 --force：覆盖已有清单或同名 marketplace 条目时才用。
5. 个人目录示例不唯一：文档示例常见 ~/.codex/plugins/，Skill 脚本示例常用 ~/plugins/；真正生效的是 marketplace 里 source.path 相对 marketplace 根的解析结果，两边对齐即可。
6. 公开分发另有流程：本地 / 仓库 marketplace 主要用于创作、测试与团队内分发；公开发布到通用插件目录需遵循官方 Build plugins 后续步骤，本文不展开未核实细节。

小结¶

plugin-creator 把 Codex Plugin 从「记得一堆目录约定」变成「一条命令或一次对话就能搭好骨架」。对已经会写 Skill 的开发者来说，它是迈向可安装、可排序、可团队分发的标准下一步；对刚接触 Plugin 的人来说，它也是对照官方规范最快的入门路径。

官方 Skill 目录：
https://github.com/openai/skills/tree/main/skills/.system/plugin-creator

构建与打包文档：
https://developers.openai.com/codex/plugins/build

Skills 总览：
https://developers.openai.com/codex/skills