构建自己的插件

Codex plugin 是分发单元，用来把 skills、MCP 配置、app integration 或其他能力打包给别人安装。它不是“把一段 prompt 包起来”。

新手最常见的错误，是本来只需要本地 skill，却一上来做 plugin、marketplace 和发布目录。

自己用先写 skill；团队复用再考虑 plugin；需要 Codex 发现和安装一组 plugin，才需要 marketplace。

Build plugins

查看官方 plugin manifest、目录结构和 marketplace 说明。

Plugins

理解 plugin 的安装、管理和使用方式。

Skills

如果只是复用流程，先做 skill。

三个概念

flowchart LR
    Skill["Skill<br/>工作方法"]
    Plugin["Plugin<br/>分发包"]
    Marketplace["Marketplace<br/>发现和安装目录"]

    Skill --> Plugin
    Plugin --> Marketplace

Skill 解决：

Codex 在某类任务上应该怎么做。
触发条件、步骤、输出和验证。

Plugin 解决：

把一组能力打包给别人安装。
可以包含 skills、MCP、hooks、app mappings 等。

Marketplace 解决：

Codex 从哪里发现 plugin。
团队或个人如何维护可安装清单。

什么时候该做 plugin

适合：

能力已经被反复使用。
有清楚名称、说明、输入边界和使用场景。
安装后别人能直接在 Codex 里发现。
需要一起分发 skill、MCP 或其他配置。
愿意维护版本、兼容性和变更记录。

不适合：

只是一次性 prompt。
skill 还没跑稳。
只服务当前仓库的临时任务。
还没想清楚权限和外部依赖。
只是为了目录看起来更工程化。

第一版应该尽量小

第一版 plugin 建议只包含一个稳定 skill。

最小结构：

my-plugin/
  .codex-plugin/
    plugin.json
  skills/
    my-skill/
      SKILL.md

说明必须写清：

插件解决什么任务。
什么时候应该调用。
什么时候不应该调用。
是否需要 token、MCP、外部网络或账号。
安装后如何确认生效。

不要第一版就塞多个 skills、多个 MCP servers 和复杂 hooks。包越大，排错越难。

最小 manifest 放在 .codex-plugin/plugin.json：

{
  "name": "my-first-plugin",
  "version": "1.0.0",
  "description": "Reusable workflow for one stable Codex task.",
  "skills": "./skills/"
}

name 使用稳定 kebab-case。Codex 会把它当成 plugin identifier 和 component namespace。

Marketplace 怎么放

Marketplace 是 JSON catalog，不是 plugin 本身。常用位置：

范围	文件
Repo marketplace	`$REPO_ROOT/.agents/plugins/marketplace.json`
Personal marketplace	`~/.agents/plugins/marketplace.json`

本地 repo marketplace 的最小条目：

{
  "name": "local-repo",
  "interface": {
    "displayName": "Local Repo Plugins"
  },
  "plugins": [
    {
      "name": "my-plugin",
      "source": {
        "source": "local",
        "path": "./plugins/my-plugin"
      },
      "policy": {
        "installation": "AVAILABLE",
        "authentication": "ON_INSTALL"
      },
      "category": "Productivity"
    }
  ]
}

source.path 必须相对 marketplace root，并以 ./ 开头。修改 marketplace 或 plugin 后要重启 Codex；local plugin 会被安装到 Codex cache 中，Codex 读取的是安装后的副本，而不是你刚编辑的源目录。

也可以用 CLI 添加 marketplace：

codex plugin marketplace add ./local-marketplace-root
codex plugin marketplace upgrade
codex plugin marketplace remove marketplace-name

发布前检查

发布前确认：

plugin name 稳定。
version 清楚。
description 能触发正确任务。
不包含密钥、token、私有 URL。
外部依赖写明。
禁止事项写明。
关闭 plugin 后不会留下全局副作用。

如果插件会调用外部系统，还要说明权限、数据流和审计方式。

安装后怎么验证

本地验证不要只看文件存在，要在 Codex 里确认：

/plugins 能看到对应 marketplace。
plugin details 能展示名称、说明和 category。
安装后 bundled skills 能被调用。
需要认证的 app 或 MCP 会在 install 或首次使用时提示。
禁用 plugin 后，相关能力不再触发。

如果插件包含外部 app、MCP server 或 hooks，还要单独确认权限提示和失败路径。安装 plugin 只是让 workflow 可用，Codex 现有 approval settings 仍然生效，外部服务仍受自己的认证和隐私策略约束。

常见坑

marketplace 路径写错。
修改后忘记重启或刷新 Codex。
description 太泛，导致误触发。
把敏感配置打进插件。
缺少版本和变更记录。
安装说明只适用于作者机器。
skill 和 plugin 职责混在一起。

Plugin 的目标是分发稳定能力，而不是提前包装不稳定流程。