构建自己的插件
基于官方 Codex 插件教程，面向新手讲清插件、skill、marketplace 的边界，以及第一版插件应该怎么安全发布。
Codex plugin 不是“把一段提示词包起来”这么简单。它是把 skills、MCP 配置、app integration 和生命周期配置打包给别人安装的分发单元。新手最容易做错的是：本来只需要一个本地 skill，却一上来做 plugin、marketplace、安装策略和发布目录。
先记住边界：自己用，先写 skill；团队复用，再考虑 plugin；要让 Codex 能发现和安装 plugin，才需要 marketplace。
先理解：plugin 解决什么问题
Skill 解决“Codex 在某类任务上应该怎么做”。它更像一份可复用工作说明。
Plugin 解决“把一组能力打包给别人安装”。它可以包含 skill，也可以包含 MCP server、apps、hooks 等配置。
Marketplace 解决“Codex 从哪里发现这些 plugin”。它不是商店概念，而是一个 JSON catalog。官方说明，一个 marketplace 可以测试时只放一个 plugin，后续再扩展成 curated catalog。
所以第一版不要问“怎么发布插件”，先问“我是不是已经有一个被反复使用、稳定、有边界的能力需要分发”。
怎么判断该不该做 plugin
适合做 plugin：
- 这个能力已经被你或团队反复使用，不是临时脚本。
- 它有清楚的名称、说明、输入边界和使用场景。
- 安装后别人能直接在 Codex 里发现并调用。
- 它可能需要一起分发 skills、MCP、hooks 或 app integration。
- 你愿意维护版本号、说明文案、安装策略和兼容性。
不适合做 plugin：
- 只是一个还没跑稳的提示词。
- 只服务你当前这个仓库的一次性任务。
- 你还没想清楚它会不会读敏感文件、调用外部服务、运行命令。
- 你只是想让目录看起来更“工程化”。
新手第一步应该是本地 skill。skill 跑稳以后，再让 $plugin-creator 帮你 scaffold plugin。
第一版插件应该长什么样
第一版只打包一个 skill 就够了。官方最小结构要求插件目录里有 .codex-plugin/plugin.json，manifest 里至少要有稳定的插件名、版本、描述和 skills 路径。插件名要用稳定的 kebab-case，因为 Codex 会把它作为插件标识和组件命名空间。
Skill 放在 skills/<skill-name>/SKILL.md。不要一开始就塞多个 skill、多个 MCP server 和复杂 hooks。第一版越小，越容易定位问题。
写说明时不要只写“提高效率”。要写清楚：
- 这个插件解决什么任务。
- 什么时候应该调用。
- 什么时候不应该调用。
- 是否需要账号、token、MCP server 或外部网络。
- 安装后如何确认它已经被 Codex 识别。
marketplace 怎么理解
Marketplace 是 Codex 能读取的 plugin catalog。官方支持 repo marketplace 和 personal marketplace。
Repo marketplace 通常放在仓库的 .agents/plugins/marketplace.json，适合团队或项目共享。Personal marketplace 通常放在 ~/.agents/plugins/marketplace.json，适合个人工作流。
source.path 指向插件目录，并且官方要求本地相对路径保持在 marketplace root 内、以 ./ 开头。这个细节很重要：它决定 Codex 实际从哪里加载插件。
一个 marketplace 不需要只服务一个 plugin。测试阶段可以只有一个，稳定后再逐步变成团队精选清单。
新手推荐流程
先把能力写成 skill，并在真实任务里跑 3 次以上。每次记录它哪里误触发、哪里没讲清楚、哪里依赖了本机环境。
再用 $plugin-creator 生成插件骨架。官方推荐这个方式，因为它能 scaffold 必需的 .codex-plugin/plugin.json，也可以生成本地 marketplace entry。
然后只在本地 marketplace 安装。确认 Codex 能看到插件、能看到 skill、调用后行为稳定。
最后再放进 repo marketplace。团队安装前，先把版本号、说明、安装面文案、权限需求和外部依赖写清楚。
新手常见坑
- 把未稳定的 skill 直接做成 plugin：一旦别人安装，问题就变成分发问题。
- marketplace 路径写错：Codex 找不到插件，或者加载了旧目录。
- 修改插件后忘记重启 Codex：本地安装不会自动读到所有变化。
- 插件说明太泛：用户不知道该不该调用，Codex 也更容易误用。
- 把敏感配置放进插件：token、账号、私有 URL 应该走用户本地配置或凭据，不该跟插件一起分发。
- 一开始就做“大全包”：多个 skill、多个 hooks、多个 MCP 混在一起，出错时无法定位。
- 没有版本和变更记录：团队使用后，你需要能解释“这个版本改了什么”。
怎么验收
第一层验收：Codex 的 plugin directory 能看到你的 marketplace 和 plugin。
第二层验收：安装后能列出插件里的 skill，并且调用一次能完成一个最小真实任务。
第三层验收：换到一个干净仓库或新用户环境，按说明仍然能安装和使用。
第四层验收：关闭插件后，Codex 不再加载这组能力，说明它没有把副作用留在全局配置里。
第五层验收：团队用户读完说明，能判断这个插件是否需要外部服务、是否会改文件、是否会触发 hooks。