plugin-creator

插件创建器

快速开始

1. 运行脚手架脚本：

  # 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>

2. 打开 <plugin-path>/.codex-plugin/plugin.json，并替换 [TODO: ...] 占位符。

3. 当插件需要出现在 Codex UI 排序中时，生成或更新个人市场条目：

# Personal marketplace entries default to ~/.agents/plugins/marketplace.json.
python3 .agents/skills/plugin-creator/scripts/create_basic_plugin.py my-plugin --with-marketplace

如果当前 Git 仓库已有 .agents/plugins/marketplace.json，且用户尚未说明插件是个人使用还是与团队共享，请在生成市场条目前先询问。 如果用户选择仓库市场，请使用：

python3 .agents/skills/plugin-creator/scripts/create_basic_plugin.py my-plugin \
  --path ./plugins \
  --marketplace-path ./.agents/plugins/marketplace.json \
  --with-marketplace

4. 根据需要生成或调整可选的配套文件夹：

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> 是用于创建插件文件夹 <plugin-name> 的目录（例如 ~/code/plugins）。

此技能会创建的内容

• 默认由市场提供支持的脚手架为个人用途：~/plugins/<plugin-name>/ 以及 ~/.agents/plugins/marketplace.json。
• 如果当前 Git 仓库已有 .agents/plugins/marketplace.json，且用户尚未说明是个人用途还是团队用途，请在生成市场条目前询问要更新哪个市场。
• 在 /<parent-plugin-directory>/<plugin-name>/ 创建插件根目录。
• 始终创建 /<parent-plugin-directory>/<plugin-name>/.codex-plugin/plugin.json。
• 填充清单，包含完整的架构结构、占位值以及完整的 interface 部分。
• 设置 --with-marketplace 时，创建或更新所选市场。
  • 如果市场文件尚不存在，则在添加第一个插件条目前，填入顶层 name 和 interface.displayName 占位符。
• <plugin-name> 将按照 skill-creator 命名规则进行规范化：
  • My Plugin → my-plugin
  • My--Plugin → my-plugin
  • 下划线、空格和标点符号会转换为 -
  • 结果为小写，并以连字符分隔，连续的连字符会合并
• 支持按需创建：
  • skills/
  • hooks/
  • scripts/
  • assets/
  • .mcp.json
  • .app.json

市场工作流

• 个人插件使用 ~/.agents/plugins/marketplace.json。
• 仓库／团队插件使用 <repo-root>/.agents/plugins/marketplace.json。
• 市场根元数据支持顶层 name，以及可选的 interface.displayName。
• 将 plugins[] 中的插件顺序视为 Codex 中的显示顺序。除非用户明确要求重新排序，否则将新条目追加到末尾。
• displayName 应放在市场的 interface 对象中，而不是单个 plugins[] 条目中。
• 每个生成的市场条目都必须包含以下各项：
  • policy.installation
  • policy.authentication
  • category
• 新条目的默认值为：
  • policy.installation: "AVAILABLE"
  • policy.authentication: "ON_INSTALL"
• 仅当用户明确指定其他允许值时，才覆盖默认值。
• 允许的 policy.installation 值：
  • NOT_AVAILABLE
  • AVAILABLE
  • INSTALLED_BY_DEFAULT
• 允许的 policy.authentication 值：
  • ON_INSTALL
  • ON_USE
• 将 policy.products 视为覆盖项。除非用户明确要求限制产品，否则省略此项。
• 生成的插件条目结构如下：

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

• 仅当有意替换同名插件的现有市场条目时，才使用 --force。

• 如果所选市场文件尚不存在，则创建该文件，其中包含顶层 "name"、带有 "displayName" 的 "interface" 对象以及 plugins 数组，然后添加新条目。

• 对于全新的市场文件，根对象应如下所示：

{
  "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" 始终使用相同的规范化插件名称。
• 不要删除必需结构；保留 .codex-plugin/plugin.json。
• 将清单值保留为占位符，直到人工或后续步骤明确填写。
• 如果在现有插件路径中创建文件，仅在有意覆盖时使用 --force。
• 保留任何现有市场条目的 interface.displayName。
• 生成市场条目时，始终写入 policy.installation、policy.authentication 和 category，即使其值为默认值。
• 仅当用户明确要求覆盖时，才添加 policy.products。
• 将市场条目的 source.path 保持为相对于所选市场根目录的路径：./plugins/<plugin-name>。
• 如果此工作流创建或更新了一个关联市场的插件，请在最终面向用户的回复末尾添加一段简短的 Codex 应用交接说明。写上 To view this in the Codex app:，并将 View <normalized plugin name> 和 Share <normalized plugin name> 写为 Markdown 链接，不要使用原始 URL 或代码跨度。
• View 深层链接使用 codex://plugins/<normalized plugin name>?marketplacePath=<absolute marketplace.json path>。 Share 深层链接使用相同的 URL，并附加 &mode=share。
• 将占位符替换为实际规范化插件名称和从搭建的插件获取的绝对 marketplace.json 路径。必要时对路径段和查询值进行 URL 编码。
• 不要在这些深层链接中添加 pluginName 或 hostId 查询参数。用户点击链接后，Codex 会自动推导这两项。
• 如果未创建或更新市场条目，不要输出 View <normalized plugin name> 或 Share <normalized plugin name> 链接。

精确规范示例的参考

如需查看插件清单和市场条目的规范 JSON 示例，请使用：

• references/plugin-json-spec.md

验证

编辑 SKILL.md 后，运行：

python3 <path-to-skill-creator>/scripts/quick_validate.py .agents/skills/plugin-creator