Claude Code 插件：安装、制作与发布

这篇适合谁

适合已经在用 Claude Code、想把自己的 skills、agents、hooks 或 MCP 服务器打包起来，或者想安装别人搭好的一套配置的人。读完你能判断插件是不是合适的工具，从市场安装一个插件，做一个只带一个 skill 的小插件，校验并加载它，最后选择分享方式。

插件是什么，什么时候需要它

Claude Code 插件是一个目录，里面装着 Claude Code 作为一个整体安装和加载的组件。这些组件可以是 skills、agents、hooks、MCP 服务器等。大多数插件来自市场^[1]。

skills、subagents、hooks 和 MCP 服务器不装插件也能单独使用。插件适合在你想把几样东西打包在一起时使用；想用一条命令装上别人搭好的配置并接收它的更新时使用；想把自己的配置分享给团队时也适合用^[1]^[2]。

清单（manifest）是位于 .claude-plugin/plugin.json 的 JSON 文件，它给插件起名，还可以补充版本、描述等元数据^[1]。skill 是一个 SKILL.md 指令文件，Claude 在相关时加载它，你也可以把它当命令运行。subagent 是 Claude 可以委派任务的定义。hooks 是 Claude Code 在生命周期特定节点运行的命令。MCP 服务器是插件启用期间 Claude Code 连接的工具服务器^[1]。

先了解启用插件的成本

插件一旦启用，就会进入每一个会话，而不只是你用到它的那几个。Claude 能自行调用的 skills 和 agents，其名称与描述会在每一轮都留在 Claude 的上下文里；插件的 MCP 服务器会随每个会话运行，插件的 hooks 也会在对应事件发生时触发。插件运行的任何东西，都是以你的身份运行的^[1]。

安装前要先看这一点。在 /plugin 的 Marketplaces 标签页里，Anthropic 官方市场的插件会显示上下文成本估算。如果想保留插件但暂时不用，可以用 /plugin 或在 shell 里运行 claude plugin disable 将其停用^[1]。

从市场安装

市场是一个带有 .claude-plugin/marketplace.json 文件的仓库或目录。文件里列出插件，并说明每个插件从哪里获取。它是一份目录，而不是托管的商店^[1]。Claude Code 在你第一次启动交互式终端会话时，会自动添加 Anthropic 官方市场，除非托管策略禁止^[1]。

在 Claude Code 的终端会话里运行 /plugin，然后在 Discover 标签页里安装插件，这里列出了你添加过的市场中的全部插件^[1]。安装时要选择作用范围：user 范围对你电脑上的所有项目生效；project 范围通过提交到仓库的 .claude/settings.json 对所有协作者生效；local 范围只对当前仓库生效^[1]。

市场分为三个等级：官方市场、社区市场和第三方市场。官方名称包括 claude-plugins-official 和 claude-code-plugins；claude-community 这类名称属于社区市场；其他都是第三方市场。插件可以用你的用户权限运行代码，所以对待第三方市场要和对待任何代码一样谨慎^[1]。

做第一个插件

需要先安装并登录 Claude Code^[2]。教程会做一个只有问候 skill 的插件，并用 --plugin-dir 加载它。这个参数可以只在一个会话里加载插件，不需要安装^[2]。

先在工作目录里创建插件目录，并在其中建一个 .claude-plugin/ 文件夹：

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

把清单保存为 my-first-plugin/.claude-plugin/plugin.json：

{
  "name": "my-first-plugin",
  "description": "A greeting plugin to learn the basics",
  "version": "1.0.0",
  "author": {
    "name": "Your Name"
  }
}

name 是必填项，它会成为插件提供的每个 skill 和 agent 的前缀，因此名称里不要有空格。description 是 /plugin 里显示的插件说明。version 可选，设置后用户会停留在该版本，直到你修改它。author 里必须有 name^[2]。

每个 skill 是 skills/ 下的一个目录，里面有一个 SKILL.md 文件。创建目录：

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

然后把 my-first-plugin/skills/hello/SKILL.md 保存为以下内容：

---
name: hello
description: Greet the user with a friendly message
disable-model-invocation: true
---
Greet the user warmly and ask how you can help them today.

disable-model-invocation: true 表示 Claude 不会自己运行这个 skill。如果你希望 Claude 自行运行某个 skill，就删掉这一行。这个 skill 的命令会把插件名和 skill 名组合起来，即 /my-first-plugin:hello^[2]。

校验放在加载之前，是为了让清单和 frontmatter 的错误先暴露出来。失败时不要反复重跑命令，应当逐条看报错指向的字段。

校验和加载

启动会话前先运行校验：

claude plugin validate ./my-first-plugin

通过时会打印 ✔ Validation passed。如果打印的是 ✘ Validation failed，结果行上方的每一行都会指出需要修改的字段^[2]。

接着用插件启动会话并运行 skill：

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

进入会话后输入 /my-first-plugin:hello。插件只在带 --plugin-dir 启动的会话里加载。会话中途修改了插件文件，运行 /reload-plugins 即可加载改动^[2]。

这个参数接受目录或 .zip 压缩包，并且可以重复使用。--plugin-url 可以在一个会话里从 URL 获取 .zip；如果无法加参数，可以用 CLAUDE_CODE_PLUGIN_DIRS 环境变量列出绝对路径^[2]。另一种做法是 claude plugin init my-tool，它会在 ~/.claude/skills/ 下生成一个每次会话都加载的插件；加上 --with skills 还会在 skills/ 下建一个 skill^[2]。

skill 名会带上插件名作为前缀，所以两个插件各自的同名 skill 不会在命令列表里冲突。这也是为什么清单里的 name 要认真起。

插件的目录结构

插件根目录就是你传给 --plugin-dir 的目录。其中，.claude-plugin/plugin.json 是清单。skills/ 每个 skill 对应一个 <name>/SKILL.md 目录。commands/ 放扁平的 Markdown 文件，是较早的 skill 写法，新插件应当使用 skills/。agents/ 每个 subagent 一个 Markdown 文件。hooks/hooks.json 配置 hooks，.mcp.json 定义 MCP 服务器。只有 plugin.json 应该放在 .claude-plugin/ 里面^[2]。