插件包结构与清单

新 portable 插件在包根目录放 plugin.json，用稳定的 kebab-case name 作为身份。最小示例：

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

目录布局

my-first-plugin/
├── plugin.json
├── mcp.json
├── skills/
│   └── hello/
│       └── SKILL.md
└── assets/

只有实际需要的组件才添加。portable 包从根目录 skills/ 发现 Skill，不要求 manifest 再写 skills 字段。mcp.json 用于分发 MCP server 配置，assets/ 放展示资源。

OpenAI 特定设置

在根 manifest 的 extensions.com.openai 下放展示元数据、注册 MCP 映射和 Hook 设置。已有 .codex-plugin/plugin.json 仍作为兼容后备；当 extensions.com.openai 是对象时，它整体替代兼容清单中的 OpenAI 设置，二者不合并。

当前 plugin-creator 生成的兼容布局仍有效，可能包含 .mcp.json、.app.json 等。不要只把 .mcp.json 改名成 mcp.json 就认为完成迁移：portable 格式还要求 Schema 和每个 server 的 transport type。

MCP 配置与已有连接

portable HTTP server 示例：

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

example.com 是待替换的服务地址。OpenAI 扩展的 apps 字段用于 .app.json 中已经注册的 MCP server 映射，不能拿它替代 portable mcp.json。

Hooks 与路径

打包文档将生命周期 Hooks 限定在手动安装的 Codex desktop 插件；含 Hooks 的包不具备公开目录提交资格。不要从本地运行成功推断可以公开发布或在云端 Work 执行。

默认发现 hooks/hooks.json；显式 hooks 字段替代默认文件发现，可指向路径、路径数组或内联对象。路径从插件根解析，以 ./ 开始且不能越出根。脚本可使用 PLUGIN_ROOT 和 PLUGIN_DATA，分别指向安装目录和可写数据目录。

本地安装测试还应确认 Skill 能被发现、MCP 连接可用，以及 Hooks 已单独审查信任。市场登记方式见市场与分发。