Claude Code 小课 · 2026年8月23日

2026-08-23 · 主题:plugins & marketplaces(把配置打包分发) 为什么是今天:第 4 课讲了 hooks、第 5 课讲了斜杠命令、第 11 课讲了 MCP 配置——这些都是你一台机器上的配置。插件是把它们打成一个包、能装能卸能版本化的容器;marketplace 是分发这些包的目录。8 月的 v2.1.2xx 系列刚给插件加了「从 HTTPS zip 安装 + SHA-256 锁定」的新来源,加上 /plugin 面板现在会显示每个插件的上下文开销和「两周没用过」的清理提示,这条线终于凑齐了「安装—评估—淘汰」的闭环。官方文档:https://code.claude.com/docs/en/discover-plugins · https://code.claude.com/docs/en/plugin-marketplaces · https://code.claude.com/docs/en/plugins

四条技巧,由浅入深:先学会装和挑,再学会算账和清理,再学会把团队配置写进仓库,最后是自己发一个 marketplace。

技巧一(入门):装第一个插件,并且在装之前先看它要花多少上下文

Claude Code 第一次交互式启动时会自动添加官方 marketplace claude-plugins-official。如果因为网络或策略没加上,自己补一条:

/plugin marketplace add anthropics/claude-plugins-official

装一个插件(以官方 GitHub 集成为例):

/plugin install github@claude-plugins-official

关键动作:别直接回车装。 运行 /plugin → Discover 标签页 → 选中插件按 Enter 进详情页,先看三行:

Context cost:这个插件每一轮会往你上下文里加多少 token。这是最容易被忽略的长期成本。
Last updated:上次更新日期,判断是不是弃坑项目。
Will install:它到底装了什么——commands / agents / skills / hooks / MCP servers / LSP servers 一条条列出来。

本地或自建 marketplace 的插件可能没有 Context cost 与 Last updated 这两行,Will install 会显示「Components will be discovered at installation」——这种情况就只能自己去看仓库。

装完看安装摘要:显示 Plugin is now active. 就已经生效;显示 Run /reload-plugins to activate. 就手动跑一次:

/reload-plugins

如果它警告「reload 会让 prompt cache 失效」,确认后用 /reload-plugins --force。

⚠️ 安全前提:插件能以你的用户权限执行任意代码。官方原话是「Anthropic 不控制插件里包含什么 MCP server、文件或软件,也无法验证它们是否按预期工作」。只装你信任来源的插件。

顺手推荐两类高性价比的官方插件:

code intelligence(LSP):typescript-lsp / pyright-lsp / rust-analyzer-lsp 等。装完后 Claude 每次改完文件会自动拿到语言服务器的诊断(类型错误、缺失 import),同一轮就能自己修;还能跳定义、找引用、查调用链,比 grep 精确得多。注意:语言服务器二进制要你自己装(如 pyright-langserver),插件不会替你装;/plugin 的 Errors 标签页里出现 Executable not found in $PATH 就是这个原因。
security-guidance:Claude 每改一处代码就顺手做一次常见漏洞审查,并在同一会话里让它自己修。

技巧二(进阶):把插件当成有持有成本的资产——定期清理

插件的成本不是一次性的,是每一轮对话都要付的上下文税。Claude Code 现在会替你记账:

/plugin → Installed 标签页,底部有一个 Not used recently 分组,收录「你自己装的、至少 10 个会话跨度内、超过两周没用过」的 marketplace 插件;每个插件的详情页还有一行 Last used。

不列入该分组的两类:组织托管或 --plugin-dir 加载的插件;以及贡献 theme / output style / monitor / workflow 的插件(它们不靠「被调用」产生价值,无从统计)。LSP 插件只要其语言服务器在会话里给过诊断或响应过导航请求,就算「被用过」。

在 Installed 里的操作:按 f 收藏/取消收藏,直接打字按名称或描述过滤,Enter 进详情页启用/禁用/卸载。列表默认把有加载错误或依赖未解决的插件排在最前。

不想进面板就用命令:

/plugin list --enabled          # 只看启用的
/plugin list --disabled
/plugin disable github@claude-plugins-official   # 先禁用观察,别急着卸
/plugin enable  github@claude-plugins-official
/plugin uninstall github@claude-plugins-official

注意 plugin-name 用的是 marketplace 条目里的 name,可能和插件自己 plugin.json 里的 name 不同(v2.1.195 起两个名字都认)。另外 /plugin disable|enable|uninstall 会顺手把插件面板打开并停留,输入下一条命令前先按 Esc 关掉;要写脚本就用不开面板的 claude plugin ... shell 命令。

一条实用的成本直觉:提供 MCP server 的插件,如果它的工具没有被 tool search 延迟加载,reload 时代价更高——改动会让 prompt cache 失效,下一次请求要重读整段对话。所以「MCP 类插件 + 关掉 tool search」是最贵的组合(正好呼应今天深度文档的主题)。

技巧三(团队):把 marketplace 写进仓库,新人 clone 完就有

个人装插件解决的是你自己的问题;团队要的是「所有人配置一致」。做法是在项目的 .claude/settings.json 里声明 extraKnownMarketplaces:

{
  "extraKnownMarketplaces": {
    "my-team-tools": {
      "source": {
        "source": "github",
        "repo": "your-org/claude-plugins"
      }
    }
  },
  "enabledPlugins": {
    "commit-commands@my-team-tools": true
  }
}

团队成员信任该仓库目录后,Claude Code 会自动添加这些 marketplace,不再二次询问。

三个必须知道的坑:

添加 marketplace ≠ 自动装插件。 自 v2.1.195 起,只由项目 .claude/settings.json 启用、且来自外部来源(GitHub 仓库、npm 包)的插件不会自动加载,Claude Code 会报告「未安装」并给出要跑的 claude plugin install 命令。想要真正零手动,考虑用 managed settings 的 managed scope。
安装作用域要选对:user(你自己所有项目)、project(写进 .claude/settings.json,全体协作者)、local(只你自己、只这个仓库)。CLI 里用 --scope 指定:

shell claude plugin install formatter@your-org --scope project

自动更新的默认值不同:claude-plugins-official 等官方 marketplace 默认开启自动更新;第三方与本地开发 marketplace 默认关闭。管理员可以在 extraKnownMarketplaces 每个条目上加 "autoUpdate": true。自动更新在会话启动后、随机延迟至多十分钟触发,当前会话继续用启动时加载的版本,更新完会提示你 /reload-plugins。

想「关掉 Claude Code 自身自动更新、但保留插件自动更新」:

bash export DISABLE_AUTOUPDATER=1 export FORCE_AUTOUPDATE_PLUGINS=1

企业侧还可以用 strictKnownMarketplaces / 托管 marketplace 限制来锁定允许添加的 marketplace 范围——插件能跑任意代码,这个开关在受管环境里基本是必开项。

技巧四(发布):开一个自己的 marketplace,四种来源任选

marketplace 本质上就是一个含 .claude-plugin/marketplace.json 的目录。添加方式有四种,依次对应「越来越不依赖 Git」的场景:

# 1) GitHub owner/repo 简写
/plugin marketplace add anthropics/claude-code

# 2) 任意 Git 仓库 URL(GitLab / Bitbucket / 自建),可用 # 指定分支或 tag
/plugin marketplace add https://gitlab.com/company/plugins.git#v1.0.0
/plugin marketplace add git@gitlab.com:company/plugins.git

# 3) 本地路径(自己开发插件时最常用)
/plugin marketplace add ./my-marketplace
/plugin marketplace add ./path/to/marketplace.json

# 4) 远程托管的 marketplace.json
/plugin marketplace add https://example.com/marketplace.json

URL 后缀的规则很容易踩:

github.com / gitlab.com:带不带 .git 都识别为仓库并 clone(gitlab.com 不带后缀需 v2.1.232+)。
Azure DevOps:不要加 .git,路径含 /_git/ 即被识别;加了反而 clone 失败。
其它所有 host(含自建 GitLab):必须带 .git,否则会被当成「直链一个托管的 marketplace.json」。像 AWS CodeCommit 这种 clone URL 不带后缀的,改用 extraKnownMarketplaces 里的 git 条目。
一律带上 https:// 前缀。v2.1.196+ 会直接拒绝 gitlab.com/company/plugins.git 这种写法并提示你补前缀。

日常维护三条:

/plugin marketplace list
/plugin marketplace update my-team-tools     # 拉最新目录
/plugin marketplace remove my-team-tools     # ⚠️ 会连带卸载从它装的所有插件

/plugin marketplace 可简写为 /plugin market,remove 可简写为 rm。

想让别人用得放心,参考社区 marketplace anthropics/claude-plugins-community 的做法:通过 Anthropic 自动化校验与安全筛查,目录里每个插件都固定到具体 commit SHA。自己发布时同样建议锁 SHA 或 tag,不要让用户跟着你的 main 漂。

/plugin marketplace add anthropics/claude-plugins-community
/plugin install <plugin-name>@claude-community

排障速查:插件里的 skills 不出现 → rm -rf ~/.claude/plugins/cache,重启 Claude Code,重装插件。/plugin 命令不存在 → claude --version 看版本,npm install -g @anthropic-ai/claude-code@latest 或 brew upgrade claude-code 后重启终端。

一句话总结

插件把「hooks + 斜杠命令 + skills + MCP server」打成可分发、可版本化、可计价的包;marketplace 是它的分发通道。装之前看 Context cost,装之后定期看 Not used recently,团队用 extraKnownMarketplaces 写进仓库,对外发布就锁 commit SHA。

参考