为 Codex 创建和脚手架化插件目录（含…

当需要新建本地 Codex 插件、添加可选插件结构，或生成/更新仓库根目录的 marketplace.json 条目时使用。

适用场景

解决思路

1. 从仓库根目录运行脚手架脚本：`python3 .agents/skills/plugin-creator/scripts/create_basic_plugin.py <plugin-name>`（默认创建在 `<repo_root>/plugins/<plugin-name>`；也可用绝对路径替换 `.agents/...`）。
2. 打开 `<plugin-path>/.codex-plugin/plugin.json`，替换其中的 `[TODO: ...]` 占位符。
3. 当插件需要出现在 Codex UI 排序中时，生成或更新仓库 marketplace 条目：`python3 .agents/skills/plugin-creator/scripts/create_basic_plugin.py my-plugin --with-marketplace`（marketplace.json 始终位于 `<repo-root>/.agents/plugins/marketplace.json`）。
4. 对于 home-local 插件，把 `<home>` 当作根目录：`python3 .agents/skills/plugin-creator/scripts/create_basic_plugin.py my-plugin --path ~/plugins --marketplace-path ~/.agents/plugins/marketplace.json --with-marketplace`。
5. 按需生成可选伴随文件夹：`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`）。
6. 如果用户未明确插件位置，在生成 marketplace 条目前先询问是要 repo-local 插件还是 home-local 插件。
7. 在 `/<parent-plugin-directory>/<plugin-name>/` 创建插件根目录。
8. 始终创建 `/<parent-plugin-directory>/<plugin-name>/.codex-plugin/plugin.json`。
9. 用完整 schema 形状、占位符值和完整的 `interface` 段填充 manifest。
10. 当设置 `--with-marketplace` 时，创建或更新 `<repo-root>/.agents/plugins/marketplace.json`；若文件尚不存在，先写入顶层 `name` 和 `interface.displayName` 占位符，再加入第一个插件条目。
11. 按 skill-creator 命名规则规范化 `<plugin-name>`：`My Plugin` → `my-plugin`，`My--Plugin` → `my-plugin`，下划线、空格和标点转换为 `-`，结果为小写连字符分隔且连续连字符折叠。
12. 支持可选创建：`skills/`、`hooks/`、`scripts/`、`assets/`、`.mcp.json`、`.app.json`。
13. marketplace.json 始终位于 `<repo-root>/.agents/plugins/marketplace.json`；home-local 插件使用相同约定，以 `<home>` 为根：`~/.agents/plugins/marketplace.json` 加 `./plugins/<plugin-name>`。
14. marketplace 根元数据支持顶层 `name` 加可选的 `interface.displayName`。
15. 把 `plugins[]` 中的插件顺序视为 Codex 中的渲染顺序；除非用户明确要求重排，否则追加新条目。
16. `displayName` 属于 marketplace 的 `interface` 对象，而不是单个 `plugins[]` 条目。
17. 每个生成的 marketplace 条目必须包含：`policy.installation`、`policy.authentication`、`category`。
18. 新条目默认设为 `policy.installation: "AVAILABLE"` 和 `policy.authentication: "ON_INSTALL"`；仅当用户明确指定其他允许值时才覆盖默认值。
19. 允许的 `policy.installation` 值：`NOT_AVAILABLE`、`AVAILABLE`、`INSTALLED_BY_DEFAULT`。
20. 允许的 `policy.authentication` 值：`ON_INSTALL`、`ON_USE`。
21. 把 `policy.products` 视为覆盖项；除非用户明确要求产品门控，否则省略它。
22. 生成的插件条目形状为：{"name":"plugin-name","source":{"source":"local","path":"./plugins/plugin-name"},"policy":{"installation":"AVAILABLE","authentication":"ON_INSTALL"},"category":"Productivity"}。
23. 仅当有意替换同一插件名的现有 marketplace 条目时才使用 `--force`。
24. 若 `<repo-root>/.agents/plugins/marketplace.json` 尚不存在，用顶层 `"name"`、包含 `"displayName"` 的 `"interface"` 对象和 `plugins` 数组创建它，然后加入新条目。
25. 全新 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"}]}。
26. 外层文件夹名和 `plugin.json` 的 `"name"` 始终是同一个规范化插件名。
27. 不要移除必需结构；保持 `.codex-plugin/plugin.json` 存在。
28. 在人工或后续步骤明确填充前，保持 manifest 值为占位符。
29. 若在现有插件路径内创建文件，仅当有意覆盖时才使用 `--force`。
30. 保留任何现有的 marketplace `interface.displayName`。
31. 生成 marketplace 条目时，即使值为默认值，也始终写入 `policy.installation`、`policy.authentication` 和 `category`。
32. 仅当用户明确要求该覆盖时才添加 `policy.products`。
33. 保持 marketplace `source.path` 相对于仓库根为 `./plugins/<plugin-name>`。
34. 需要插件 manifest 和 marketplace 条目的精确规范示例 JSON 时，参考 `references/plugin-json-spec.md`。
35. 编辑 `SKILL.md` 后运行验证：`python3 <path-to-skill-creator>/scripts/quick_validate.py .agents/skills/plugin-creator`。

适用边界 · 注意事项

• 不适用于非 Codex 插件系统或不需要 `.codex-plugin/plugin.json` 的场景。
• 当用户未明确指定其他允许值时，不要覆盖 marketplace 的默认 policy 值或添加 `policy.products`。
• 除非有意替换现有条目或覆盖文件，否则不要使用 `--force`。