Logo Vincent
返回文章列表

Claude Code /plugin 详解：给你的 AI 编程助手装插件

Claude
Claude Code /plugin 详解：给你的 AI 编程助手装插件

为什么需要 /plugin

Claude Code 自带 40+ 工具和 80+ 命令，已经很强了。但每个团队、每个项目的需求不同——有人想加一个一键部署的命令，有人想接入内部的 MCP 服务，有人想让 Claude 在每次提交前自动跑检查。

靠内置功能满足所有人是不现实的。所以 Claude Code 做了一套插件系统，让你自己扩展它的能力。

/plugin 就是管理这些插件的入口。

/plugin 是什么

/plugin 是 Claude Code 的插件管理命令（别名 /plugins、/marketplace）。它提供一个交互式界面，让你浏览、安装、启用、禁用和管理插件。

输入：

/plugin

会弹出插件管理界面，显示已安装的插件列表和可用的 Marketplace。

插件能做什么

一个插件可以包含以下任意组合：

组件说明举例
Commands自定义斜杠命令/build、/deploy
SkillsAI 技能（SKILL.md 格式）代码审查技能、测试生成技能
AgentsAI 子代理专门跑测试的 Agent
Hooks生命周期钩子提交前自动 lint
MCP ServersMCP 协议服务器连接数据库、内部 API
LSP Servers语言服务协议自定义语言支持
Output Styles终端输出样式自定义主题

简单说，插件是给 Claude Code 加功能的标准化方式。

插件的结构

一个典型的插件目录长这样：

my-plugin/
├── plugin.json          # 插件清单（元数据 + 组件声明）
├── commands/            # 自定义命令
│   ├── build.md
│   └── deploy.md
├── skills/              # AI 技能
│   └── code-review/
│       └── SKILL.md
├── agents/              # AI 代理
│   └── test-runner.md
├── hooks/               # 生命周期钩子
│   └── hooks.json
├── .mcp.json            # MCP 服务器配置
└── data/                # 持久化数据目录

核心是 plugin.json，它声明了插件的所有元数据和组件：

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "A custom plugin for my team",
  "author": {
    "name": "Your Name"
  },
  "commands": "./commands",
  "skills": "./skills",
  "agents": "./agents",
  "hooks": "./hooks/hooks.json",
  "mcpServers": {
    "my-db": {
      "command": "npx",
      "args": ["my-mcp-server"]
    }
  }
}

安装和管理

交互式管理

/plugin

进入图形界面，可以直接操作插件的安装、启用和禁用。

命令行管理

更适合脚本和自动化：

# 安装插件
claude plugin install my-plugin@github:owner/repo

# 卸载
claude plugin uninstall my-plugin@github:owner/repo

# 启用 / 禁用
claude plugin enable my-plugin@github:owner/repo
claude plugin disable my-plugin@github:owner/repo

# 更新
claude plugin update my-plugin@github:owner/repo

# 查看已安装
claude plugin list
claude plugin list --json        # JSON 格式输出
claude plugin list --available   # 显示可安装的插件

# 验证插件清单
claude plugin validate ./path/to/plugin.json

三种安装范围

范围配置位置影响谁
user~/.claude/settings.json你的所有项目
project.claude/settings.json这个仓库的所有协作者
local.claude/settings.local.json只有你、只有这个仓库副本

通过 --scope 参数指定：

claude plugin install my-plugin@marketplace --scope project

默认范围是 user。

Marketplace

Marketplace 是插件的来源。你可以添加多个 Marketplace：

# 添加 GitHub 仓库作为 Marketplace
claude plugin marketplace add github:owner/plugin-repo

# 查看已添加的 Marketplace
claude plugin marketplace list

# 更新 Marketplace 缓存
claude plugin marketplace update

# 移除
claude plugin marketplace remove marketplace-name

Marketplace 支持多种来源：

  • GitHub 仓库：github:owner/repo
  • Git URL：任意 Git 仓库
  • URL：直接指向 marketplace.json 的链接
  • 本地目录：开发调试用

插件标识符

每个插件的唯一标识是 name@marketplace，例如：

  • my-tool@github:owner/repo — 来自 GitHub Marketplace
  • dev-util@builtin — 内置插件
  • test-plugin@inline — 会话级插件（通过 --plugin-dir 加载）

内置插件

Claude Code 自带一些内置插件，标识为 @builtin。它们和第三方插件一样可以启用或禁用，但不需要安装——直接随 CLI 发布。

在 /plugin 界面中，内置插件会显示在单独的 “Built-in” 区域。

插件的环境变量

插件内的命令、Hook 和 MCP 配置可以使用以下变量：

变量值用途
${CLAUDE_PLUGIN_ROOT}插件安装路径引用插件内的文件
${CLAUDE_PLUGIN_DATA}~/.claude/plugins/data/<id>/持久化数据目录
${CLAUDE_SKILL_DIR}技能子目录路径技能内部使用
${CLAUDE_SESSION_ID}当前会话 ID跨工具关联
${user_config.KEY}用户配置的值动态参数

${CLAUDE_PLUGIN_DATA} 目录在插件更新后依然保留，适合存放用户数据。

用户配置

插件可以声明用户需要填写的配置项：

{
  "userConfig": {
    "API_KEY": {
      "type": "secret",
      "description": "Your API key for the service",
      "sensitive": true
    },
    "BUILD_FLAGS": {
      "type": "string",
      "description": "Extra build flags",
      "default": "--production"
    }
  }
}

安装插件后，Claude Code 会提示用户填写这些配置。敏感字段（如 API Key）不会出现在命令内容中。

/reload-plugins

修改了插件配置后，不需要重启 Claude Code。直接：

/reload-plugins

它会：

  1. 清空插件缓存
  2. 重新加载所有插件
  3. 报告加载结果：插件数、技能数、Agent 数、Hook 数、MCP/LSP 服务器数
  4. 如果有加载错误，会明确提示

插件 Hook 系统

插件可以注册 Hook 来监听 Claude Code 的生命周期事件。支持的事件包括：

  • SessionStart / SessionEnd — 会话开始和结束
  • PreToolUse / PostToolUse — 工具调用前后
  • UserPromptSubmit — 用户提交消息时
  • PreCompact / PostCompact — 上下文压缩前后
  • Stop — Claude 停止响应时

Hook 配置示例：

{
  "PreToolUse": [
    {
      "matcher": "Bash",
      "hooks": [
        {
          "name": "lint-before-bash",
          "command": "echo 'Running pre-check...'"
        }
      ]
    }
  ]
}

错误排查

插件加载失败？用 /doctor 命令可以看到所有插件错误的详细信息。

常见错误类型：

  • plugin-not-found — Marketplace 中找不到该插件
  • manifest-parse-error — plugin.json 格式错误
  • dependency-unsatisfied — 依赖的其他插件未启用
  • mcp-config-invalid — MCP 服务器配置错误

实际使用场景

场景 1：团队共享命令

你的团队有一套标准的部署流程。把它封装成插件，放到 .claude/settings.json（project 范围），所有人 clone 仓库后就自动拥有 /deploy 命令。

场景 2：接入内部工具

公司有一个内部 MCP 服务器，连接着数据库和监控系统。通过插件声明 MCP 配置，团队成员安装后就能让 Claude 直接查询生产数据。

场景 3：自定义代码检查

写一个 Hook 插件，在每次 Claude 修改文件后自动运行你的 lint 和 type-check。发现问题立即反馈，不用等到提交时才发现。

场景 4：开发调试

开发自己的插件时，用 --plugin-dir 参数临时加载本地目录：

claude --plugin-dir ./my-local-plugin

调试完成后再发布到 Marketplace。

写在最后

/plugin 把 Claude Code 从一个”固定功能的工具”变成了一个可扩展的平台。

你不再受限于 Claude Code 内置了什么——如果缺少某个功能，自己写一个插件就行。而且通过 Marketplace 和安装范围机制，插件可以在团队间轻松共享。

好的工具不是什么都做，而是让你能做任何事。

更多同类文章

© 2026 vincentqiao.com . 保留所有权利。