Codex Plugin 教程：Marketplace、Plugin、Skill 是如何被识别和加载的？

这篇文章只讲一件事：

Codex 如何从 marketplace.json 一步步找到 plugin，再找到 skill。

先看流程图。

最短链路：

marketplace root
  -> .agents/plugins/marketplace.json
  -> plugins[].source.path
  -> .codex-plugin/plugin.json
  -> skills/
  -> SKILL.md

---

1. 三个核心文件

文件	作用
.agents/plugins/marketplace.json	插件市场清单：列出有哪些 plugin，以及 plugin 在哪里
.codex-plugin/plugin.json	单个 plugin 的描述文件：名字、版本、能力入口
SKILL.md	单个 skill 的说明书：触发条件、执行步骤、引用脚本

可以这样记：

marketplace.json 管一组 plugin。
plugin.json 管一个 plugin。
SKILL.md 管一个 skill。

---

2. Codex 如何识别 Marketplace

Codex 识别 marketplace 有两种方式。

第一种：放在约定位置。

个人级:
~/.agents/plugins/marketplace.json

项目级:
$REPO_ROOT/.agents/plugins/marketplace.json

第二种：通过命令注册。

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

查看 Codex 当前识别到哪些 marketplace：

codex plugin marketplace list

---

3. Marketplace Root 是什么

marketplace root 是 Codex 解析路径的根目录。

Codex 会在这个 root 下找：

<marketplace-root>/.agents/plugins/marketplace.json

marketplace.json 里的 source.path 也是相对于这个 root。

例如：

marketplace root:
~/my-codex-marketplace

marketplace file:
~/my-codex-marketplace/.agents/plugins/marketplace.json

source.path:
./plugins/my-plugin

plugin path:
~/my-codex-marketplace/plugins/my-plugin

注意：

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

---

4. marketplace.json 如何指向 Plugin

一个最小的 marketplace.json：

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

关键字段是：

"plugins": [
  {
    "name": "my-plugin",
    "source": {
      "path": "./plugins/my-plugin"
    }
  }
]

Codex 会用：

marketplace root + source.path

找到 plugin 目录。

一个 marketplace.json 可以列多个 plugin，不需要每个 plugin 都单独建一个 marketplace。

---

5. Plugin 如何暴露 Skill

Plugin 目录里需要有：

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

最小的 plugin.json：

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "A reusable Codex workflow plugin.",
  "skills": "./skills/"
}

关键字段是：

"skills": "./skills/"

它告诉 Codex：

这个 plugin 里面有 skills，请扫描 ./skills/。

这里的 ./skills/ 是相对于 plugin 目录，不是相对于 marketplace。

---

6. Skill 如何被识别

一个最小的 skill：

skills/
  my-skill/
    SKILL.md

SKILL.md 至少包含：

---
name: my-skill
description: Use when the user wants this specific workflow.
---

Follow these steps:

1. Understand the user request.
2. Run the needed checks.
3. Make the smallest safe change.

Codex 会先读取：

name
description
file path

用于判断什么时候触发这个 skill。

触发方式有两种：

显式触发:
$my-skill

隐式触发:
用户请求匹配 description

只有真正触发时，Codex 才会读取完整 SKILL.md。

---

7. Skill 不一定来自 Plugin

Skill 可以单独存在，不一定要打包成 plugin。

常见单独 skill 位置：

用户级:
~/.agents/skills/<skill-name>/SKILL.md

项目级:
$REPO_ROOT/.agents/skills/<skill-name>/SKILL.md

什么时候只用 skill：

自己用
项目内用
还在快速迭代流程

什么时候做成 plugin：

想让别人安装
想团队共享
想进入插件列表
想同时打包多个 skills / MCP / App / assets

---

8. 本地和远端 Marketplace 的区别

本地 personal marketplace：

~/.agents/plugins/marketplace.json

项目 marketplace：

$REPO_ROOT/.agents/plugins/marketplace.json

远端 marketplace：

codex plugin marketplace add owner/repo

远端 marketplace 添加后，Codex 会在本地维护快照。通常不建议手动改这些缓存目录。

如果要更新远端 marketplace：

codex plugin marketplace upgrade

或者：

codex plugin marketplace upgrade <marketplace-name>

---

9. 安装 Plugin 后发生什么

执行：

codex plugin add my-plugin@my-marketplace

意思是：

从 my-marketplace 这个 marketplace 里安装 my-plugin。

大致流程：

1. 找到 marketplace
2. 读取 marketplace.json
3. 找到 name = my-plugin 的 entry
4. 根据 source.path 找到 plugin 目录
5. 读取 plugin.json
6. 安装并启用 plugin
7. 让 plugin 暴露的 skills / MCP / App 可用

查看安装结果：

codex plugin list

---

10. 排查顺序

如果 Codex 没识别到 plugin 或 skill，按这个顺序查。

查看 marketplace：

codex plugin marketplace list

查看 plugin：

codex plugin list

检查 marketplace 文件：

<marketplace-root>/.agents/plugins/marketplace.json

检查 plugin 文件：

<plugin-root>/.codex-plugin/plugin.json

检查 skill 文件：

<plugin-root>/skills/<skill-name>/SKILL.md

如果路径都对，但当前线程仍然识别不到：

新开一个 Codex 线程，或重启 Codex。

---

11. 最短总结

Codex 先找到 marketplace root。
再读取 .agents/plugins/marketplace.json。
marketplace.json 的 plugins[] 指向 plugin 目录。
plugin 目录下的 .codex-plugin/plugin.json 声明能力入口。
如果 plugin.json 写了 "skills": "./skills/"，Codex 会扫描 skills。
每个 skill 通过 SKILL.md 的 name 和 description 被识别。
触发 skill 后，Codex 再读取完整 SKILL.md。