Plugins（插件）

把 skills/agents/hooks/MCP/LSP/monitors 等自定义能力打包成可版本化、可跨项目复用、可通过 marketplace 分发的扩展单元。

你的真实配置

你启用了 15 个插件，全部来自一个市场 claude-plugins-official（semgrep 关着）。按"它给你带来什么能力"分组：

插件给的东西	你启用的插件
MCP server	`context7`、`figma`、`playwright`、`serena`、`chrome-devtools-mcp`
Subagent	`pr-review-toolkit`（code-reviewer / silent-failure-hunter / …）、`code-simplifier`
Skill	`superpowers`、`code-review`、`commit-commands`、`frontend-design`、`claude-md-management`、`skill-creator`、`ralph-loop`
LSP server	`typescript-lsp`（给你前端 TS 实时代码智能）
Hooks	`superpowers`、`ralph-loop`（它们自带 hooks，已在跑）

一个插件可以同时给多种能力。比如 serena 给的是 MCP server，pr-review-toolkit 给的是一组 subagent，superpowers 同时给 skills + hooks。这就是插件相对"散装放 .claude/"的价值：打包、版本化、一键启用。

去真实体验

想验证什么	这样做
看已装/已启用插件、开关	输入 `/plugin`
看插件来自哪个市场	`/plugin marketplace`（你的是 `claude-plugins-official`）
改了本地插件后热重载	`/reload-plugins`（重载 skills/agents/hooks/MCP/LSP，不用重启）
插件技能的命令名	带命名空间，如 `/code-review`、`/commit`、`/superpowers:brainstorming`
本地开发一个插件	`claude --plugin-dir ./my-plugin`

真实案例：把你的项目规范打包成插件

你现在的约定散在 4 层 AGENTS.md + CLAUDE.md（root / docs / kj-frontend / SpringBlade）。如果想让整个团队一键拿到同样的：SpringBlade 端口速查、/lian-tiao 联调技能、pr-review-toolkit 配置、前端样式分层规则——可以打成一个内部插件：

kj-conventions/
├── .claude-plugin/plugin.json     # { "name": "kj-conventions", "version": "1.0.0" }
├── skills/lian-tiao/SKILL.md       # 联调自检技能
├── agents/springblade-reviewer.md  # 专审 R<T>/Tenant-Id/鉴权 的 subagent
└── hooks/hooks.json                # 拦 git push main、保护 AGENTS.md

团队成员 claude --plugin-dir ./kj-conventions 或装进私有市场即可——比让每个人手抄 CLAUDE.md 强。

注意：插件里的 skill 命令名强制带前缀（/kj-conventions:lian-tiao）；.claude-plugin/ 目录里只放 plugin.json，skills/ agents/ hooks/ 都放插件根级（常见错误）。

官方文档要点

以下为按官方文档整理的系统性参考。

是什么

Plugin 是 Claude Code 的扩展打包机制：一个目录里放一个 .claude-plugin/plugin.json manifest，加上 skills/、agents/、hooks/、.mcp.json、.lsp.json、monitors/、bin/、settings.json 等组件目录/文件。相对于直接放在 .claude/ 的 standalone 配置，plugin 的核心区别是：可分享给团队/社区、可版本化更新、可跨多个项目复用、通过 marketplace 安装；代价是 skill 名称被强制加上命名空间前缀（如 /my-plugin:hello）。官方文档把 standalone（.claude/，skill 名形如 /hello）与 plugin（.claude-plugin/plugin.json，skill 名形如 /plugin-name:hello）作为两种并列方式对照。

怎么工作

每个 plugin 是独立目录，目录里必须有 .claude-plugin/plugin.json manifest，Claude Code 读取其中 metadata 在 plugin manager 中展示
skills 放在 plugin 根的 skills/ 下，每个 skill 是一个文件夹含 SKILL.md；文件夹名即 skill 名，并自动加上 plugin 的 name 作为命名空间前缀，例如 plugin 名 my-first-plugin 下的 hello/ 变成 /my-first-plugin:hello
命名空间是强制的，用来避免多个 plugin 有同名 skill 时冲突；改前缀只能改 plugin.json 的 name 字段
SKILL.md 是 YAML frontmatter + 指令正文；frontmatter 里的 description 决定 Claude 何时自动调用该 skill（model-invoked）；$ARGUMENTS 占位符捕获 skill 名后面用户输入的文本
开发期用 claude --plugin-dir ./my-plugin 直接加载本地 plugin，不需要安装；改动后用 /reload-plugins 热加载（会重载 plugins/skills/agents/hooks/plugin MCP servers/plugin LSP servers），无需重启
当 --plugin-dir 加载的本地 plugin 与已安装的 marketplace plugin 同名时，本会话以本地副本为准（被 managed settings 强制启停的 plugin 除外）
hooks 放在 hooks/hooks.json，格式与 .claude/settings.json 里的 hooks 对象相同；命令通过 stdin 接收 JSON 形式的 hook input（用 jq 提取字段如 file_path）
LSP server 通过根目录 .lsp.json 配置（command/args/extensionToLanguage），给 Claude 实时代码智能；用户机器上必须装有对应 language server 二进制
background monitors 在 monitors/monitors.json 配置；plugin 激活时 Claude Code 自动启动每个 monitor，command 的每行 stdout 作为 notification 推给 Claude
bin/ 里的可执行文件在 plugin 启用期间会被加进 Bash 工具的 PATH
plugin 根的 settings.json 在 plugin 启用时应用默认设置，目前仅支持 agent 和 subagentStatusLine 两个 key；agent 可把 plugin 自带的某个 custom agent 设为主线程（套用其 system prompt/工具限制/model）
版本控制：设了 version 时用户只在你 bump 该字段后才收到更新；省略且经 git 分发时用 commit SHA，每次 commit 都算新版本

怎么配置 / 用法

manifest 路径固定为 <plugin>/.claude-plugin/plugin.json，最小示例：

json

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

组件目录全部放 plugin 根（不是 .claude-plugin/ 里面）：skills/<name>/SKILL.md、commands/（旧式扁平 md，新 plugin 用 skills/）、agents/、hooks/hooks.json、.mcp.json、.lsp.json、monitors/monitors.json、bin/、settings.json。 SKILL.md frontmatter 示例：description:（决定何时调用）、disable-model-invocation: true（禁止模型自动触发）；正文里用 $ARGUMENTS 接收输入。本地测试：claude --plugin-dir ./my-plugin（可重复多次加载多个；也接受 .zip，需 v2.1.128+）；远程 zip：claude --plugin-url https://example.com/my-plugin.zip（可重复或空格分隔）。 marketplace：/plugin marketplace add anthropics/claude-plugins-community 添加社区市场，安装用 /plugin install；提交前本地跑 claude plugin validate。

什么时候用

用 plugin：要分享给团队/社区、跨多个项目复用、需要版本化和便捷更新、要通过 marketplace 分发、能接受命名空间化的 skill 名（如 /my-plugin:hello）
用 standalone（.claude/）：只为单个项目定制、个人配置不需分享、在打包前快速试验 skill/hook、想要短 skill 名（如 /hello、/deploy）
官方建议：先在 .claude/ 里快速迭代，准备好分享时再转成 plugin
自定义 LSP plugin 仅在需要支持官方 marketplace 尚未覆盖的语言时才做；TypeScript/Python/Rust 等常见语言直接装官方预建 LSP plugin

限制 / 坑

常见错误：不要把 commands/、agents/、skills/、hooks/ 放进 .claude-plugin/ 目录——.claude-plugin/ 里只能放 plugin.json，其余目录都必须在 plugin 根级
plugin 的 skill 名称永远是命名空间化的，无法去掉前缀，只能通过改 name 字段换前缀
settings.json 目前只支持 agent 和 subagentStatusLine 两个 key，未知 key 被静默忽略
settings.json 的设置优先级高于 plugin.json 里声明的 settings
--plugin-dir 接受 .zip 需要 Claude Code v2.1.128 或更高版本
--plugin-dir 无法覆盖被 managed settings 强制启用/禁用的 plugin
--plugin-url 在启动时拉取归档，仅当前会话有效；拉取失败或归档无效则报 plugin load error 并不带它启动；只应指向你信任/掌控的归档
LSP plugin 要求用户本机已安装对应 language server 二进制，否则不可用
提交社区市场后，公开 catalog 每晚（nightly）从审核管线同步，审核通过到出现在 marketplace.json 之间存在延迟
提交表单只进入社区市场审核，不会加入 official marketplace；official marketplace 由 Anthropic 自行决定收录，无申请流程
若看不到 /plugin 命令，需把 Claude Code 升级到最新版本

硬事实速查（27 条）

manifest 固定路径：.claude-plugin/plugin.json
plugin.json 字段：name（唯一标识 + skill 命名空间）、description（plugin manager 中展示）、version（可选，控制更新）、author（可选，如 {"name": "Your Name"}）；更多字段如 homepage/repository/license 见 plugins-reference
skill 命名规则：skills/<folder>/SKILL.md，名称变为 /<plugin-name>:<folder>，如 /my-first-plugin:hello
SKILL.md frontmatter 字段示例：description、disable-model-invocation: true
skill 参数占位符：$ARGUMENTS
plugin 根目录组件清单：.claude-plugin/（仅放 plugin.json）、skills/、commands/、agents/、hooks/、.mcp.json、.lsp.json、monitors/、bin/、settings.json
commands/ = 扁平 Markdown 文件形式的 skill；新 plugin 应改用 skills/
hooks/hooks.json 格式与 .claude/settings.json 的 hooks 对象相同；hook command 通过 stdin 收 JSON
.lsp.json 字段：每语言 key 下 command、args、extensionToLanguage（如 {".go": "go"}）；示例 command gopls args ["serve"]
monitors/monitors.json 是数组，条目字段含 name、command、description；还有 when 触发器和变量替换（见 reference）
settings.json 支持的 key：agent、subagentStatusLine
bin/ 中可执行文件在 plugin 启用时加入 Bash 工具 PATH
本地加载命令：claude --plugin-dir ./my-first-plugin，可重复指定多次
--plugin-dir 接受 .zip 需 Claude Code v2.1.128+
远程加载命令：claude --plugin-url https://example.com/my-plugin.zip，可重复或空格分隔多 URL
热重载命令：/reload-plugins（重载 plugins/skills/agents/hooks/plugin MCP servers/plugin LSP servers）
查看 agent：/agents；查看 skill 列表：/help
官方两个公共 marketplace：claude-plugins-official（Anthropic 策展，每个安装自带）、claude-community（社区，第三方审核后落地）
添加社区市场命令：/plugin marketplace add anthropics/claude-plugins-community，从中安装记作 @claude-community
安装命令：/plugin install
本地校验命令：claude plugin validate（提交前跑，审核管线也跑同样检查）
社区提交表单：Claude.ai claude.ai/settings/plugins/submit、Console platform.claude.com/plugins/submit
审核通过的 plugin 在 anthropics/claude-plugins-community catalog 中被 pin 到特定 commit SHA，CI 随新 commit 自动 bump pin
社区 catalog 路径：anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json，每晚同步
迁移对照：.claude/commands/ → plugin-name/commands/；settings.json 中 hooks → hooks/hooks.json
standalone skill 名 /hello vs plugin skill 名 /plugin-name:hello
Skills-directory plugins：往 skill 文件夹放 .claude-plugin/plugin.json，即作为 <name>@skills-dir plugin 加载（可顺带打包 agents/hooks/MCP），无需 marketplace/install；项目 .claude/skills/ 下需先过 workspace trust。

官方出处：https://code.claude.com/docs/en/plugins

Plugins（插件） ​

你的真实配置 ​

去真实体验 ​

真实案例：把你的项目规范打包成插件 ​

官方文档要点 ​

是什么 ​

怎么工作 ​

怎么配置 / 用法 ​

什么时候用 ​

限制 / 坑 ​

硬事实速查（27 条） ​