Claude Code 插件教程：安装、市场与自建插件（2026）

如果你已经在用 Claude Code 写 CLAUDE.md、配 hooks、拆 subagents，那你迟早会遇到一个问题：这些配置怎么分享给同事？复制粘贴 .claude/ 目录既不好维护也没法版本化。Claude Code 插件（Plugins）就是官方给出的答案——把 skills、subagents、hooks、MCP server、甚至 LSP server 打包成一个可安装、可版本化、可通过市场分发的单元。这篇 Claude Code 插件教程从安装现成插件讲到自己造轮子、自建插件市场，命令全部来自官方文档实测。

Claude Code 插件是什么

一个插件就是一个自包含的目录，里面可以放 skills、agents、hooks、MCP 配置等扩展，通常还带一份 .claude-plugin/plugin.json 清单文件描述它的身份。用户通过「市场（marketplace）」发现并安装它，安装后插件的 skill 会以插件名做命名空间前缀调用，比如 /my-plugin:hello。

理解插件体系有三层关系：Marketplace（目录，列出有哪些插件）→ Plugin（可安装单元）→ 组件（skills / agents / hooks / MCP server）。市场只是一份索引，真正的插件内容可以托管在完全不同的仓库里。

插件 vs .claude/ 独立配置：什么时候该用哪个

Claude Code 支持两种加自定义能力的方式，官方给的判断标准很清楚：

安装现成插件：官方市场与社区市场

Anthropic 维护着两个公共市场。claude-plugins-official 是官方精选集，你第一次以交互模式启动 Claude Code 时会自动注册；claude-community 是社区市场，第三方插件审核后进入，需要手动添加。

# 添加社区市场（官方市场通常已自动注册）
/plugin marketplace add anthropics/claude-plugins-community

# 安装一个插件：插件名@市场名
/plugin install some-plugin@claude-community

# 装完让它生效，不用重启
/reload-plugins

这些斜杠命令在非交互脚本里也有等价的 CLI 子命令，方便写进 CI 或 Dockerfile：

claude plugin marketplace add anthropics/claude-plugins-official
claude plugin marketplace add acme-corp/claude-plugins@v2.0   # @ref 固定分支或标签
claude plugin marketplace list --json
claude plugin marketplace update            # 省略名字则更新全部
claude plugin marketplace remove <name>

插件目录结构：最容易踩的坑

插件根目录（也就是包含 .claude-plugin/plugin.json 的那一层）下可以放这些内容：

手写第一个插件

从一个只带 skill 的最小插件开始。三步：建目录、写清单、写 skill。

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

清单文件 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 的命名空间前缀；description 在插件管理器里展示；version 可选，设了之后只有你改这个字段用户才会收到更新，省略则用 git commit SHA，每次提交都算新版本；author 可选。

然后写 skill，文件是 my-first-plugin/skills/hello/SKILL.md，目录名就是 skill 名：

---
description: Greet the user with a personalized message
---

# Hello Skill

Greet the user named "$ARGUMENTS" warmly and ask how you can help them today.

$ARGUMENTS 会捕获用户在 skill 名后面输入的文本。本地测试不用安装，直接用 --plugin-dir 加载：

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

# 会话里试一下（注意命名空间前缀）
/my-first-plugin:hello Alex

# 改完文件后热重载，不用重启
/reload-plugins

自建插件市场，分发给团队

要让别人能 /plugin install，你需要一个 marketplace.json。它放在仓库根目录的 .claude-plugin/marketplace.json：

{
  "name": "company-tools",
  "owner": {
    "name": "DevTools Team",
    "email": "devtools@example.com"
  },
  "plugins": [
    {
      "name": "code-formatter",
      "source": "./plugins/formatter",
      "description": "Automatic code formatting on save",
      "version": "2.1.0"
    },
    {
      "name": "deployment-tools",
      "source": { "source": "github", "repo": "company/deploy-plugin" },
      "description": "Deployment automation tools"
    }
  ]
}

必填字段只有三个：name（kebab-case，用户安装时会看到）、owner、plugins 数组。每个插件条目至少要 name 和 source。source 支持多种类型：

写完先验证，再本地测试，最后推到 GitHub：

# 校验 JSON 语法、重复插件名、路径穿越等问题
claude plugin validate .

# 本地添加测试
/plugin marketplace add ./my-marketplace
/plugin install code-formatter@company-tools

# 推到 GitHub 后，别人这样加
/plugin marketplace add your-org/claude-plugins

让团队成员自动装上

把市场声明写进项目的 .claude/settings.json，团队成员信任该项目目录时就会被提示安装，还能指定哪些插件默认启用：

{
  "extraKnownMarketplaces": {
    "company-tools": {
      "source": { "source": "github", "repo": "your-org/claude-plugins" }
    }
  },
  "enabledPlugins": {
    "code-formatter@company-tools": true,
    "deployment-tools@company-tools": true
  }
}

企业侧还有更硬的管控手段：管理员可以在托管设置里用 strictKnownMarketplaces 限制只能添加白名单里的市场（空数组 [] 表示完全锁死），个人和项目配置无法覆盖。

版本管理：一个反直觉的坑

还有一个容易忽略的点：插件安装时会被复制到 ~/.claude/plugins/cache 缓存目录，所以插件里不能用 ../shared-utils 这种指向自身目录之外的路径，那些文件根本不会被复制过去。在 hooks 和 MCP 配置里引用插件内文件要用 ${CLAUDE_PLUGIN_ROOT} 变量。

插件体系真正的价值不在于「多装几个工具」，而在于把团队里那些散落的最佳实践——代码审查的检查清单、部署前的校验钩子、内部 API 的 MCP 封装——变成可版本化、可一键安装的资产。这一步跨过去，AI 编程才从个人技巧变成团队生产力。想系统学会用 Claude Code 这类工具把想法落成能交付的产品，欢迎来 IMAI 看看我们的实战课程。