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

作者：袖梨 2026-07-29

这次要介绍的主题，是 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/` 配置	使用插件
仅供当前项目使用	✅	不需要
个人试用	✅	不需要
希望跨项目复用	❌	✅
希望与团队分享	❌	✅
要求版本管理及自动更新	❌	✅
准备发布到社区市场	❌	✅

简单概括：

自用、临时、项目专属 → 用 .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 就会称呼你的名字回应。

两项主要差异

项目	Claude Code	Codex
描述文件所在目录	`.claude-plugin/plugin.json`	`.codex-plugin/plugin.json`
创建方法	手动 `mkdir` + 编写文件	`@plugin-creator` 生成插件骨架
调用 skill	`/plugin-name:skill-name`	`$skill-name`
本地载入	`claude --plugin-dir ./my-plugin`	`codex plugin marketplace add ./my-plugin`