Codex Plugin 教程Marketplace、Plugin、Skill 是如何被识别和加载的这篇文章只讲一件事Codex 如何从 marketplace.json 一步步找到 plugin再找到 skill。先看流程图。是否Codex 启动 / 刷新插件找到 marketplace root读取 .agents/plugins/marketplace.json读取 plugins[]根据 source.path 找到 plugin 目录读取 .codex-plugin/plugin.jsonplugin 是否声明 skills?扫描 plugin 内的 skills/不暴露 skill可能只提供 MCP / App读取 /SKILL.md加载 skill 的 name / description用户通过 $skill-name 调用或 Codex 自动匹配触发触发后读取完整 SKILL.md最短链路marketplace root - .agents/plugins/marketplace.json - plugins[].source.path - .codex-plugin/plugin.json - skills/ - SKILL.md1. 三个核心文件文件作用.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 如何识别 MarketplaceCodex 识别 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 当前识别到哪些 marketplacecodex plugin marketplace list3. Marketplace Root 是什么marketplace root是 Codex 解析路径的根目录。Codex 会在这个 root 下找marketplace-root/.agents/plugins/marketplace.jsonmarketplace.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 如何暴露 SkillPlugin 目录里需要有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 如何被识别一个最小的 skillskills/ my-skill/ SKILL.mdSKILL.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 不一定来自 PluginSkill 可以单独存在不一定要打包成 plugin。常见单独 skill 位置用户级: ~/.agents/skills/skill-name/SKILL.md 项目级: $REPO_ROOT/.agents/skills/skill-name/SKILL.md什么时候只用 skill自己用 项目内用 还在快速迭代流程什么时候做成 plugin想让别人安装 想团队共享 想进入插件列表 想同时打包多个 skills / MCP / App / assets8. 本地和远端 Marketplace 的区别本地 personal marketplace~/.agents/plugins/marketplace.json项目 marketplace$REPO_ROOT/.agents/plugins/marketplace.json远端 marketplacecodex plugin marketplaceaddowner/repo远端 marketplace 添加后Codex 会在本地维护快照。通常不建议手动改这些缓存目录。如果要更新远端 marketplacecodex plugin marketplace upgrade或者codex plugin marketplace upgrademarketplace-name9. 安装 Plugin 后发生什么执行codex pluginaddmy-pluginmy-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 list10. 排查顺序如果 Codex 没识别到 plugin 或 skill按这个顺序查。查看 marketplacecodex plugin marketplace list查看 plugincodex 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。
Codex Plugin 教程：Marketplace、Plugin、Skill 是如何被识别和加载的？
Codex Plugin 教程Marketplace、Plugin、Skill 是如何被识别和加载的这篇文章只讲一件事Codex 如何从 marketplace.json 一步步找到 plugin再找到 skill。先看流程图。是否Codex 启动 / 刷新插件找到 marketplace root读取 .agents/plugins/marketplace.json读取 plugins[]根据 source.path 找到 plugin 目录读取 .codex-plugin/plugin.jsonplugin 是否声明 skills?扫描 plugin 内的 skills/不暴露 skill可能只提供 MCP / App读取 /SKILL.md加载 skill 的 name / description用户通过 $skill-name 调用或 Codex 自动匹配触发触发后读取完整 SKILL.md最短链路marketplace root - .agents/plugins/marketplace.json - plugins[].source.path - .codex-plugin/plugin.json - skills/ - SKILL.md1. 三个核心文件文件作用.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 如何识别 MarketplaceCodex 识别 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 当前识别到哪些 marketplacecodex plugin marketplace list3. Marketplace Root 是什么marketplace root是 Codex 解析路径的根目录。Codex 会在这个 root 下找marketplace-root/.agents/plugins/marketplace.jsonmarketplace.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 如何暴露 SkillPlugin 目录里需要有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 如何被识别一个最小的 skillskills/ my-skill/ SKILL.mdSKILL.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 不一定来自 PluginSkill 可以单独存在不一定要打包成 plugin。常见单独 skill 位置用户级: ~/.agents/skills/skill-name/SKILL.md 项目级: $REPO_ROOT/.agents/skills/skill-name/SKILL.md什么时候只用 skill自己用 项目内用 还在快速迭代流程什么时候做成 plugin想让别人安装 想团队共享 想进入插件列表 想同时打包多个 skills / MCP / App / assets8. 本地和远端 Marketplace 的区别本地 personal marketplace~/.agents/plugins/marketplace.json项目 marketplace$REPO_ROOT/.agents/plugins/marketplace.json远端 marketplacecodex plugin marketplaceaddowner/repo远端 marketplace 添加后Codex 会在本地维护快照。通常不建议手动改这些缓存目录。如果要更新远端 marketplacecodex plugin marketplace upgrade或者codex plugin marketplace upgrademarketplace-name9. 安装 Plugin 后发生什么执行codex pluginaddmy-pluginmy-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 list10. 排查顺序如果 Codex 没识别到 plugin 或 skill按这个顺序查。查看 marketplacecodex plugin marketplace list查看 plugincodex 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。
