Home

深色模式

Claude Code 插件 ​

概述 ​

Claude Code 插件是一个自包含目录，可以把 Skills、Agents、hooks、MCP Server、LSP Server 和后台 monitor 等扩展能力一起分发。它适合跨项目复用、团队安装和版本化发布；只服务于单个仓库的临时配置，继续放在 .claude/ 中更直接。

截至 2026 年 8 月 19 日，Claude Code 已提供官方 Marketplace、社区 Marketplace、自定义 Marketplace、交互式插件管理器和非交互 CLI。安装 Marketplace 只会注册目录，具体插件仍要单独选择安装。

适用场景 ​

Standalone 配置和插件使用同一批底层能力，但面向的生命周期不同：

方式常见位置Skill 名称适用情况
Standalone.claude//review单项目配置、个人实验、快速调整
Plugin独立插件目录/plugin-name:review跨项目复用、团队共享、版本升级、公开分发

先在 .claude/skills/ 或 .claude/agents/ 中验证工作流，成熟后再包装成插件，通常比一开始就维护 manifest 和 Marketplace 更省事。

插件组件 ​

Claude Code 插件可包含以下组件：

组件路径作用
Skillsskills/<name>/SKILL.md可自动触发或手动调用的工作流
Commandscommands/*.md兼容旧插件的扁平命令，新插件优先使用 Skills
Agentsagents/*.md专门处理特定任务的 subagent
Hookshooks/hooks.json在工具调用、任务和会话事件上执行动作
MCP.mcp.json接入外部工具和服务
LSP.lsp.json提供定义跳转、引用查询和诊断能力
Monitorsmonitors/monitors.json后台监听日志、文件或外部状态
Executablesbin/插件启用时加入 Bash 工具的 PATH
Defaultssettings.json插件启用时应用支持的默认设置

插件可以只包含其中一种组件。一个稳定的代码审查 Skill 没必要顺便塞进 MCP 和 LSP；组件越多，安装说明、权限面和排错成本也越大。

目录结构 ​

典型插件结构如下：

text
quality-review/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   └── review/
│       └── SKILL.md
├── agents/
├── hooks/
│   └── hooks.json
├── monitors/
│   └── monitors.json
├── bin/
├── settings.json
├── .mcp.json
└── .lsp.json

只有 plugin.json 放在 .claude-plugin/ 中。skills/、agents/、hooks/、.mcp.json 等组件都位于插件根目录，这是最常见的结构错误。

采用默认目录时，manifest 可以省略，Claude Code 会按目录名推导插件名称并自动发现组件。准备安装、展示和分发时，仍应提供 .claude-plugin/plugin.json，明确身份和版本：

json
{
  "name": "quality-review",
  "description": "按统一标准审查代码改动",
  "version": "1.0.0",
  "author": {
    "name": "Platform Team"
  }
}

name 同时是插件标识和 Skill 命名空间。这个插件中的 review Skill 会以 /quality-review:review 暴露，命名空间避免多个插件都定义 /review 时互相覆盖。

创建插件 ​

创建一个只包含 Skill 的最小插件：

sh
mkdir -p quality-review/.claude-plugin
mkdir -p quality-review/skills/review

在 quality-review/skills/review/SKILL.md 中写入：

md
---
description: 审查当前代码改动，检查正确性、安全风险、行为回归和测试缺口。
disable-model-invocation: true
---

读取当前分支与基线分支的差异。

只报告会影响正确性、安全性或维护成本的问题，按严重程度排序。
每条问题包含文件位置、触发条件、判断依据和最小修复方向。

disable-model-invocation: true 表示只允许用户手动调用，适合有明确执行时机或成本较高的工作流。允许 Claude 根据上下文自动选择时，可以去掉该字段，并把 description 写得足够具体。

Claude Code 也能在 Skills 目录中直接初始化插件：

sh
claude plugin init quality-review

它会在 ~/.claude/skills/quality-review/ 中创建 starter plugin，下次 session 会以 quality-review@skills-dir 自动加载，不需要先配置 Marketplace。

本地调试 ​

开发阶段用 --plugin-dir 直接加载目录：

sh
claude --plugin-dir ./quality-review

进入会话后调用：

text
/quality-review:review

修改文件后运行 /reload-plugins，不必重启整个会话。该命令会重新加载 Skills、Agents、hooks、MCP 和 LSP 配置。

多个插件可以同时加载：

sh
claude \
  --plugin-dir ./quality-review \
  --plugin-dir ./release-helper

本地插件与已安装插件同名时，--plugin-dir 指定的版本在本次 session 中优先。Managed settings 强制启用或停用的插件不受这个覆盖规则影响。

发布前执行结构校验：

sh
claude plugin validate ./quality-review
claude plugin validate ./quality-review --strict

--strict 会把 warning 也当成失败，适合 CI 或正式提交前使用。加载错误可以在 /plugin 的 Errors 标签中查看，更详细的原因则通过 claude --debug 排查。

安装插件 ​

官方 Marketplace claude-plugins-official 在首次交互启动时自动注册。打开插件管理器：

text
/plugin

界面包含 Discover、Installed、Marketplaces 和 Errors 等标签。也可以直接安装插件：

text
/plugin install github@claude-plugins-official

自定义 Marketplace 分两步使用：

text
/plugin marketplace add owner/repository
/plugin install plugin-name@marketplace-name

第一条命令只下载和注册目录，不会安装目录中的全部插件。Marketplace 可以来自 GitHub shorthand、任意 Git URL、本地目录或远程 marketplace.json。

安装作用域 ​

安装插件时可以选择四种作用域：

作用域配置位置用途
user~/.claude/settings.json个人跨项目使用，默认值
project.claude/settings.json提交到仓库，供协作者安装
local.claude/settings.local.json只在当前仓库对自己生效
managedManaged settings由管理员统一控制，只读

团队项目应把 Marketplace 来源和需要启用的插件声明在 .claude/settings.json，不要要求每位成员手工复制一份插件目录。成员信任仓库后，Claude Code 会提示安装项目配置中的 Marketplace 和插件。

创建市场 ​

Marketplace 仓库在根目录使用 .claude-plugin/marketplace.json：

text
team-marketplace/
├── .claude-plugin/
│   └── marketplace.json
└── plugins/
    └── quality-review/
        ├── .claude-plugin/
        │   └── plugin.json
        └── skills/
            └── review/
                └── SKILL.md

最小 Marketplace 清单如下：

json
{
  "name": "team-tools",
  "owner": {
    "name": "Platform Team"
  },
  "plugins": [
    {
      "name": "quality-review",
      "source": "./plugins/quality-review",
      "description": "统一代码审查标准"
    }
  ]
}

本地验证流程：

sh
claude plugin validate ./team-marketplace
claude plugin marketplace add ./team-marketplace
claude plugin install quality-review@team-tools

一个 Marketplace 可以收录多个插件。更新仓库后，用户通过以下命令刷新目录：

sh
claude plugin marketplace update team-tools
claude plugin update quality-review@team-tools

删除 Marketplace 会同时卸载从该 Marketplace 安装的插件。只想拉取新版本时应执行 update，不要先删再加。

缓存与路径 ​

Marketplace 插件安装后会复制到 ~/.claude/plugins/cache，Claude Code 从缓存副本运行，而不是从 Marketplace 原目录运行。因此插件不能依赖目录外的 ../shared-utils，那些文件不会进入安装缓存。

hook 和脚本需要定位插件内部文件时，使用 ${CLAUDE_PLUGIN_ROOT}：

json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/check-format.sh"
          }
        ]
      }
    ]
  }
}

插件版本写在 plugin.json 或 Marketplace 中时，发布新内容也要更新版本。只改仓库文件、不提升固定版本，用户不会收到新包。

安全边界 ​

插件不是纯提示词。hooks 可以自动运行命令，MCP Server 可以访问外部数据，LSP 需要启动本地进程，bin/ 还会进入 Bash 工具的 PATH。安装第三方插件前应检查源码、组件清单和外部依赖。

还需要注意以下边界：

  • 插件 Agents 不能通过自身定义携带 permissionMode、hooks 或 MCP Server
  • LSP 插件不会自动安装语言服务器二进制，例如 .lsp.json 配置了 gopls，本机仍要有 gopls
  • settings.json 不是任意设置注入入口，当前只支持文档列出的少数字段
  • Marketplace 自动更新会带来代码变化，内部插件应固定版本并建立审查流程
  • 卸载或停用前先确认 hook、monitor 和外部进程是否已经结束

Claude Code 插件与 Codex 插件的名称相似，但目录规范并不兼容。前者使用 .claude-plugin/ 和 Claude Marketplace，后者使用 .codex-plugin/ 以及 ChatGPT/Codex 的插件目录和 Marketplace。

参考 ​