Agent Plugin 完全指南

一、Plugin 的核心概念与适用场景

什么是 Plugin

在以 Codex、Claude Code 为代表的 Agent 客户端中，Plugin 是一种可安装、可分发、可版本化的 Agent 能力包。它将 Skill、MCP/App、Hook、Agent、脚本和展示资产封装为具有独立身份和边界的交付单元。

Plugin 不提供新的推理机制或工具协议。模型负责推理与生成，Skill 定义任务方法、工作流，MCP/App 提供工具与数据，Hook 在生命周期节点执行确定性逻辑；Plugin 负责这些组件的封装、安装与分发。

为什么需要 Plugin？

以代码评审 Skill 为例。随着能力范围扩展，可能还需要：

• 一个读取内部代码平台的 MCP Server；
• 一个提交前自动检查的 Hook；
• 两个分别检查安全和测试的子 Agent；
• 几段脚本、规则模板、图标和使用说明；
• 面向团队的安装、升级迭代与停用机制。

缺少 Plugin 时，这些能力需要依靠手工复制文件、修改配置和启动服务完成安装。Plugin 将分散的配置封装为可安装、可升级迭代的交付单元。

对于仅包含一份持续迭代的 SKILL.md，且暂无组合、安装和版本化需求的能力，本地 Skill 通常更合适。OpenAI 的 Build plugins 和 Anthropic 的 Create plugins 均建议先进行本地迭代，再完成产品化封装。

二、Plugin 包与最小结构

manifest 是 Host 识别 Plugin 身份和组件路径的入口；Skill 则是最小的任务能力单元。因此，最小 Plugin 可以只包含一个 manifest 和一个 Skill。

以下四句话概括它们的分工：

• Host 是 Codex、Claude Code 这类客户端及其运行时，负责发现、装载和管理模型、工具与 Plugin；
• Agent 是 Host 内由模型驱动的执行主体，负责理解任务并选择、调用已装载的能力；
• Plugin 是被 Host 装载的能力包；
• Manifest 是 Plugin 给 Host 看的说明书。

以下以 repo-review 作为示例：安装后，Agent 可按照团队规则评审代码改动。

Codex Plugin 的最小结构

repo-review/                    # Plugin 根目录
├── .codex-plugin/              # Codex Mate 目录
│   └── plugin.json             # Plugin Manifest
├── skills/                     # Skill 组件目录
│   └── review/
│       └── SKILL.md
├── .mcp.json                   # MCP 配置
└── hooks/
    └── hooks.json              # Hook 配置

.codex-plugin/plugin.json：

{
  "name": "repo-review",
  "version": "1.0.0",
  "description": "Review repository changes with team rules.",
  "skills": "./skills/"
}

skills/review/SKILL.md：

---
name: review
description: Review code changes against repository rules and report actionable findings.
---
 
Read the repository guidance and current diff.
Report only actionable findings with file and line evidence.

其中 .codex-plugin/plugin.json 和一个 Skill 构成最小 Codex Plugin；.mcp.json 与 hooks/hooks.json 按需加入。.codex-plugin/plugin.json 是入口，skills 指向包内能力。如需被 Plugin 浏览器发现，还需登记到个人或仓库级 Marketplace，详见第五章“安装、分发与版本管理”。OpenAI 官方最小示例 采用相同结构。

Claude Code Plugin 的最小结构

repo-review/                    # Plugin 根目录
├── .claude-plugin/             # Claude Code Mate 目录
│   └── plugin.json             # Plugin Manifest
└── skills/                     # Skill 组件目录
    └── review/
        └── SKILL.md

.claude-plugin/plugin.json：

{
  "name": "repo-review",
  "version": "1.0.0",
  "description": "Review repository changes with team rules."
}

开发时可以直接加载目录：

claude --plugin-dir ./repo-review

Plugin 加载完成后（必要时执行 /reload-plugins 或新建会话），输入 /repo-review:review 显式调用其中的 review Skill。Claude Code 使用 Plugin 名作为命名空间，以避免多个名为 review 的 Plugin 发生冲突。

Claude Code 也支持按默认目录结构自动发现组件。因此，manifest 在部分布局中可省略；使用自定义目录或正式分发时，仍应保留 Manifest。详见 Plugins reference。

Codex 与 Claude Code 的差异

两者采用相似的能力封装抽象，但属于不同产品的加载协议。

图中中间层可以共享：任务定义、Skill、references、纯脚本和测试。manifest 与 Marketplace 可以在共同字段范围内复用 Claude 兼容格式；Hook 配置、安装命令和端侧运行组件仍需分别验证或装配。

**Manifest 入口

Codex 的原生入口是 .codex-plugin/plugin.json；Claude Code 的入口是 .claude-plugin/plugin.json。
`
关键差异

兼容性

codex-cli 0.144.1起也会兼容读取.claude-plugin/plugin.json。Codex 在两个 manifest 同时存在时优先读取 .codex-plugin/plugin.json`，不会与 Claude manifest 合并。

因此只包含 Skill 且使用两端共同字段的 Plugin，可以只维护一份 .claude-plugin/plugin.json，同时供 Claude Code 原生读取和 Codex 兼容读取。

repo-review/
├── .claude-plugin/plugin.json  # Claude 原生读取，Codex 兼容读取
└── skills/

双端组织

如果需要 Codex App、Codex 原生元数据、Claude Agent/LSP/依赖或不同的 Hook 配置，则采用”共享能力、分端装配”的目录结构：

repo-review/
├── .codex-plugin/plugin.json
├── .claude-plugin/plugin.json
├── skills/                    # 单一事实源
├── references/
├── scripts/                   # 尽量写纯逻辑
├── hooks/
│   ├── codex/
│   └── claude/
├── .app.json                  # Codex / ChatGPT
├── .mcp.json
└── assets/

需要 Codex App、端侧 Hook、Claude Agent/LSP/依赖等差异化能力时，仍应维护两套 manifest 与端侧配置，不要把两端字段的并集无边界地塞进单一 manifest。

三、组件模型与组合方式

Plugin 的组件模型

Plugin 作为组件容器，不要求包含全部组件。组件数量增加会同步提高安装成本、权限面、上下文成本和维护成本。

依见 Extend Claude with skills、Commands reference、Agent SDK custom slash commands 和 Plugins reference。

不是每个 Host 都支持表里的全部组件。
Codex 当前公开的核心 Plugin 结构集中在 Skills、App/Connector、MCP、Hooks 和 assets；Claude Code 还公开支持 Agents、LSP、bin、output styles，以及处于实验演进中的 themes、monitors 等组件。
表中单列 Command 只为说明旧目录和迁移边界；Claude Code 的 plugin details 会把 skills/ 与 commands/ 统一计入 Skills 组件组。
OpenAI 的用户侧 Plugin 概览还列出 Browser Extension 和 Scheduled Task Template。这些属于依 Surface 提供的平台扩展，当前公开 Build 页面没有给出可自行编写的通用 manifest 字段，因此未列为可自定义的通用目录。

Skill：任务方法与执行边界

Skill 用于定义 Agent 处理一类任务时采用的流程与边界，适合保存：

• 触发条件和不触发条件；
• 分步流程、决策规则和验收标准；
• 参考资料、模板和少量辅助脚本；
• 对工具使用顺序和失败处理的约束。
  Skill 可以独立存在，也可以被 Plugin 打包。Skill 是能力编写格式，Plugin 是分发单元。 Plugin 不改变 Skill 的指令质量，其作用限于能力的封装、交付与分发。
  Skill 的目录结构、触发机制、渐进式加载与编写方法，详见 Agent Skills 完全指南。

MCP Server：工具与实时上下文

MCP Server 用于向 Agent 暴露可调用的真实能力。它可以连接 API、数据库、本地进程或 SaaS，负责认证、结构化输入输出和执行动作。
例如，repo-review 可以通过 Skill 定义评审流程，再通过 MCP 工具读取代码评审平台上的变更、评论和构建状态。Skill 定义评审方法，MCP 提供评审所需的数据和操作。更完整的协议分层与调用链说明详见 Agent MCP 完全指南。

App 与 Connector：MCP 集成的产品形态

在当前 OpenAI 产品语境里，App 通常由 MCP Server 提供工具，可选使用 Apps SDK 增加 ChatGPT UI；Connector 是连接 GitHub、Slack、Google Drive 等外部服务的产品能力。Plugin 可以只包含 Skill，也可以包含 MCP-backed App，或者把两者组合起来。

.app.json 用于将 Plugin 映射到 App/Connector；.mcp.json 用于配置并启动 MCP Server。二者都可以提供工具，但安装、授权、部署与生命周期不同。

Hook：生命周期事件处理

Hook 在 SessionStart、PreToolUse、PostToolUse、Stop 等生命周期节点自动运行。它适合：

• 工具执行前阻止明显危险操作；
• 文件写入后自动格式化或记录审计；
• 回答结束前检查测试、证据或合规项；
• 会话开始时准备环境或注入小段上下文。
  Hook 不应承载开放式、长时运行的 Agent 工作流。高频节点应保持快速、可预测、可超时和可诊断。涉及命令执行的 Hook 需要按照可执行代码进行审查。
  command Hook 的典型执行流程如下：

Host 触发事件
→ 把事件上下文作为 JSON 交给 handler
→ handler 检查并执行动作
→ 用退出码和可选的 stdout JSON 返回结果
→ Host 按该事件的协议继续、阻断、补充上下文或改写决策

不同 Host 可以共享上述流程抽象，但输出字段不可直接复用。http、mcp_tool、prompt、agent 等 handler 各有相应的传输和返回方式；Codex 与 Claude Code、PreToolUse 与 Stop 的 schema 也可能不同，必须按当前 Host、handler 类型和事件文档实现。

Agent、Skill 与旧 Command：子任务分工与兼容入口

Agent 适合处理独立子问题，例如安全审查、测试覆盖检查和历史上下文核验。Agent 定义应明确审查维度、工具边界与输出契约；单一角色描述不足以构成可执行约束。
Claude Code 当前已把 custom commands 合并进 Skills。项目或用户目录中的 .claude/commands/*.md、Plugin 根目录中的 commands/*.md 仍会按扁平 Skill 加载；同名 Skill 与 Command 并存时，Skill 优先。二者默认都可被用户或模型调用，设置 disable-model-invocation: true 后才限制为仅手动调用。新 Plugin 应优先使用 skills/<name>/SKILL.md，旧 commands/ 只保留迁移或兼容用途，避免维护两份相同流程。Codex 当前公开的 Plugin 结构没有对应的 commands/ 组件。

Plugin 组件的选型

组件选型应以能力缺口为依据，而非预设采用 Plugin。

选型依据如下：

1. 方法、流程与验收标准：使用 Skill；
2. 实时数据或外部动作：使用 MCP Server 或 App/Connector；
3. 生命周期中的确定性约束：使用 Hook；
4. 组合安装、版本化或团队分发：封装为 Plugin。

典型组件组合

这些模式可以组合，但所有组件应围绕单一主任务，以限制权限面与维护成本。

哪些情况不适合使用 Plugin？

• 仅对当前对话有效的约束：使用 Prompt；
• 仅对当前仓库长期有效的约束：使用 AGENTS.md、CLAUDE.md、项目配置或本地 Skill；
• 稳定且确定的单一操作：使用 CLI 或脚本，并按需由 Skill 调用；
• 仅需连接外部服务：优先完善 MCP/App，无须附加不承载实际流程的 Skill；
• 任务边界仍在频繁变化：使用本地 Skill 迭代，以降低过早版本化带来的兼容成本。

四、加载与运行生命周期

Plugin 从安装到运行一次完整的分发至少涉及来源、目录、安装状态与会话加载四层。

该图说明三类常见状态差异：源码修改不会立即影响当前会话；Marketplace 更新不一定刷新已安装副本；Plugin 卸载也不一定撤销外部 Connector 授权。

Plugin 的四层状态模型

在默认分层模型中，Marketplace 主要提供 Plugin 的发现目录和源码位置；部分 Host 还允许它在特定分发模式下选择组件。无论采用哪种模式，仅登记 Marketplace 条目都不等于安装、启用或把能力注册进当前会话。

组件触发与执行流程

一个典型请求会经过：

1. 新会话读取已启用 Plugin 的组件描述；
2. 用户的自然语言请求触发隐式调用，或使用当前 Host 的显式入口：ChatGPT 用 @Plugin，Codex 用 $skill-name，Claude Code 用 /<plugin-name>:<skill-name>；
3. Host 选择 Skill、Agent 或工具；
4. Skill 按需加载详细指令和 references；
5. MCP/App 请求经过认证和工具审批；
6. Hook 在匹配的生命周期节点介入；
7. 结果回到 Agent，由模型继续判断和生成。
   Plugin 不会绕过 Host 的 Sandbox、Approval、组织策略或外部服务权限。组件能否执行仍由运行时安全边界决定。

修改后未生效的常见原因

• Codex / ChatGPT：安装或更新后通常需要新建 Task、Chat 或 CLI Session，让组件重新注册。
• Claude Code：开发中可用 /reload-plugins 重新加载；Marketplace 安装会使用缓存副本，源码目录的修改不等于缓存已更新。
• MCP：配置被加载不代表 Server 成功启动，也不代表工具已经通过审批。
• Hook：文件存在不代表已被信任、已匹配事件或脚本可执行。
  排错应先确定状态过期的层级，再选择刷新目录、重装、重启 Server 或新建会话。

五、分发与版本管理

Plugin manifest 与 Marketplace manifest

Plugin 分发使用两份职责不同的清单。Marketplace manifest 先告诉 Host“有哪些 Plugin、源码在哪里”；取得源码后，Host 再读取 Plugin manifest，确认“这个 Plugin 版本信息、包含哪些组件”。

Plugin manifest：定义一个 Plugin

Plugin manifest 位于 Plugin 源码根目录下：Codex 原生使用 .codex-plugin/plugin.json，Claude Code 使用 .claude-plugin/plugin.json。它以一个 Plugin 为描述对象，字段可分为三组：

下面示例同时声明身份、Skill root、MCP 配置和展示信息：

{
  "name": "repo-review",
  "version": "1.0.0",
  "description": "Review repository changes with team rules.",
  "author": {
    "name": "Example Team"
  },
  "skills": [
    "./skills/review",
    "./skills/security-review"
  ],
  "mcpServers": "./.mcp.json",
  "interface": {
    "displayName": "Repo Review",
    "shortDescription": "Review changes with team rules",
    "longDescription": "Bundle repository review workflows and tools.",
    "developerName": "Example Team",
    "category": "Developer Tools",
    "capabilities": ["Read"],
    "defaultPrompt": [
      "Review my current changes."
    ],
    "brandColor": "#2563EB",
    "logo": "./assets/logo.png"
  }
}

interface 是 Plugin manifest 内的展示字段组，它影响用户在安装前看到什么。单个 Codex Skill 还可以用 skills/<name>/agents/openai.yaml 定义自己的 interface、调用策略和工具依赖；那是 Skill 级元数据，不是 Plugin 或 Marketplace manifest。

Marketplace manifest：定义可安装目录

Marketplace manifest 以一个 Plugin 目录为描述对象。顶层定义 Marketplace 身份与展示名，plugins[] 中的每一项定义一个可发现的 Plugin、源码位置和安装策略：

一个 Codex 本地 Marketplace 示例：

{
  "name": "team-tools",
  "interface": {
    "displayName": "Team Tools"
  },
  "plugins": [
    {
      "name": "repo-review",
      "source": {
        "source": "local",
        "path": "./plugins/repo-review"
      },
      "policy": {
        "installation": "AVAILABLE",
        "authentication": "ON_INSTALL"
      },
      "category": "Developer Tools"
    }
  ]
}

这里的 source.path 指向 Plugin 源码根目录，Host 到达该目录后才读取其中的 plugin.json。相对路径以 Marketplace 根目录为基准，不是以 .agents/plugins/ 或 .claude-plugin/ 子目录为基准。

Marketplace 中的组件选择

Marketplace schema 也允许在 Plugin 条目上声明 skills 等组件字段，用于从共享源码中选择或重新组合能力。此时必须先判断字段属于哪一份 manifest：

Claude Code 用 strict 决定两份定义如何配合：strict: true 默认以 Plugin manifest 为权威，并允许 Marketplace 条目补充组件；strict: false 则由 Marketplace 条目完整定义组件，源码目录可以不提供 plugin.json。后者适合把一个共享仓库拆成多个虚拟 Plugin，不适合普通 Plugin 重复维护两套组件清单。

例如，可以从同一个 Skill 仓库中只分发文档能力：

{
  "name": "document-skills",
  "source": "./",
  "strict": false,
  "skills": [
    "./skills/xlsx",
    "./skills/docx",
    "./skills/pdf"
  ]
}

个人级与仓库级 Marketplace

这里的“个人级”和“仓库级”描述的是 Marketplace 目录的归属和发现范围。

个人级 Marketplace 的默认文件会被 Codex 隐式发现。仓库级 Marketplace 只有在宿主传入当前工作目录或工作区根、由 Codex 再解析到对应 Git 仓库根时才会参与发现；如果使用没有传入工作区根目录的 CLI 入口，则需要显式执行 codex plugin marketplace add <repo-root>。这个命令登记的是当前用户的 Marketplace 来源，不会替其他成员修改其本地配置。

两种 Marketplace 的 source.path 都相对 Marketplace 根目录 解析，不是相对 marketplace.json 所在的 .agents/plugins/ 子目录：

个人级：
~/.agents/plugins/marketplace.json
~/plugins/repo-review/
 
仓库级：
$REPO_ROOT/.agents/plugins/marketplace.json
$REPO_ROOT/plugins/repo-review/

最关键的是：仓库级 Marketplace 只让目录随仓库共享，不会把 Plugin 变成“仅在该仓库启用”。 仓库成员克隆代码后，可以在该仓库上下文中发现同一批 Plugin，但仍需各自在本机安装和启用。安装副本与启用记录保存在各自的 $CODEX_HOME；同一用户安装后，这份状态可在其他仓库继续生效。如果能力必须只对当前仓库生效，不能只依赖仓库级 Marketplace 来隔离作用域。

Plugin 身份由 <plugin>@<marketplace> 决定，而不是由个人级或仓库级这个层级决定。只有 Marketplace 顶层 name 不同时，repo-review@personal 和 repo-review@team-tools 才是两个不同的来源身份；如果两处的 Marketplace name 和 Plugin name 都相同，宿主可能按发现顺序去重，容易造成来源不明确。

这里的 Marketplace 作用域不要与 Claude Code 后文的 user、project、local 安装作用域混淆：前者决定目录由谁维护、何时被发现，后者决定安装配置写在哪里。

Codex / ChatGPT 的分发与安装

发布方

1. 在 Plugin Repo 根目录提供 .codex-plugin/plugin.json 和实际组件；兼容包也可以提供 .claude-plugin/plugin.json。
2. 将源码放在团队仓库、本地目录或受支持的包来源中。
3. 根据使用范围，将 Plugin 登记到个人级或仓库级 Marketplace；需要公开分发时，再提交到公共 Plugin Directory。

用户侧

codex plugin marketplace add owner/repo
codex plugin marketplace list
codex plugin marketplace upgrade team-tools

添加 Marketplace 后，在 /plugins 或对应图形界面中选择并安装 Plugin。安装完成后还需要：

1. 启用 Plugin；
2. 完成 App/Connector 账号授权和 MCP 工具审批；
3. 审查并信任需要自动执行的 Hook；
4. 新建 Task、Chat 或 CLI Session，验证 Skill 和工具是否已经注册。

仓库级 Marketplace 适合随项目共享，个人级 Marketplace 适合跨项目自用，Workspace 分享和公共 Plugin Directory 适合更广范围分发。它们改变的是发现范围，不会绕过安装、授权和会话加载。

Claude Code 的分发与安装

Claude Code 的正式分发同样分两步：先添加 Marketplace，再安装其中的具体 Plugin。

/plugin marketplace add owner/repo
/plugin install repo-review@team-tools

安装时选择作用域：

常用管理命令为：

claude plugin list
claude plugin details repo-review@team-tools
claude plugin update repo-review@team-tools
claude plugin disable repo-review@team-tools
claude plugin enable repo-review@team-tools
claude plugin uninstall repo-review@team-tools --prune

安装、启停或更新后执行 /reload-plugins，或者新建会话。claude --plugin-dir 只适合当前会话的开发验证；它不建立正式安装台账，也不验证 Marketplace、版本缓存和升级链路。

默认采用 plugin.json 作为组件权威来源。只有需要从共享仓库策展多个“虚拟 Plugin”时，才使用 Marketplace 的 strict: false 和组件路径重新编排；普通 Plugin 不应在两处重复维护同一组组件定义。

版本、缓存与升级

版本管理只需守住以下规则：

1. ID 稳定：name 是安装、更新和依赖解析的稳定标识，不能跟着展示文案变化。
2. 版本可判定：稳定发布使用 SemVer；内部固定发布可以使用不可变 Git SHA 或 tag。
3. 内容变化就换版本：显式版本号不变时，客户端可能继续命中旧缓存。
4. 版本只有一个权威来源：不要在 Plugin manifest 与 Marketplace 条目中长期维护冲突版本。
5. 缓存不是源码目录：修改开发目录或刷新 Marketplace 后，仍要确认已安装副本是否真的更新。

一次可靠升级应完成整条闭环：

发布新版本
→ 刷新 Marketplace
→ 更新或重装已安装 Plugin
→ 核对实际安装版本
→ 新建会话或 reload
→ 验证 Skill、MCP 与 Hook

Codex 的 marketplace upgrade 首先刷新目录信息，不应仅凭这一步判断已安装 Plugin 已更新。Claude Code 可以显式执行 claude plugin update；是否自动更新取决于 Marketplace 配置，更新后仍需 /reload-plugins 或新会话。

停用、卸载与残留状态

停用只阻止 Plugin 继续加载，卸载则移除安装记录和缓存副本；两者都不一定清理外部状态：

• App/Connector 的 OAuth 授权通常需要在账号连接管理中单独撤销；
• PLUGIN_DATA / CLAUDE_PLUGIN_DATA 中的持久数据需要按产品规则或 README 说明清理；
• Plugin 创建的远端数据、评论、工单和构建不会因卸载自动回滚；
• 团队 Marketplace 条目仍然存在时，其他用户仍可继续发现和安装该 Plugin。

发布前至少实际验证一次：全新安装、升级、停用、卸载、重新安装和新会话加载。发布说明应写清版本变化、权限与数据去向、持久数据处理、降级方式和已知限制。

六、安全、质量与排错

Plugin 的设计原则

符合目录规范只是基础要求。Plugin 的质量取决于任务边界、组件协作、失败可见性和维护方式。

任务契约与组件选型

一个可交付的 Plugin 应明确以下内容：

• 预期交付结果；
• 输入、账号、网络与本地依赖；
• 会修改数据或外部状态的操作；
• 成功验收标准与失败证据；
• 不支持的场景。
  在任务契约尚未明确时扩充组件，会增加任务边界的不确定性和维护成本。

组件职责与协作边界

各类组件可以按以下方式分工：

• Skill：定义任务阶段、判断规则、失败边界和验收标准；
• 旧 Command：只保留现有 commands/*.md 的迁移或兼容入口；新参数化入口使用可手动调用的 Skill，不复制另一份流程；
• 工具：完成单一的任务级动作，并明确副作用；
• Hook：使用快速、确定性的高频逻辑，将复杂审查安排在阶段末；
• Agent：按互斥维度拆分，并提供可整合的输出契约；
• Plugin：围绕同一任务目标组织全部组件。

上下文成本管理

Plugin 安装后，组件名称和描述可能进入每次会话的发现上下文；触发组件后，Skill、Agent 和 references 会继续消耗上下文。Claude Code 的 plugin details 会估算 always-on 和 on-invoke token cost，因此组件数量和描述长度都属于运行成本的一部分。
常用的优化顺序是：

1. 缩短 description；
2. 把细节移入按需 references；
3. 合并重复 Skill；
4. 优化过度泛化的 Skill；
5. 让脚本处理确定性转换，避免模型重复读取机械性规则。

安装路径适配

Marketplace 安装往往运行缓存副本，版本目录会变化。Hook、MCP 和脚本应通过 Host 提供的 Plugin 根变量定位包内文件，通过 ${PLUGIN_DATA} 或 ${CLAUDE_PLUGIN_DATA} 保存持久数据。
跨 Codex 与 Claude Code 运行时，可以增加一层稳定包装脚本（wrapper）：包装脚本只负责识别 Host 环境、定位实际脚本并转发 stdin/stdout，业务脚本无需感知缓存目录。相关案例见 Codex Plugin CC Rescue 原理。

README 的运行边界说明

README 至少应包含：

1. 目标结果与适用场景；
2. 安装和启用方式；
3. 最小示例与预期输出；
4. 组件清单及各组件的引入理由；
5. 账号、网络、二进制和版本依赖；
6. 权限、数据去向、日志和隐私；
7. 失败模式与排错入口；
8. 升级、卸载和持久数据处理；
9. 已知限制和不支持场景。
   这些信息用于说明安装后的自动行为、数据访问范围、停用方式和残留状态。

常见 Plugin 设计模式

以下模式说明不同任务中常见的组件组合及其适用边界。

Skills-only：知识与方法封装

适合规范、写作、开发方法和审查清单。核心是渐进式加载：主 Skill 只保留决策流程，细节进入 references，确定逻辑进入 scripts。
优点是权限面小、易分发；风险是把资料堆积误当成工作流。Anthropic 官方示例中的 plugin-dev 就属于这种思路。

Skills + MCP：方法与工具闭环

当任务同时依赖操作方法和实时系统时，可以由 Skill 编排流程，由 MCP 提供读取与写入动作。Notion、GitHub 和数据平台等集成通常适合这种组合。
MCP 工具应围绕任务级动作设计。直接暴露大量底层接口会增加工具选择和调用编排的负担。

Hook 分层：快速检查、阶段审查与提交校验

高频 PreToolUse 用正则或轻脚本阻断明显风险；Stop 阶段执行较深的 diff 审查；影响提交结果的检查应部署在提交阶段或 CI 中。Anthropic 官方示例中的 security-guidance 展示了这种延迟与覆盖率的取舍。
各层应具有不同的成本、误报率和阻断权限，避免重复执行同类检查。

多 Agent：按审查维度并行

代码评审可以拆成安全、测试、类型设计、历史上下文和注释准确性。每个 Agent 只负责一个维度，再由主线程去重和排序。
多个 Agent 若采用相同的宽泛审查范围，容易产生重复和低置信度结果。

双端适配：共享业务能力与端侧装配

对于 iplugin 的跨端桥接 一类双端能力，可以共享 Skills 与脚本的单一事实源，分别维护 Codex / Claude Code manifest、Hook 事件和加载入口，再通过包装脚本适配缓存路径和环境变量。
双端 Plugin 需要分别验证升级、缓存、权限和失败恢复机制，不能以一端的测试结果替代另一端。

Plugin 的安全模型

Plugin 可以携带脚本、MCP Server、Hook、bin 和外部连接，属于高信任扩展。安装前应按照依赖与自动化脚本的标准审查其来源和行为。

Plugin 与 Host 的权限边界

Plugin 的安装不会自动放宽 Host 权限：

• Codex Plugin 仍受 Sandbox、Approval Policy 和组织策略约束；
• MCP 工具仍可以按 Server 或 Tool 单独审批；
• Codex Plugin Hook 在信任当前定义前会被跳过；
• Claude Code 的 Hook、MCP、Agent 和 Bash 仍受其权限系统控制；
• 外部服务只允许账号本身有权做的操作。
  要求永久开放全部工具、网络和写权限的 Plugin 缺少最小权限设计，不应将其视为常规安装要求。

密钥与持久数据管理

• 密钥不得写入 Git、Skill、manifest、日志或示例；
• 使用 Connector OAuth、系统钥匙串、Plugin userConfig 的敏感存储或受控环境变量；
• 缓存和依赖存放在 PLUGIN_DATA / CLAUDE_PLUGIN_DATA；
• 日志默认脱敏，不记录完整 token、Cookie、私有文档或工具原始响应；
• 卸载时说明哪些授权、缓存和外部数据需要另行清理。

Hook 安全检查项

Hook 会自动运行，因此至少需要检查：

1. 触发事件是否过宽；
2. matcher 是否仅匹配目标工具或文件；
3. 命令是否使用安全的参数传递；
4. stdin JSON 是否做输入校验；
5. 超时和失败是 fail-open 还是 fail-closed；
6. 阻断结果能否向用户提供清晰说明；
7. 更新 Hook 后是否需要重新信任。

Plugin 的分层排错方法

Codex 排错流程

codex plugin marketplace list
→ Plugin 浏览器确认来源和状态
→ 检查 .codex-plugin/plugin.json 与 source.path
→ 检查 ~/.codex/config.toml 中启用状态和 MCP 审批
→ 新建 Task / CLI Session
→ 通过最小 Prompt 显式触发

Claude Code 排错流程

claude plugin validate ./my-plugin
→ claude plugin list / details
→ claude --debug 查看加载与 MCP 初始化
→ /reload-plugins
→ /plugin Errors 查看 manifest、Hook、LSP 错误
→ 通过 /plugin-name:skill-name 显式触发

排错时应记录来源、安装版本、缓存路径、会话开始时间以及 MCP/Hook 状态。清空缓存会移除现场信息，适合在上述信息完成记录且其他检查无效后使用。

常见反模式

总结

1. Plugin 是分发容器，不是新的推理机制、工具类型或通信协议。
2. Skill 定义任务方法；Claude Code 的旧 Command 是 Skill 的兼容布局；MCP/App 提供工具与数据，Hook 实施生命周期约束，Agent 负责独立子任务。
3. Marketplace、Plugin 源码、安装缓存和会话状态属于不同层级，需要分别管理。
4. 本地 Skill 适合早期迭代；出现组合安装、版本化或团队分发需求后，再封装为 Plugin。
5. Codex 与 Claude Code 共享能力包抽象；当前 Codex 可兼容 Claude manifest，Skills-only Plugin 可以复用一份共同配置，端侧能力仍需分别装配。
6. Plugin 安装不会绕过 Sandbox、Approval、Hook 信任机制或外部账号权限。
7. Plugin 的质量体现为任务边界清楚、失败可见、升级可控和卸载行为明确，而非组件数量。

参考

OpenAI / Codex

• Plugins：浏览、安装与使用
• Build plugins：结构、manifest、Marketplace 与分发
• Customization：AGENTS.md、Skill、Plugin、MCP 的边界
• Build skills
• MCP
• Build an app
• Submit plugins

Anthropic / Claude Code

• Create plugins
• Plugins reference
• Extend Claude with skills
• Commands reference
• Agent SDK custom slash commands
• Discover and install plugins
• Create and distribute a plugin marketplace
• Plugin dependency versions
• Hooks reference
• Claude Code 官方 Plugin 示例

相关笔记

• Agent Skills 完全指南
• Agent MCP 完全指南
• Codex 与 Claude Code 的 Skill Plugin Hook 机制
• Codex config 配置说明
• Codex Plugin CC Rescue 原理