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

今天的话题，是 OpenAI Codex 与 Claude Code 的插件。

一、插件究竟是什么？

可以把 Claude Code 或者 Codex 想象成一个助手。它起初只能完成读代码、改代码、跑命令等基础工作；安装工具包（插件）后，这个助手便能掌握新的技能。

例如：

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

一个或多个技能、子 agent、自动化钩子及外部工具集成（MCP），可以被整合成一个可安装的能力包，这就是 Claude Code 的插件。安装后，只需一条命令，Claude 的能力便能得到扩展。

二、插件由什么组成？

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

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

团队专属开发助手，可以由一个通用 Claude Code 组合这些组件后得到。

三、插件 vs 项目内配置

Claude Code 提供两种扩展方式：

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

直接在项目中创建一个 .claude/ 目录，用于容纳 agents、hooks、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: 向用户热情地打招呼---用温暖、热情的语气问候用户，并问他今天需要什么帮助。

告诉 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 各自是什么以及何时使用。理解这些内容后，你就能按照自己的工作流设计插件，不再只是照抄文档示例。