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 <repo_root>/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 的排序中，生成或更新仓库的 marketplace 条目：

# 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

对于本地用户目录插件，将 <home> 视为根目录并使用：

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> \
  --with-skills --with-hooks --with-scripts --with-assets --with-mcp --with-apps --with-marketplace

<parent-plugin-directory> 是将创建插件文件夹 <plugin-name> 的目录（例如 ~/code/plugins）。

此技能创建的内容

• 如果用户尚未明确插件位置，请在生成 marketplace 条目前询问他们要使用仓库本地插件还是本地用户目录插件。
• 在 /<parent-plugin-directory>/<plugin-name>/ 创建插件根目录。
• 始终创建 /<parent-plugin-directory>/<plugin-name>/.codex-plugin/plugin.json。
• 使用完整的 schema 结构、占位值和完整的 interface 部分填充清单文件。
• 设置 --with-marketplace 时，创建或更新 <repo-root>/.agents/plugins/marketplace.json。
  • 如果 marketplace 文件尚不存在，则先填入顶层 name 和 interface.displayName 占位值，再添加第一个插件条目。
• <plugin-name> 按照 skill-creator 命名规则进行规范化：
  • My Plugin → my-plugin
  • My--Plugin → my-plugin
  • 下划线、空格和标点符号会转换为 -
  • 结果为小写且以连字符分隔，并将连续的连字符合并
• 支持可选创建：
  • skills/
  • hooks/
  • scripts/
  • assets/
  • .mcp.json
  • .app.json

Marketplace 工作流

• marketplace.json 始终位于 <repo-root>/.agents/plugins/marketplace.json。
• 对于本地用户目录插件，使用相同约定并将 <home> 作为根目录： ~/.agents/plugins/marketplace.json 加上 ./plugins/<plugin-name>。
• Marketplace 根元数据支持顶层 name，以及可选的 interface.displayName。
• 将 plugins[] 中的插件顺序视为 Codex 中的显示顺序。除非用户明确要求重新排序，否则将新条目追加到末尾。
• displayName 应放在 marketplace 的 interface 对象内，而不是单个 plugins[] 条目中。
• 每个生成的 marketplace 条目都必须包含以下所有内容：
  • 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"
}

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

• 如果 <repo-root>/.agents/plugins/marketplace.json 尚不存在，则创建该文件，包含顶层 "name"、带有 "displayName" 的 "interface" 对象以及 plugins 数组，然后添加新条目。

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

{
  "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>。

精确规范示例参考

有关插件清单和市场条目的规范 JSON 示例，请使用：

• references/plugin-json-spec.md

验证

编辑 SKILL.md 后，运行：

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