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

今天就聊聊 Claude Code 和 OpenAI Codex 的插件，聊聊它们到底是什么、什么时候该用、怎么快速上手。

一、插件是什么？

想象你有一个助手（Claude Code 或者 Codex）。一开始，这个助手只会做基础工作：读代码、改代码、跑命令。但你可以给它安装工具包（插件），让它学会新技能。

比如：

• 你给它装一个「代码检查工具包」，它就能自动找出代码错误；
• 你给它装一个「部署工具包」，它就能帮你发布应用；
• 你给它装一个「数据库工具包」，它就能连接数据库、查表结构。

Claude Code 的插件，本质上就是这样一个可安装的能力包。它把一个或多个技能、子 agent、自动化钩子、外部工具集成（MCP）打包在一起，让你用一条命令就能扩展 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/ 目录，里面放 skills、agents、hooks。适合：

• 只在这个项目里用；
• 个人快速试验；
• 不想折腾安装和版本管理。

方式二：插件（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

常见错误提醒

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

八、下一篇预告

下一篇我们进入插件结构全景：skills、agents、hooks、MCP、LSP、monitors 分别是什么、什么时候用。理解之后，你就能根据自己的工作流设计插件，而不是只会照着文档抄例子。