插件到底是个啥?装完一次,我把它的底裤都扒了

装完一个插件,我盯着终端发呆了三秒:它到底干了啥?为什么我的 skills 目录里没有它,却冒出来个 plugins 目录?今天就把这层窗户纸捅破。

📦 本文主题:Claude Code 插件体系

资源	地址
📖 官方文档	https://code.claude.com/docs/en/plugins
📖 插件参考	https://code.claude.com/docs/en/plugins-reference

一、先破一个迷思:插件 ≠ skill

故事从一次安装说起。我用官方命令装了个测试插件(这里就叫它"我的测试插件"):

/plugin install my-test-plugin

跑完,我以为它会被丢进 ~/.claude/skills/,跟我那一堆 skill 做邻居。结果翻目录——skills 里根本没有它,它落在 ~/.claude/plugins/ 下面。

这是第一个关键认知:插件住的地方跟 skill 不一样,它俩不是一回事。

我去挖了这个插件的"说明书"(.claude-plugin/plugin.json),看到这段铁证:

{  "skills": "./skills/",          // 它确实带了一批 skill  "agents": ["./agents/runner.md"],   // 还带了 agent  "hooks": {    "SessionStart": [{ "command": "bash .../check-version.sh" }]  // 还能挂 hook  }  // 外加 settings.json 里的 permissions 权限白名单}

看明白没?这份说明书里 skills 只是其中一个字段。它还塞了 agent、hook、权限白名单。

一句话:skill 是插件的一个组成部分。 装一个插件,通常会顺带装进一堆 skill;但装一个 skill,就只是装一个 skill。当然,skill 也能完全独立存在(自己躺在 ~/.claude/skills/ 里),不一定非得依附于某个插件——只是插件把多个 skill 连同 agent、hook 一起打包了而已。

二、skill 和插件到底是啥关系?

如果你已经写过 skill(在 .claude/skills/xxx/SKILL.md 里写一段"何时触发+怎么做"的说明书),那理解插件就很简单了:

插件 = skill + agent + hook + 权限白名单的打包集合。

skill 是你已经熟悉的最小单位。插件做的,就是把你写好的若干个 skill,再配上能自主干活的 agent、到点自动触发的 hook、调用命令时免询问的权限,一起打成一个可分发、可版本管理的包。

打个比方:skill 是"一把锤子",插件是"连锤子带工具箱带说明书带门禁卡"的整套装备包。你可以只买锤子,也可以直接包一套。

这里还藏着一个更小的概念叫 agent(子智能体),它是"能自主多步干活的子任务"。插件里经常带一两个 agent,让它去串联调用多个 skill 完成一摊大活。对入门来说,你只要知道"agent 比 skill 大、能自主调度 skill"就够了,先不深究。

三、什么时候该用插件?

先说个很多人没意识到的结论:skill 也能共享。 它本质就是一个目录加一个 SKILL.md,丢进 git 仓库让人 clone 到自己的 .claude/skills/ 就能用,技术上行得通,很多人也正是这么干的。

那官方为啥还要搞个插件?——因为上面说的是"一个 skill"的情况。一旦你的 skill 从一个变成一批,土办法就开始疼了。我把它分成三档来判断:

单个 skill、自己用
→ 直接放 ~/.claude/skills/ 或项目的 .claude/skills/,技能名还短,叫 /hello。别上插件,过度设计。
一两个 skill、想给同事用
→ 丢 git/npm 让人 copy 也行,这是土办法,能用。
一批 skill(还可能带 agent、hook)、要版本管理、要一键装/升级、要防命名冲突、要上插件市场
→ 这时候 plugin 才真正发挥价值。

重点掰扯第三档,也就是 plugin 相比"土法共享 skill"多出来的东西:

打包一批能力,一次装到位。
这是最实在的特性。一个 plugin 的 skills/ 下能放一整批 SKILL.md,装一次插件 = 一组 skill 同时到位,不用你一个一个让人装。
带 manifest,能版本管理。
plugin 有 plugin.json 声明版本,你 bump 版本号、用户一条命令升级,清楚明白。土办法 copy skill 没有版本概念,更新了只能再喊一遍"大家重新拉一下"。
命名空间防冲突。
plugin 里的 skill 自动带前缀 /plugin-name:skill-name,多个插件有同名 skill 也不打架。裸 skill 共名就会互相覆盖。
顺带 agent / hook / 权限。
前面说了 plugin 能连带这些一起装——这意味着你分发的不是一堆散装 skill,而是一整套能直接跑起来的能力,这是纯 skill 做不到的。
走 marketplace 分发。
官方有插件市场,/plugin install 一条命令装,还有官方/社区两个市场可选。

举个具体场景。你写了个 lint-fix skill 只自己用,丢 ~/.claude/skills/lint-fix/ 就完事。但如果你维护的是一整套测试能力——init、gen-case、run、diag、fix 五六个 skill 还加一个调度它们的 agent——这时候再让同事一个个 copy 就太蠢了。打包成 plugin,大家一条命令把这堆能力全装上,还能锁版本、能升级,才划算。

所以判断标准不是"要不要给别人用",而是"能力是不是成体系、要不要持续维护分发"。 官方原话也是这个意思:先在 .claude/ 里快速试,等要分享了、成体系了,再升级成 plugin。

四、插件怎么装?装完到底干了啥?

回到那条 /plugin install 命令。它在我电脑的 ~/.claude/plugins/ 下落了三层东西:

~/.claude/plugins/├── marketplaces/xxx-plugins/      ① 市场:整个插件仓库(带 .git,可更新)│   └── plugins/xxx/               插件源码本体├── cache/xxx-plugins/.../1.2.8/   ② 缓存:当前在用版本的快照│   ├── .claude-plugin/plugin.json   ★ 元数据│   ├── skills/   一批 SKILL.md│   ├── agents/   子 agent 定义│   └── settings.json   权限白名单└── installed_plugins.json         ③ 登记表:记录这个插件已装

翻译一下这三层:① 是"从哪拉的"(插件市场仓库,带 git 能更新),② 是"现在用的哪一版"(版本快照),③ 是"装了没"(一张登记表,Claude Code 靠它知道哪些插件存在)。

装插件时如果碰到报 command not found,先别慌。有些 installer 会同时往多个 AI 编程工具注册,你电脑里没装的那个工具报错很正常,不影响你真正在用的 Claude Code。

五、插件怎么"活"起来:运行原理

这是最反直觉的一点:

插件本身不运行,它被运行。

它没有进程、不常驻、不后台跑。它是「一堆声明 + 资源文件」,真正干活的执行者是 Claude Code 引擎自己。原理分四步:

① 安装(一次性):落盘 + 写登记表,没有任何东西在跑,只是文件就位。

② 引擎启动(每次开 CC):引擎启动时扫一遍 installed_plugins.json 这张登记表,读每个插件的 plugin.json,把它声明的东西——skill、agent、hook、权限——注册进自己的运行时。换句话说,插件的能力本质上变成了引擎自己能力的一部分。登记表里每个插件都有 installPath(装哪了)和 version(哪个版本),这就是引擎"知道它存在"的依据。

③ hook 触发:这是插件唯一"会自己动"的地方。我的测试插件在 SessionStart(每次开 CC)时自动跑检查脚本查更新——但这也不是插件自己跑,是引擎在固定的生命周期点替它执行。插件可以往"用工具前""会话开始"等事件上挂命令,引擎就替它在那个点执行。

④ 真正干活:你下个指令,引擎按 agent 的剧本派生子 agent,子 agent 再接力调一个个 skill。具体说,你敲一句"帮我跑一轮接口测试",引擎看到这个插件里的 runner agent 匹配这个任务,就派一个子 agent 出去。子 agent 自己读那一批 skill 的说明书,一步步走:初始化→分析场景→生成用例→执行→出报告。"被运行"这四个字落到这里就是——agent 和 skill 都是引擎在调度,插件只是把剧本递过去。

画张流转图:

[安装]  落盘 + 登记表(无进程)   ↓[启动]  引擎读 plugin.json → 注册 skills/agents/hooks/permissions   ↓[钩子]  SessionStart → 引擎替它跑检查脚本(被动)   ↓[干活]  你下指令 → 引擎派 agent → agent 调 skill 接力执行 → 产出

官方文档里还提到,插件能装的东西远不止 skill——还有斜杠命令、MCP 工具、代码智能配置等更多组件,具体可以翻官方文档。所以你看,skill 只是插件最常被拉开的那层抽屉。

插件是"剧本+演员+道具"的打包,引擎是"剧院+导演"。
演出只有引擎在场时才发生。

六、一句话带走

插件不运行,它被运行;skill 是零件,插件是整台机器。装插件就是把一整套成体系的能力「打包、版本化、分发」,而不是让你一个一个 skill 去拼。下次装插件,记得翻一眼 ~/.claude/plugins/——底裤都在那儿。

💬 聊聊:你装过最香的 CC 插件是哪个?有没有哪个让你"原来还能这么玩"的瞬间? 评论区蹲一个。

☕ AI茶馆.蚁慕

不追热点,不鼓吹 all in,只把 AI 用人话讲透。

AI 是工具,不是焦虑的来源。

坐下,喝茶,慢慢聊。