什么是 Claude Code / Codex 插件、何时使用？

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

一、什么是插件？

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

例如：

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

只需一条命令，Claude 的能力便可得到扩展。实现这一点的 Claude Code 插件，本质是可安装的能力包，其中集中封装了外部工具集成（MCP）、自动化钩子、子 agent 以及一个或多个技能。

二、插件包含哪些内容？

插件并非单一功能，而是一个能够容纳多类组件的文件夹：

• Skills：例如「帮我重构这段代码」，属于交给 Claude 的「指令模板」；
• Agents：安全审计 agent、代码评审 agent 等子助手，各自专门负责某类任务；
• Hooks：像「文件保存后自动跑 lint」这样的操作，会由事件触发；
• MCP Servers：GitHub、Jira、Slack、浏览器和数据库等，都可作为其连接的外部工具；
• LSP Servers：代码补全、跳转等语言级智能，由此提供给 Claude；
• Monitors：负责后台盯住日志文件，一旦报错便通知 Claude。

团队专属开发助手可以由通用 Claude Code 转化而来，关键在于组合使用这些组件。

三、插件 vs 项目内配置

Claude Code 提供两种扩展方式：

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

直接在项目中创建一个 .claude/ skills、agents、hooks 均置于该目录中。适合：

• 仅在当前项目使用；
• 个人进行快速试验；
• 不希望处理安装及版本管理。

方式二：插件（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: 向用户热情地打招呼---用温暖、热情的语气问候用户，并问他今天需要什么帮助。

告诉 Claude 该技能要完成什么，是 Skill 核心自然语言指令的作用。

步骤 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 各自是什么以及何时使用。掌握这些内容后，你便能依据自身工作流设计插件，不再只是跟着文档复制示例。