Codex Plugin 教程：Marketplace、Plugin、Skill 是如何被识别和加载的？-拓冰建站

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 marketplaceaddowner/repo codex plugin marketplaceaddowner/repo--refmain codex plugin marketplaceaddhttps://github.com/example/plugins.git codex plugin marketplaceadd./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 marketplaceaddowner/repo

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

如果要更新远端 marketplace：

codex plugin marketplace upgrade

或者：

codex plugin marketplace upgrade<marketplace-name>

9. 安装 Plugin 后发生什么

执行：

codex pluginaddmy-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。