Claude Code 中文学习站

为什么用插件

skill、agent、hook、MCP server 这些东西,散放在 .claude/ 目录里只服务一个项目,想给队友用只能靠复制粘贴。插件(plugin)把它们打包成一个可安装、可版本化的单元:

| | 散装(.claude/ 目录) | 插件 | | --- | --- | --- | | 命令名 | /hello | /my-plugin:hello(带命名空间,防重名) | | 分发 | 手动复制文件 | /plugin install 一键装 | | 适合 | 单项目、个人实验 | 团队共享、跨项目复用、社区分发 |

一个插件可以同时带:skills、commands、agents、hooks、MCP server、LSP server。官方建议:先在 .claude/ 里散装试验,成熟了再打包成插件。

怎么装(/plugin 与官方市场)

官方市场 claude-plugins-official 在你第一次交互式启动 Claude Code 时自动注册,不用手动添加。会话内打开插件面板浏览:

> /plugin

在 Discover 里翻列表,或者直接按名字装:

> /plugin install commit-commands@claude-plugins-official

格式固定是 插件名@市场名。终端里也有等价的非交互命令,适合脚本和 CI:

claude plugin install commit-commands@claude-plugins-official

第三方市场先 add 再 install,比如官方维护的社区市场:

> /plugin marketplace add anthropics/claude-plugins-community

实战示例

示例 1:装两个官方市场的现成插件

commit-commands 是最好上手的一个——装完多出三个 git 工作流命令:

> /plugin install commit-commands@claude-plugins-official

之后 /help 里能看到 /commit(自动生成符合仓库风格的提交信息)、/commit-push-pr(提交 + 推送 + 开 PR 一条龙,需要 gh CLI)、/clean_gone(清理远端已删除的本地分支)。与别的插件重名时,用全名 /commit-commands:commit。

> /commit-push-pr

再装一个 frontend-design,它带的不是命令而是一个 skill——不用手动调用,Claude 在做前端任务时自动用上,避免"AI 味"的千篇一律界面:

> /plugin install frontend-design@claude-plugins-official
> 给音乐流媒体应用做一个 dashboard 页面

插件还能捆绑 MCP server:context7 装完就是一个查"版本对应文档"的 MCP server,进 /mcp 面板能看到它,之后问库的 API 时 Claude 会去查当前版本的文档而不是凭记忆。

示例 2:写一个最小的自己的插件

一个插件 = 一个目录 + 一个 manifest + 至少一个组件。三步搭出来:

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

manifest 写在 my-first-plugin/.claude-plugin/plugin.json:

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

name 就是命名空间前缀;version 可选——设了就只有你改这个字段时用户才收到更新,不设则走 git commit SHA、每次提交都算新版本。

skill 写在 my-first-plugin/skills/hello/SKILL.md,文件夹名 hello 成为命令名,$ARGUMENTS 接收命令后面的参数:

---
description: Greet the user with a personalized message
---
 
Greet the user named "$ARGUMENTS" warmly and ask how you can help them today.

不用发布就能测,--plugin-dir 直接加载本地目录:

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

> /my-first-plugin:hello 小黑

Claude 会按 SKILL.md 的指令带着名字打招呼。改了插件文件后不用重启,/reload-plugins 热加载。要分发时把插件推上 GitHub、写一个 marketplace.json 即可,见排错一节的 validate。

示例 3:通过 .claude/settings.json 给团队固定插件

把市场和插件写进项目的 .claude/settings.json 提交 git,队友 clone 后信任目录时会自动被提示安装,不用人肉传"你去装一下 XX":

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

extraKnownMarketplaces 声明市场从哪拉,enabledPlugins 声明装哪些、默认开启。注意这是"提示安装"不是静默安装——自 v2.1.195 起,仅由项目 settings 启用的外部插件在所有加载路径上都要用户显式同意,防止 clone 一个仓库就被塞进任意代码。

排错与更新

装了但命令没出现——先分清 enable/disable 状态:/plugin 面板里被 disable 的插件还在磁盘上,只是不加载。选中插件 → Enable 即可,不用重装。

Enable/Disable 按了没反应——老版本的坑:插件 plugin.json 里的 name 和市场条目里的 name 不一致时,开关会失灵。v2.1.195 已修复;还碰到就先升级 Claude Code。

自己写的插件加载不出组件——最常见的结构错误:skills/、commands/、agents/、hooks/ 必须放在插件根目录,.claude-plugin/ 里只放 plugin.json。发布前跑一遍校验,能查出 JSON 语法、重名、frontmatter 错误:

claude plugin validate .

市场里看不到新版本——本地市场缓存要手动刷:/plugin marketplace update。另一个反向的坑:插件设了 version 字段却忘了 bump,推了新 commit 用户也收不到更新——要么每次发版改版本号,要么干脆不设、让 commit SHA 当版本。

想深入写插件,官方市场里还有个 plugin-dev 插件,专门辅助开发插件本身。

回到示例列表 →