---
title: "新插件用根目录 plugin.json，不要只把 .mcp.json 改名"
summary: "$plugin-creator 仍脚手架 .codex-plugin。可移植包是根目录 plugin.json 加带 type 的 mcp.json。extensions.com.openai 会整份替换 overlay，两套不合并。"
category: skills
level: intermediate
surfaces: [cli, app]
tags: ["plugins", "plugin.json", "mcp.json"]
canonical: /tips/plugin-portable-json/
---

# 新插件用根目录 plugin.json，不要只把 .mcp.json 改名

$plugin-creator 仍脚手架 .codex-plugin。可移植包是根目录 plugin.json 加带 type 的 mcp.json。extensions.com.openai 会整份替换 overlay，两套不合并。

现行可移植包把身份放在插件根的 `plugin.json`，不要把 MCP、钩子、技能路径塞进这份清单的顶层。最小可用：

```json
{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "my-first-plugin",
  "version": "1.0.0",
  "description": "Reusable greeting workflow"
}
```

`name` 用 kebab-case，宿主拿它当插件标识和组件命名空间。技能固定从根目录 `skills/` 发现，清单里不必写 `skills` 字段。

带 MCP 时，和 `plugin.json` 放在同一层，再写 `mcp.json`，并声明 Agent Plugins schema 和每台服务器的 transport `type`：

```json
{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
  "mcpServers": {
    "docs": {
      "type": "streamable-http",
      "url": "https://example.com/mcp"
    }
  }
}
```

`$plugin-creator` / `@plugin-creator` 仍脚手架兼容布局：`.codex-plugin/plugin.json`、`.mcp.json`、`.app.json`。这套还支持，没有作废。不要只把 `.mcp.json` 改名为 `mcp.json`：可移植格式还要给每台服务器写 `type`（例如 `streamable-http`）。兼容布局里，根目录的 `.mcp.json` 只有清单把 `mcpServers` 指到 `./.mcp.json` 才会被导入，否则会被忽略。

OpenAI 专用展示、已注册 MCP 映射和钩子路径写在根清单的 `extensions.com.openai`。这个对象一旦出现，会整份替换 `.codex-plugin/plugin.json` overlay，两套不合并。没有这个对象时，才回退读兼容 overlay。可移植包里，overlay 或 extension 里的 `skills` / `mcpServers` 改不了、关不掉、也加不了根目录已经发现的技能和 MCP。

加 Codex overlay 时，只有 `plugin.json` 放进 `.codex-plugin/`。`skills/`、`hooks/`、`assets/`、`.mcp.json`、`.app.json` 留在插件根。路径一律相对插件根并以 `./` 开头。`app.json`（没有前导点）不是合法文件名。

公共目录投稿的 ZIP 检查更严：根上还要有 `.codex-plugin/plugin.json`、`.agent-plugin/plugin.json` 或 `.claude-plugin/plugin.json` 之一，只有根目录 `plugin.json` 会报 `plugin_manifest_missing`。本地 marketplace 测试用可移植根清单即可；要上公共目录，保留一份 overlay。密钥不要写进 `mcp.json`。

装进 marketplace 后，CLI 0.154 起先看当前会话的 `/plugins`。IDE 扩展没有插件目录。

## 来源

- [OpenAI · Package your plugin](https://learn.chatgpt.com/plugins/build/plugins)
- [OpenAI · Plugin submission errors](https://learn.chatgpt.com/plugins/deploy/submission-errors)