Codex 插件开发教程：从 Skill 到 Plugin 的完整实践

Codex 插件不是“多写一个提示词文件”这么简单。

它更像一个可安装的能力包：

1 2	把可复用工作流、技能、MCP 工具、应用集成和展示信息打包起来让自己或团队可以安装、启用、分享和迭代

如果只是给当前项目加几条长期规则，写 AGENTS.md 就够了。

如果只是给自己沉淀一个小工作流，写一个 Skill 也够了。

但如果你希望这个能力能被安装、分发、展示在 Codex 插件目录里，或者想把多个 Skill、MCP 配置、应用集成打包在一起，就应该考虑做成 Plugin。

本文基于 2026-06-16 的 Codex 官方 manual 和本地 @plugin-creator 规范整理，讲一个从零开发 Codex 插件的完整流程。

一、先分清 AGENTS.md、Skill 和 Plugin

这三个东西经常被混在一起。

但它们的定位不同。

1. AGENTS.md

AGENTS.md 适合写当前仓库的长期约定。

比如：

使用 pnpm
提交前运行 pnpm build
博客文章必须放在 source/_posts
不要提交 public/ 生成目录

它解决的是：

1	这个仓库里，Codex 应该一直遵守什么规则。

2. Skill

Skill 适合写一个可复用任务流程。

比如：

写 SEO 文章
审查安全漏洞
生成 PPT
操作 FFmpeg
处理电子表格

Skill 本质上是一个目录，里面有 SKILL.md，也可以带脚本、模板和参考资料。

最小结构：

1 2	my-skill/ SKILL.md

SKILL.md：

---
name: my-skill
description: 当用户需要执行某类任务时使用这个技能。
---

这里写 Codex 应该遵循的工作流。

Skill 解决的是：

1	让 Codex 在某类任务上按固定流程工作。

3. Plugin

Plugin 是可安装的分发单元。

它可以包含：

一个或多个 Skill
MCP server 配置
app integration 配置
assets 展示资源
插件名称、版本、描述、展示信息
marketplace 条目

Plugin 解决的是：

1	把一组能力打包起来，方便安装、共享和管理。

我的建议是：

1 2	先写 Skill 流程稳定后再打包成 Plugin

不要一上来就为了“看起来完整”写插件。

插件适合稳定能力，不适合频繁变动的草稿。

二、什么时候应该开发插件

适合做成插件的场景：

你写了多个相关 Skill，想统一安装
团队里多人都要用同一套工作流
需要绑定 MCP server，比如文档搜索、Figma、浏览器、内部系统
需要连接外部 app，比如 GitHub、Slack、Google Drive
希望在 Codex app 插件目录里展示和分享
希望通过 marketplace 管理安装来源

不适合做成插件的场景：

只是当前仓库的一条规范
只是一次性提示词
工作流还没稳定
没有复用价值
不需要安装和分发

一个简单判断：

1 2	如果只有你在一个项目里用，先写 AGENTS.md 或 Skill。如果多人、多项目、可安装分发，再做 Plugin。

三、插件的最小目录结构

一个最小 Codex 插件可以长这样：

my-first-plugin/
  .codex-plugin/
    plugin.json
  skills/
    hello/
      SKILL.md

其中最重要的是：

1	.codex-plugin/plugin.json

这是插件 manifest。

一个最小示例：

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

name 建议使用 kebab-case：

1
2
3

my-first-plugin
code-review-helper
internal-docs-assistant

不要用空格，不要随便改名。

Codex 会把插件 name 当作插件标识和组件命名空间。

四、添加第一个 Skill

创建 Skill 目录：

1	mkdir -p my-first-plugin/skills/hello

创建：

1	my-first-plugin/skills/hello/SKILL.md

内容：

---
name: hello
description: 当用户需要一个友好的问候和下一步协助时使用。
---

用简短、友好的语气问候用户。
如果用户没有给出具体任务，询问他们想完成什么。

这里最关键的是 description。

Codex 会根据 Skill 的描述判断什么时候加载它。

写 description 时不要太虚：

帮助用户提高效率

这种描述太泛。

更好的写法是：

1	当用户需要把一段接口说明转换成 OpenAPI 草稿时使用。

触发场景越清楚，Codex 越容易选对 Skill。

五、用 @plugin-creator 快速脚手架

手写插件当然可以。

但更推荐用 Codex 内置的 @plugin-creator。

它会生成合法的 .codex-plugin/plugin.json，也可以顺手创建 skills、scripts、assets、MCP、apps 和 marketplace 配置。

基础命令：

1	python3 scripts/create_basic_plugin.py my-plugin

如果要创建带 marketplace 的本地插件：

1	python3 scripts/create_basic_plugin.py my-plugin --with-marketplace

如果想一起生成常用目录：

python3 scripts/create_basic_plugin.py my-plugin \
  --with-skills \
  --with-scripts \
  --with-assets \
  --with-mcp \
  --with-apps \
  --with-marketplace

注意：上面的脚本路径是 @plugin-creator 技能目录里的相对路径。

真实使用时，要么让 Codex 调用 @plugin-creator，要么进入对应 skill 目录执行脚本。

六、plugin.json 常用字段

一个更完整的 manifest 可以这样写：

{
  "name": "internal-docs-helper",
  "version": "0.1.0",
  "description": "Search internal docs and turn findings into implementation notes.",
  "author": {
    "name": "Your Team",
    "email": "[email protected]",
    "url": "https://example.com"
  },
  "homepage": "https://example.com/internal-docs-helper",
  "repository": "https://github.com/example/internal-docs-helper",
  "license": "MIT",
  "keywords": ["docs", "mcp", "internal-tools"],
  "skills": "./skills/",
  "mcpServers": "./.mcp.json",
  "interface": {
    "displayName": "Internal Docs Helper",
    "shortDescription": "Search internal docs from Codex.",
    "longDescription": "A Codex plugin that bundles documentation search workflows and MCP configuration.",
    "developerName": "Your Team",
    "category": "Productivity",
    "capabilities": ["Read", "Search"],
    "websiteURL": "https://example.com",
    "privacyPolicyURL": "https://example.com/privacy",
    "termsOfServiceURL": "https://example.com/terms",
    "defaultPrompt": [
      "Search docs for the deployment flow.",
      "Summarize the API auth guide.",
      "Find examples for the billing webhook."
    ],
    "brandColor": "#3B82F6"
  }
}

几个注意点：

version 使用语义化版本，例如 0.1.0
skills 指向插件内的 Skill 目录
mcpServers 只有真的存在 .mcp.json 时再写
apps 只有真的存在 .app.json 时再写
websiteURL、privacyPolicyURL、termsOfServiceURL 如果写，应该是 https:// 绝对地址
defaultPrompt 最多放 3 条短提示
图标、logo、截图等资源要真实存在于插件目录里

不要为了“完整”乱填字段。

插件 manifest 的第一目标是：

1	真实、可验证、能被 Codex 正确加载。

七、Marketplace 是插件目录，不是插件本身

很多人会把 plugin 和 marketplace 搞混。

插件是能力包。

marketplace 是插件目录。

一个本地 marketplace 文件大概长这样：

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

常见位置：

1 2	个人 marketplace：~/.agents/plugins/marketplace.json 仓库 marketplace：<repo-root>/.agents/plugins/marketplace.json

source.path 是相对 marketplace root 的路径。

比如个人 marketplace 在：

1	~/.agents/plugins/marketplace.json

那么：

1	./plugins/my-plugin

通常会解析到类似：

1	~/plugins/my-plugin

这点很容易弄错。

不要以为它是相对 .agents/plugins/ 目录。

八、安装本地 marketplace

如果你使用默认个人 marketplace：

1	~/.agents/plugins/marketplace.json

通常不需要额外执行 codex plugin marketplace add。

如果是非默认位置，比如某个团队仓库里的 marketplace，可以用：

1	codex plugin marketplace add ./local-marketplace-root

也可以添加 GitHub 或 Git 地址：

1
2
3

codex plugin marketplace add owner/repo
codex plugin marketplace add owner/repo --ref main
codex plugin marketplace add https://github.com/example/plugins.git --sparse .agents/plugins

查看 marketplace：

1	codex plugin marketplace list

更新 marketplace：

1	codex plugin marketplace upgrade

删除 marketplace：

1	codex plugin marketplace remove marketplace-name

安装插件后，通常要开启新线程，让 Codex 重新加载可用插件、技能和工具。

九、给插件添加 MCP 能力

插件可以绑定 MCP server。

MCP 的作用是让 Codex 访问外部工具或上下文，比如：

文档搜索
浏览器控制
Figma
GitHub
Sentry
内部系统

插件里可以放：

my-plugin/
  .codex-plugin/
    plugin.json
  .mcp.json
  skills/

然后在 plugin.json 里声明：

{
  "name": "my-plugin",
  "version": "0.1.0",
  "description": "Plugin with MCP tools",
  "skills": "./skills/",
  "mcpServers": "./.mcp.json"
}

.mcp.json 里放 MCP server 配置。

实际配置要看你的 MCP server 是 stdio 还是 HTTP。

比如 stdio 形式常见是：

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"]
    }
  }
}

如果 MCP 需要 token，不要把密钥写死进插件。

应该通过环境变量、OAuth 或用户配置处理。

插件可以打包能力，但不应该硬编码用户秘密。

十、开发时一定要验证插件

开发插件时，最容易出问题的是：

plugin.json 字段不合法
version 不是合法 semver
name 和目录名不一致
skills 路径写错
mcpServers 指向了不存在的 .mcp.json
icon、logo、screenshots 文件不存在
marketplace 的 source.path 相对路径写错

如果使用 @plugin-creator，可以跑：

1	python3 scripts/validate_plugin.py <plugin-path>

这个验证很重要。

不要靠“看起来差不多”。

插件一旦进入 marketplace，错误路径和错误 manifest 会让安装体验很差。

十一、本地迭代时更新 cachebuster

本地开发插件时，经常会遇到：

1	我改了插件，但 Codex 好像没加载最新版本。

这时不要手改 marketplace。

更推荐使用 @plugin-creator 的更新脚本：

1	python3 scripts/update_plugin_cachebuster.py <plugin-path>

它会把版本改成类似：

1	0.1.0+codex.local-20260616-175820

然后读取 marketplace 名称：

1	python3 scripts/read_marketplace_name.py

再重新安装：

1	codex plugin add <plugin-name>@<marketplace-name>

如果插件不在默认个人 marketplace，就要先确认它来自哪个 marketplace。

这种情况下可以看：

1	codex plugin list

迭代完成后，开启新线程测试插件。

这是比较稳的边界。

十二、插件的常见开发流程

我建议按这个顺序做：

1. 先写一个单独 Skill
2. 用真实任务测试 description 是否容易触发
3. 把 Skill 放进 plugin 的 skills/ 目录
4. 编写 .codex-plugin/plugin.json
5. 需要外部工具时再加 .mcp.json 或 .app.json
6. 创建或更新 marketplace.json
7. 安装插件并开启新线程测试
8. 跑 validate_plugin.py
9. 修复路径、metadata、权限和认证问题
10. 分享给团队或放入 repo marketplace

不要一开始就追求大而全。

一个好插件，通常是从一个稳定 Skill 长出来的。

十三、一个完整示例

假设我们要做一个“代码审查助手”插件。

code-review-helper/
  .codex-plugin/
    plugin.json
  skills/
    code-review/
      SKILL.md

plugin.json：

{
  "name": "code-review-helper",
  "version": "0.1.0",
  "description": "Reusable code review workflow for Codex.",
  "skills": "./skills/",
  "interface": {
    "displayName": "Code Review Helper",
    "shortDescription": "Review code changes with a focused checklist.",
    "longDescription": "A Codex plugin that packages a repeatable code review workflow.",
    "developerName": "Personal",
    "category": "Developer Tools",
    "capabilities": ["Read", "Review"],
    "defaultPrompt": [
      "Review the current diff.",
      "Find bugs in this pull request.",
      "Check this change for test gaps."
    ],
    "brandColor": "#0F766E"
  }
}

skills/code-review/SKILL.md：

---
name: code-review
description: 当用户要求 review、审查 PR、检查 diff、找 bug 或评估测试缺口时使用。
---

以代码审查姿态工作。

优先输出问题，而不是总结。
按严重程度排序。
每个问题都要给出文件和行号。
重点关注：
- 行为回归
- 并发问题
- 安全问题
- 数据一致性
- 缺失测试

如果没有发现问题，明确说明没有发现阻塞问题，并指出剩余风险。

这个例子不复杂。

但它已经是一个可分发插件的雏形。

后续可以继续加：

安全审查 Skill
性能审查 Skill
GitHub MCP
漏洞扫描脚本
插件 logo 和截图

十四、常见坑

1. 直接把插件写成一堆提示词

插件不是提示词集合。

真正有用的是稳定工作流。

Skill 里应该写：

触发条件
操作步骤
输入输出
验证方式
边界和禁忌

不要只写“你是一个专业专家”。

2. description 写得太泛

错误示例：

1	帮助用户完成开发任务。

这会让 Codex 很难判断什么时候用。

更好：

1	当用户需要把接口文档转换成 OpenAPI 3.1 YAML 草稿时使用。

触发条件越具体，效果越稳定。

3. 把密钥写进插件

不要这样：

1
2
3

{
  "token": "sk-xxx"
}

密钥应该通过环境变量、OAuth、1Password 或用户本地配置处理。

插件可能会分享给别人。

把密钥写进去就是事故。

4. 忘记新线程测试

安装或更新插件后，最好开启新线程测试。

这样 Codex 能重新加载插件、Skill 和 MCP 工具。

如果你在旧线程里测试，有时会以为插件没生效。

其实是当前上下文还没拿到最新能力。

5. marketplace 路径写错

记住这句话：

1	source.path 相对 marketplace root，不是相对 .agents/plugins 目录。

路径错了，插件目录就找不到。

这是本地插件最常见的问题之一。

十五、我的建议

如果你要认真开发 Codex 插件，可以按这个原则走：

小工作流先做 Skill
稳定后再包装成 Plugin
本地先用 personal marketplace
团队共用再放 repo marketplace
需要外部能力再接 MCP 或 app
每次交付前都跑 validate_plugin.py

插件开发的关键不是把 manifest 写得多复杂。

而是把一个真实可复用的工作流打磨稳定，再用插件把它包装成可安装、可分享、可管理的能力。

这才是 Codex 插件真正有价值的地方。