Codex Plugin 开发:从 Skill 到 MCP、Hook、App 的完整打包方式

如果你已经写过 Codex skill,很快就会遇到一个问题:这个 workflow 只在自己机器上好用,怎么稳定地给团队复用?

一开始,把 SKILL.md 放在本机 skill 目录就够了。但当你的能力开始包含更多东西时,单独一个 skill 就不够清晰了:

  • 你有一组固定的 MCP server 配置。
  • 你想把生命周期 hook 一起发给团队。
  • 你想挂一个 app integration。
  • 你希望用户能在 Codex 的 /plugins 里看到、安装、启用、更新。
  • 你不想让每个人手动拷贝零散文件。

这时就该把它做成 Codex plugin。

本文整理 Codex plugin 的核心模型、目录结构、开发流程和一个完整实战案例。重点不是罗列字段,而是把插件到底解决什么问题、每个文件负责什么、什么时候该用 skill / MCP / hook / app 讲清楚。

一句话结论

Codex plugin 不是一个新的执行引擎。它更像一个可安装的能力包。

它可以把这些东西打在一起:

  • skills/:可复用工作流和领域操作规约。
  • .mcp.json:MCP server 配置,让 Codex 多一组工具。
  • hooks.json 或 hooks/hooks.json:生命周期脚本,比如拦截危险命令、记录审计、停止时做检查。
  • .app.json:App integrations 的声明入口。
  • assets/:图标、截图、品牌展示素材。
  • .codex-plugin/plugin.json:插件 manifest,声明这个包叫什么、版本是多少、包含哪些组件。

再通过 marketplace.json 把插件放进一个可浏览、可安装、可更新的 catalog。

可以这样记:

skill 解决“怎么做”
MCP 解决“能调用什么工具”
hook 解决“什么时候插入规则或自动动作”
app 解决“连接哪个外部应用”
plugin 解决“怎么把这些能力打包、安装、分发”
marketplace 解决“Codex 从哪里发现这些插件”

什么时候只写 Skill,什么时候做 Plugin

官方文档里的判断很实用:如果还在一个 repo 或个人 workflow 里迭代,先写 local skill;当你要跨团队共享、打包 MCP config、打包 app integration、打包 lifecycle hooks,或者发布一个稳定能力包时,再做 plugin。

换成工程判断:

场景
推荐形态
只是自己常用的一段操作规约
local skill
一个 repo 内部的工程约定
repo-local skill
需要给多人安装
plugin
skill 还依赖 MCP server
plugin
skill 还依赖 hooks
plugin
需要在 /plugins 里可见、可安装、可更新
plugin + marketplace
需要发布一组插件
curated marketplace

不要过早做 plugin。plugin 的价值在于分发和组合,不在于让一个还没稳定的 prompt 看起来更正式。

插件目录结构

一个完整插件可以长这样:

repo-pr-guardian/
├── .codex-plugin/
│   └── plugin.json
├── skills/
│   └── pr-guardian/
│       └── SKILL.md
├── hooks/
│   ├── hooks.json
│   └── scripts/
│       └── block-dangerous-git.py
├── assets/
│   ├── icon.png
│   └── screenshot1.png
├── .mcp.json
└── .app.json

最小插件只需要:

my-first-plugin/
├── .codex-plugin/
│   └── plugin.json
└── skills/
    └── hello/
        └── SKILL.md

对应的 plugin.json:

{
  "name": "my-first-plugin",
  "version": "1.0.0",
  "description": "Reusable greeting workflow",
  "skills": "./skills/"
}

这个最小结构已经是一个插件。后面的 MCP、hook、app 都是增强能力,不是必须项。

plugin.json 负责什么

.codex-plugin/plugin.json 是插件 manifest。它回答四个问题:

  • 这个插件是谁:name、version、description、author。
  • 这个插件包含什么:skills、hooks、mcpServers、apps。
  • 这个插件如何展示:interface.displayName、shortDescription、brandColor、logo、screenshots。
  • 用户怎么信任和理解它:homepage、repository、license、privacyPolicyURL、termsOfServiceURL。

一个较完整的形态:

{
  "name": "repo-pr-guardian",
"version": "1.0.0",
"description": "Review pull requests with repo policy, safe git hooks, and optional MCP tools.",
"author": {
    "name": "Your Team",
    "email": "team@example.com",
    "url": "example-dot-com"
  },
"homepage": "example-dot-com/repo-pr-guardian",
"repository": "github-dot-com/example/repo-pr-guardian",
"license": "MIT",
"keywords": ["codex", "review", "pull-request"],
"skills": "./skills/",
"hooks": "./hooks/hooks.json",
"mcpServers": "./.mcp.json",
"apps": "./.app.json",
"interface": {
    "displayName": "Repo PR Guardian",
    "shortDescription": "Review PRs with repo policy and safety checks.",
    "longDescription": "A Codex plugin that packages PR review workflow guidance, optional MCP tools, and lifecycle hooks for safer repository work.",
    "developerName": "Your Team",
    "category": "Productivity",
    "capabilities": ["Review", "MCP", "Hooks"],
    "defaultPrompt": [
      "Review this PR against repo policy.",
      "Check risky git commands before running.",
      "Summarize review findings for maintainers."
    ],
    "brandColor": "#2563EB",
    "composerIcon": "./assets/icon.png",
    "logo": "./assets/icon.png",
    "screenshots": ["./assets/screenshot1.png"]
  }
}

几个细节要记住:

  • name 用稳定的 kebab-case,Codex 会把它当插件标识和组件 namespace。
  • 路径建议用 ./ 开头,并保持在 plugin root 内。
  • skills、hooks、mcpServers、apps 是组件入口,不是展示字段。
  • interface 是给插件目录和安装页面看的,不参与 workflow 本身。

skills/:插件的操作大脑

Skill 是插件里最重要也最容易复用的部分。

一个 SKILL.md 通常长这样:

---
name: pr-guardian
description: Review pull requests against repository policy, test expectations, and risk boundaries.
---


Use this skill when the user asks for PR review, merge readiness, or risk assessment.

Start by reading the diff and relevant tests. Report findings first, ordered by severity.
Prefer concrete file and line references. Do not rewrite unrelated code.

If the PR touches authentication, secrets, deployment, or data deletion paths,
include an explicit risk section.

Skill 的价值不是“多一段 prompt”,而是把一个稳定流程固定下来:

  • 什么时候使用。
  • 先读什么。
  • 输出格式是什么。
  • 不能做什么。
  • 哪些风险必须显式检查。

如果你的 plugin 只能保留一个部分,优先保留 skill。

.mcp.json:把工具能力打进插件

MCP server 让 Codex 能调用外部工具。.mcp.json 是插件内 MCP 配置的入口。

示例:

{
  "mcpServers": {
    "repo-policy": {
      "command": "node",
      "args": ["./server/index.js"],
      "env": {
        "REPO_POLICY_MODE": "strict"
      }
    }
  }
}

这类配置适合:

  • 把内部检索工具接给 Codex。
  • 把工单、CI、仓库、文档系统接给 Codex。
  • 给 skill 提供一组稳定工具,而不是让用户自己手动配 MCP。

但 MCP 有一个现实边界:它经常涉及认证、网络、二进制依赖或本地服务。插件可以打包配置,不等于用户安装后立刻能用。你需要在 README 或 skill 里写清楚:

  • 需要哪些环境变量。
  • 需要先启动哪个本地服务。
  • 认证是在安装时还是首次使用时完成。
  • 失败时如何自检。

hooks:把生命周期规则打进插件

Hooks 是插入 Codex Agent loop 的脚本。它能做很多治理类工作:

  • 在 PreToolUse 拦截危险命令。
  • 在 PostToolUse 检查命令输出。
  • 在 UserPromptSubmit 做 prompt 审计。
  • 在 Stop 做收尾检查或生成摘要。
  • 在 SessionStart 加载项目上下文。

插件可以自带 hooks,但这里有两个关键限制:

  • 当前 release 里,plugin hooks 默认关闭,需要 [features].plugin_hooks = true。
  • 插件 hooks 是 non-managed hooks,需要用户 review / trust 后才会运行。

插件内默认 hook 路径是:

hooks/hooks.json

你也可以在 plugin.json 里覆盖:

{
  "name": "repo-pr-guardian",
  "hooks": "./hooks/hooks.json"
}

一个 hooks/hooks.json 示例:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python3 \"$PLUGIN_ROOT/hooks/scripts/block-dangerous-git.py\"",
            "timeout": 1…
— 以上为试看内容(约 40%),开通会员后阅读全文 —