什么是 Claude Code / Codex 插件、应该什么时候用？

这次要介绍的主题，是 OpenAI Codex 与 Claude Code 的插件。

一、什么叫插件？

可以把 Claude Code 或 Codex 想象成一名助手：它起初只能读代码、修改代码和运行命令等基础工作；安装工具包，也就是插件后，它便能掌握新的技能。

例如：

• 安装「代码检查工具包」后，它可以自动发现代码错误；
• 装上「部署工具包」，它便能协助发布应用；
• 连接数据库和查看表结构的能力，可以由安装的「数据库工具包」提供。

一条命令即可为 Claude 扩展能力，背后依靠的就是 Claude Code 插件。作为可安装的能力包，它能够将外部工具集成（MCP）、自动化钩子、子 agent 以及一个或多个技能统一封装。

二、插件包含哪些内容？

插件并非只有一项功能，而是一个可容纳多种组件的文件夹：

• Skills：例如「帮我重构这段代码」，这类给 Claude 使用的「指令模板」；
• Agents：安全审计 agent、代码评审 agent 等面向特定任务的子助手；
• Hooks：例如「文件保存后自动跑 lint」这样的事件触发器；
• MCP Servers：用于接入外部工具，可连接数据库、浏览器、Slack、Jira、GitHub；
• LSP Servers：代码补全、跳转等语言级智能可借此提供给 Claude；
• Monitors：在后台盯住日志文件，一旦报错便通知 Claude。

团队专属开发助手可以由通用 Claude Code 转化而来，所需方式就是组合这些组件。

三、插件 vs 项目内配置

Claude Code 提供两种扩展方式：

方式一：放在项目内 .claude/ 配置

直接在项目中创建一个 .claude/ 目录，用于容纳 hooks、agents 和 skills。适合以下情况：

• 仅供当前项目使用；
• 个人快速验证；
• 不准备处理安装及版本管理。

方式二：插件（Plugin）

将能力整理成带有 plugin.json 描述文件的独立目录，使其能够安装、分享和更新。适用于：

• 在多个项目之间复用；
• 提供给团队或社区使用；
• 需要进行版本控制；
• 分发渠道准备选择插件市场（Marketplace）。

官方建议是先在公司项目中进行 .claude/ 快速迭代，确认有效后再封装为插件。

四、哪些时候适合用插件？

不少人拿不准插件的使用时机，其实判断标准并不复杂：

简单概括：

• 自用、临时、项目专属 → 用 .claude/；
• 需要复用、分享、发布 → 封装成插件。

五、用5 分钟创建首个插件

弄清「是什么」与「什么时候用」后，接下来直接制作一个最简插件。

步骤 1：建立插件目录

mkdir my-first-plugin

该目录将作为插件根目录，今后所有插件文件都存放于此。

步骤 2：编写插件描述文件

创建 .claude-plugin/plugin.json：

mkdir -p my-first-plugin/.claude-plugin

写入：

{"name": "my-first-plugin","description": "一个最简的问候插件","version": "1.0.0","author": {"name": "Your Name"}}

name 它既是插件的唯一标识，也是技能所用的命名空间。

步骤 3：建立第一个 Skill

mkdir -p my-first-plugin/skills/hello

在 my-first-plugin/skills/hello/SKILL.md 中写入：

---description: 向用户热情地打招呼---用温暖、热情的语气问候用户，并问他今天需要什么帮助。

一段说明技能具体职责的自然语言指令，构成了 Skill 的核心，并供 Claude 理解其任务。

步骤 4：在本地测试

claude --plugin-dir ./my-first-plugin

输入内容前，先进入 Claude Code：

/my-first-plugin:hello

若 Claude 热情回应，就表示插件已经成功运行。

步骤 5：让 Skill 获取参数

把 SKILL.md 修改为：

---description: 用名字向用户打招呼---用温暖、热情的语气问候用户 "$ARGUMENTS"，并问他今天需要什么帮助。

然后运行：

/my-first-plugin:hello Alex

随后 Claude 会称呼你的名字进行回应。

常见错误提示

• plugin.json 必须置于 .claude-plugin/ 之下；
• skills/、agents/、hooks/ 等目录应放在插件根目录，不要放入 .claude-plugin/ 之中；
• 插件修改完成后，运行 /reload-plugins Claude Code 无须退出，便能完成重新加载。

七、对比：如何创建Codex 插件？

OpenAI 的 Codex CLI 同样提供类似的插件系统，其设计与 Claude Code 十分接近：采用相同的 SKILL.md + plugin.json 思路，只在目录名称与调用方法上略有差异。

Codex 更方便之处在于，它内置一个 @plugin-creator 技能，可直接生成插件骨架。接下来使用 @plugin-creator 制作同样的「hello」问候插件，再与手动修改得到的文件进行比较。

步骤 1：使用 @plugin-creator 生成

codex@plugin-creator

按提示填写插件名称，例如 my-codex-plugin。随后 Codex 会自动建立 .codex-plugin/plugin.json 与 skills/ 目录。

步骤 2：将 plugin.json 修改成 hello 插件

{"name": "my-codex-plugin","description": "一个最简的问候插件","version": "1.0.0","author": {"name": "Your Name"}}

步骤 3：把 Skill 改成 hello 问候

在生成的 skills/hello/SKILL.md 里写：

---description: 向用户热情地打招呼---用温暖、热情的语气问候用户，并问他今天需要什么帮助。

步骤 4：进行本地测试

Codex 本地市场需要先加入该插件目录：

codex plugin marketplace add ./my-codex-plugin

打开 Codex 后输入：

$hello

如果看到 Codex 热情地回应你，说明插件已经跑通。

步骤 5：让 Skill 获取参数

把 SKILL.md 修改为：

---description: 用名字向用户打招呼---用温暖、热情的语气问候用户 "$ARGUMENTS"，并问他今天需要什么帮助。

然后运行：

$hello Alex

Codex 就会称呼你的名字回应。

两项主要差异

常见错误提示

• .codex-plugin/ 不要混淆目录与 .claude-plugin/ ；
• Codex 调用 skill 时不需要加插件前缀，直接用 $hello；
• 插件修改后，应查看 Codex 当前版本支持的命令来确定重新加载方法（可使用 /plugins 检查状态）。

八、下篇内容预告

下一篇将完整梳理插件结构，说明 skills、agents、hooks、MCP、LSP、monitors 分别是什么以及适用时机。掌握这些内容后，你便能依据自身工作流设计插件，不必再局限于照抄文档示例。