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

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

{
  "$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：

{
  "$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 扩展没有插件目录。