Claude Code 插件从装到写,后缀坑和五步打包法

Claude Code 插件从装到写,后缀坑和五步打包法

先把一条命令放在这,你现在就可以开个终端照着敲。

/plugin install github@claude-plugins-official

装完敲一句 /reload-plugins 激活,不用重启。这两行是新手装第一个 Claude Code 插件的最短路径,装好的 github 插件预先配好了连 GitHub 的 MCP 服务器,Claude 从此能直接读 issue、看 PR,省掉你手动接服务的整个下午。

为什么这条命令能一步到位。@claude-plugins-official 是 Anthropic 官方策展的插件目录,每次启动自动就绪,不用手动添加。这是整篇唯一一条可以无脑照抄的命令,后面的每一步都有坑,老雷一个一个给你标出来。

插件是一个打包好的能力箱

你刚装的 github 不是一个按钮,也不是一段提示词,是一个打包好的能力包。一个插件里可以同时塞进六类能力,Skill 是模型按任务自动调用的能力,Slash Command 是斜杠触发的命令入口,Subagent 是带独立上下文的子 Agent,Hook 是事件发生时自动跑的脚本,MCP 服务器是接外部服务的桥,LSP 是给代码补类型检查的语言服务。

装一个插件,等于把这一组配合好的能力一次拿齐。github 插件给的是 MCP 服务器,官方的 commit-commands 给的是提交、推送、建 PR 一组斜杠命令,pr-review-toolkit 给的是几个专门审 PR 的子 Agent。能力组合、开箱即配,这是插件比单个 Skill 更值的地方。

官方目录里现成的东西不少,新手不必造轮子。最实用的一类是 LSP 语言服务插件,改完代码立刻看到类型错、漏掉的导入,还能跳转定义、找引用,相当于给 Claude 配了一副能看见错误的眼镜,TypeScript、Python、Rust、Go 等 11 种语言各一个插件,名字像 typescript-lsp、pyright-lsp,前提是你机器上装了对应的语言服务程序。第二类是外部集成,github、gitlab、notion、figma、slack、linear、vercel、sentry 这些,全是预配好 MCP 服务器的,免手动连接。剩下还有安全审查的 security-guidance,开发流程的 pr-review-toolkit,写插件用的 plugin-dev,基于 Agent SDK 开发的 agent-sdk-dev,按需取用。

它和你直接丢在项目 .claude/ 目录里的标准配置有什么区别。官方的分法很清楚,标准配置适合个人、单项目、快速试验,技能名很短,像 /hello。插件是带清单文件的独立目录,适合跨项目复用、分享给团队、做版本管理,技能名带命名空间,像 /插件名:hello。自己一个项目随手用,标准配置就够,要分发、要复用、要标版本,才上插件。

@ 后缀是栽人最多的地方

安装命令的完整结构是 /plugin install 插件名@目录注册名。坑在 @ 后面这一截,它必须和添加目录时生成的注册名严格对上,对不上就报「插件未找到」,而注册名常常不等于你敲的仓库地址。

官方三个公开目录放一起看就明白了。官方策展那个内置无需添加,后缀写 @claude-plugins-official。社区目录添加时敲的是 anthropics/claude-plugins-community,安装后缀却是 @claude-community。演示目录添加时敲的是 anthropics/claude-code,后缀反而是 @claude-code-plugins。仓库名不等于注册名,凭直觉照搬仓库地址几乎一定错。拿不准就先敲 /plugin marketplace list,它会列出所有已注册目录的真实名字,照着抄比猜靠谱。

目录的来源也不止 GitHub 仓库一种,官方支持五种写法,owner/repo 简写、完整 Git 地址(GitLab 和自建都行)、地址后面加 #tag 锁定分支或版本、本地路径、远程 marketplace.json 地址。要锁版本用第二种加 # 的写法,公司内网自建目录用本地路径或自建 Git 地址,团队私有插件的分发就靠这个。

从演示目录完整装一个 commit-commands,四步长这样。

/plugin marketplace add anthropics/claude-code

/plugin install commit-commands@claude-code-plugins

/reload-plugins

/commit-commands:commit

注意第二步,添加时敲的是仓库名,安装后缀写的是注册名。最后一步调用要带命名空间前缀,这个冒号前缀是官方为防止不同插件同名技能打架强制加的,新手最容易漏。装好的 commit-commands 会帮你暂存改动、生成提交信息、建好这次提交。不想敲命令的话,直接敲 /plugin 打开图形管理器,四个标签用 Tab 切换,Discover 浏览安装,Installed 管理已装,Marketplaces 管目录,Errors 看报错。

App 界面风格插画,安装命令特写中 @ 后缀高亮警示,旁边两块标签对比仓库名与注册名,一勾一叉

装之前看三样,装完查三样

装之前在 Discover 的详情页看三样。一是 Will install 清单,它逐项列出这个插件会带来哪些命令、子 Agent、技能、Hook,接哪些 MCP 和 LSP 服务,看完才知道装进来的到底是什么。二是 Context cost 估算,它每轮对话占多少 token,装多了上下文被挤占。三是 Last updated,判断它还在不在维护。详情页里还能选安装范围,User 只给自己跨所有项目,Project 写进仓库配置给所有协作者,Local 只在本仓库给自己,团队协作这一步要选对。

装完别假设它一定生效,花十秒查三样。看 /reload-plugins 的回执,它会报重新加载了多少插件、技能、Agent、Hook、MCP 服务器,数字对不上预期就是哪里没加载进来。用 /help 看技能有没有列在对应命名空间下,用 /agents 看子 Agent 出现没有。去 Errors 标签看报错,最常见的是 LSP 插件提示 Executable not found in $PATH,意思是你还没装对应的语言服务程序,比如 Python 的 pyright-langserver,按提示装上就好。

顺手说一句,/reload-plugins 不是零成本,它会让下一次请求重读一遍对话历史,带 MCP 服务器的插件尤其明显,别为每个小改动都刷一次,攒着一起更划算。

App 截图风格插画,插件详情页分两栏,左栏能力清单上下文开销更新日期三张卡片,右栏加载回执计数与报错标签,机器人逐项打钩

它能以你的权限跑任意代码

这段不吓人,只摆事实。官方文档说得很直白,插件和目录是高度可信组件,能以你的用户权限在你机器上执行任意代码,安全完全取决于来源,和你随手 npm install 一个包是同一种风险。插件里的 Hook 能跑任意 shell 命令,能调 MCP 接外部服务,一个来路不明的插件完全可能在你不知情时读文件、发网络请求。

老雷给大家提个醒,装任何插件前固定看三件事。看用途,它做的事和你的真实需求对得上吗。看它带什么,Will install 清单里的命令、Hook、MCP 你都认得吗。看来源,官方策展最稳,社区目录过了自动校验和安全筛查,第三方和来路不明的最谨慎。

第一次装外部插件,别直接上核心仓库,先找个低风险目录试跑,观察它有没有改你没预期的文件、有没有调外部服务。按风险分三档安排节奏,检查类只读轻量,适合先试,出错也没大损失。执行类会改文件跑命令,先给小范围任务,稳定几次再进重要项目。集成类接外部服务和凭据,必须看清要哪些凭据、数据流向哪。组织层面还能用受管设置限制成员只能添加哪些目录,把口子收在制度上。插件不能绕过你的确认,涉及删除、发布、付款这些动作它仍然该停下来问你,插件是能力,不是免审通行证。

五步打包你自己的插件

会装之后,自己打一个其实不难,官方快速上手就是五步。

第一步建目录,mkdir my-first-plugin。第二步加清单文件,在 my-first-plugin/.claude-plugin/plugin.json 里写清 name、description、version、author 四个字段。这里有个最高频的结构错误,.claude-plugin/ 里只放 plugin.json 这一个文件,skills、commands、agents、hooks 全部放插件根目录,放错位置加载不到。

第三步加一个技能,放根目录的 skills/hello/SKILL.md,整个结构长这样。

my-first-plugin/

├── .claude-plugin/

│ └── plugin.json

├── skills/

│ └── hello/SKILL.md

├── commands/

├── agents/

└── hooks/hooks.json

第四步本地测试,不用先发布,claude --plugin-dir ./my-first-plugin 直接加载,启动后敲 /my-first-plugin:hello 调用,改了内容跑 /reload-plugins 刷新。第五步分享,推到 GitHub 配一个 marketplace.json,别人用 /plugin marketplace add 你的仓库就能装上。

如果你已经在某个项目的 .claude/ 里攒了一堆技能和 Hook,迁移几乎就是搬文件,commands、agents、skills 复制到插件根目录对应位置,Hook 从 settings.json 的 hooks 对象原样搬进插件的 hooks/hooks.json,格式一样。老雷自己就是从散装配置搬过来的,一个下午搬完,从此换项目不用再背一遍配置。

插件最适合沉淀已经被反复验证过的流程,天天还在变的做法,先别急着打包。

装多了要会往回退。代价有三样,每个插件的描述都进上下文占 token,可用入口太多模型选起来分散,代码面越大潜在风险越高。几条命令配着用,/plugin disable 停用不卸载,/plugin enable 重新启用,/plugin uninstall 彻底卸载,/plugin marketplace remove 移除整个目录并连带卸载它装过的插件。老雷的习惯是一个月看一次 Installed 列表,还在用的留,想不起用途的停用,功能重复的合并,来源不清的删。

说到底,插件是复用成熟工作流,不是替代基础能力。什么时候该从标准配置升级成插件,给你一个简单的判断,同一段技能或 Hook 被你复制到第三个项目的时候。第一次用是试验,第二次是顺手,第三次就是信号,说明它已经是你的稳定工作流,值得打包、命名、标版本,让它跟着你走遍所有项目。

今晚先把官方目录翻一遍,挑一个检查类的小插件装上跑跑,十秒钟的事,你会马上知道这东西该不该进你的工作流。这个生态长得很快,我自己也还在挑挑拣拣,值得每两个月回来看一眼。

App 风格插画,屏幕里一条五工位装配流水线依次组装目录、清单、技能、测试与发布,机器人逐站操作,末端亮起已发布徽章