插件

模块编号： 11 · 难度： 高级 · 预计时间： 1.5 小时

前面我们学了 Skills（技能）和 MCP（外接工具），它们都是在 Claude Code 内部发挥作用的扩展方式。Plugins（插件）则更进一步——它是一种可以独立打包、分发、安装的完整扩展系统。你可以把它理解为给 Claude Code 装"App"。

插件 vs Skills vs MCP

先理清三者的区别，避免混淆：

特性	Skills	MCP	Plugins
本质	一段提示词 + 配置	外部数据服务	完整的功能包
分发	手动拷贝文件	配置命令/JSON	可打包安装
能力	指导 Claude 如何做事	给 Claude 接通实时数据	可包含 Skills + MCP + 钩子 + 自定义工具
适合场景	编码规范、审查标准	数据库/API 连接	完整的工作流方案

一句话总结：插件是 Skills、MCP、Hooks 的集大成者，可以把一整套工具链打包在一起。

插件文件结构

一个插件的核心就是 .claude-plugin/plugin.json 这个清单文件。没有它，Claude 不会认这个目录是插件。

text

my-awesome-plugin/
├── .claude-plugin/
│   └── plugin.json      # 必须有，插件的"身份证"
├── .claude/
│   ├── agents/          # 插件自带的子智能体
│   ├── skills/          # 插件自带的技能
│   └── settings.json    # 插件自带的钩子等配置
├── src/                 # 插件的源码（如果有自定义工具的话）
└── README.md

plugin.json 清单详解

清单文件定义了插件的名称、版本、能力范围等基础信息：

json

{
  "name": "my-awesome-plugin",
  "version": "1.0.0",
  "description": "一个帮你自动写测试的插件",
  "userConfig": {
    "testFramework": {
      "type": "string",
      "description": "使用的测试框架",
      "default": "vitest",
      "enum": ["vitest", "jest", "mocha"]
    }
  }
}

userConfig — 让用户自己选配置

userConfig 字段很有意思。它允许插件声明一些可配置项，用户安装后可以在设置里调整。Claude 会在加载插件时自动读取用户选的值，不需要插件作者去操心配置管理的代码。

插件专属环境变量

插件内部的 Skills、Agents 和 Hooks 可以使用几个特殊的环境变量：

${CLAUDE_PLUGIN_ROOT}：指向插件自身的根目录。用来引用插件自带的脚本、模板等资源文件。
${CLAUDE_PLUGIN_DATA}：指向 Claude 为这个插件单独分配的数据存储目录。适合存缓存、SQLite 数据库等需要持久化的东西。

这意味着插件可以有自己的"私人空间"，不用担心跟其他插件或用户数据冲突。

LSP 支持

插件可以声明 Language Server Protocol (LSP) 集成。如果你的插件涉及特定编程语言的智能感知，可以在清单中配置 LSP 服务器，让 Claude 获得更精确的代码理解能力。

这对于做特定语言工具链的插件来说非常有价值——Claude 不仅能看代码文本，还能理解类型关系和引用链。

安装和管理插件

本地加载

开发或测试时，用 --plugin-dir 参数指定本地插件目录：

bash

claude --plugin-dir ./my-awesome-plugin

在会话中管理

在 Claude Code 会话里，你可以用这些命令管理插件：

/plugins：查看当前已加载的所有插件
/plugin install <source>：安装一个新插件
/reload-plugins：重新加载所有插件（修改插件代码后用这个刷新）

分发方式

目前插件的分发还在发展中。主要方式包括：

Git 仓库：把插件代码推到 GitHub，别人 clone 后用 --plugin-dir 加载
团队共享：放在公司内部的包管理器或共享目录里
插件市场：Anthropic 正在建设官方的插件市场（类似 VS Code 的扩展商店）

企业管控

在企业环境中，安全团队可能不希望开发者随意安装第三方插件。Claude Code 提供了集中管控机制：

managed-plugins.json：管理员可以维护一份插件白名单，只有白名单内的插件才允许被安装和使用
强制安装：管理员也可以给全团队统一推送必装的插件（比如公司内部的代码规范检查插件）

这和 MCP 的 managed-mcp.json 思路是一样的——在不限制生产力的前提下守住安全底线。

动手试一试

Terminal

▌

模板区

1. 基础插件清单模板

一个最小可用的 plugin.json，带有用户可配置项：

json

{
  "name": "code-quality-checker",
  "version": "1.0.0",
  "description": "自动执行代码质量检查，集成 lint 和类型检查",
  "userConfig": {
    "lintCommand": {
      "type": "string",
      "description": "Lint 检查命令",
      "default": "npx eslint ."
    },
    "autoFix": {
      "type": "boolean",
      "description": "是否自动修复可修复的问题",
      "default": true
    }
  }
}

2. 完整插件目录结构模板

一个包含 Skills + Agents + Hooks 的完整插件骨架：

text

my-quality-plugin/
├── .claude-plugin/
│   └── plugin.json
├── .claude/
│   ├── agents/
│   │   └── quality-reviewer.md    # 专属代码审查智能体
│   ├── skills/
│   │   └── lint-fix/
│   │       └── SKILL.md           # Lint 修复技能
│   └── settings.json              # PostToolUse 自动格式化钩子
├── scripts/
│   └── check-quality.sh           # 自定义检查脚本
└── README.md

这个结构展示了插件如何把 Skills、Agents 和 Hooks 组合在一起，形成一套完整的代码质量检查方案。安装这一个插件，就等于同时获得了审查智能体、自动修复技能和格式化钩子。

测验

📝

测验时间

第 1/3 题

一个 Claude Code 插件至少需要哪个文件才能被识别？

← 工作流 · 返回模块列表 →

插件 ​

插件 vs Skills vs MCP ​

插件文件结构 ​

plugin.json 清单详解 ​

userConfig — 让用户自己选配置 ​

插件专属环境变量 ​

LSP 支持 ​

安装和管理插件 ​

本地加载 ​

在会话中管理 ​

分发方式 ​

企业管控 ​

动手试一试 ​

模板区 ​

1. 基础插件清单模板 ​

2. 完整插件目录结构模板 ​

测验 ​