23. 插件 plugins

插件解决什么问题

前面几章你学了技能（Skill）、子代理（Subagent）、钩子（Hook）、MCP 服务器。这些都能放在 .claude/ 目录里用。但有个问题：你在 A 项目调好一套部署技能、审查代理、格式化钩子，想在 B 项目也用，得手动复制一堆文件。想分享给团队，更麻烦—每个人都要照着配一遍。

插件（Plugin）就是把这一堆东西打包成一个自包含的目录，一次安装到处用，还能版本化、更新、回滚。

打个比方：.claude/ 里的配置像你手写的菜谱，自己用挺好，给别人得抄一份。插件像盒装调料包—配好的、有包装有保质期，谁要用拆一盒就行。

插件可以包含：

• 技能（Skill）：可复用的指令和命令
• 子代理（Agent）：专门化的 AI 助手
• 钩子（Hook）：事件自动化
• MCP 服务器：外部工具集成
• LSP 服务器：代码智能（跳转定义、查引用、类型检查）
• 后台监视器（Monitor）：监视日志文件变化并通知 Claude
• 默认设置：启用插件时应用的配置

插件 vs 独立配置

Claude Code 有两种方式加自定义扩展：

方式	命令形式	适合
独立（.claude/）	/hello	个人工作流、单项目、快速实验
插件（.claude-plugin/）	/plugin-name:hello	团队共享、跨项目、版本化发布

用独立配置的情况：

• 只在单个项目自定义
• 配置是个人的，不用共享
• 打包前先实验迭代
• 想要短命令名，如 /hello、/deploy

用插件的情况：

• 要和团队或社区共享
• 多个项目复用相同的 skills/agents
• 想要版本控制和轻松更新
• 通过市场分发
• 能接受命名空间命令（/my-plugin:hello 这种）

插件的最小结构

一个插件就是一个目录，核心是 .claude-plugin/plugin.json 清单：

my-plugin/
├── .claude-plugin/
│   └── plugin.json     # 插件清单（必需）
├── skills/             # 技能
├── agents/             # 子代理
├── hooks/              # 钩子
├── .mcp.json           # MCP 配置
├── .lsp.json           # LSP 配置
└── monitors/           # 后台监视器

写插件清单 plugin.json

plugin.json 是插件的身份证，定义名称、描述、版本：

{
  "name": "my-first-plugin",
  "description": "一个用来学习基础的概念插件",
  "version": "1.0.0",
  "author": {
    "name": "你的名字"
  }
}

字段说明：

字段	作用
name	唯一标识符和技能命名空间。技能以此为前缀，如 /my-first-plugin:hello
description	插件管理器里显示的描述
version	可选。设了的话，只有更新此字段用户才收到更新。省略则用 git 提交 SHA 当版本
author	可选，归属信息

还有 homepage、repository、license 等可选字段。name 决定命令命名空间，想改前缀就改它。

创建第一个插件

走一遍完整流程，做一个带技能的插件。

第一步：建目录和清单

mkdir my-first-plugin
mkdir my-first-plugin/.claude-plugin

创建 my-first-plugin/.claude-plugin/plugin.json：

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

第二步：加技能

技能放 skills/ 目录，每个技能是一个含 SKILL.md 的文件夹。文件夹名变成技能名，加插件命名空间前缀：

mkdir -p my-first-plugin/skills/hello

创建 my-first-plugin/skills/hello/SKILL.md：

---
description: Greet the user with a friendly message
disable-model-invocation: true
---

Greet the user warmly and ask how you can help them today.

第三步：本地测试

用 --plugin-dir 标志加载插件，不用安装：

claude --plugin-dir ./my-first-plugin

启动后试技能：

/my-first-plugin:hello

Claude 会用问候语回应。/help 里能看到你的技能列在插件命名空间下。

第四步：加参数

$ARGUMENTS 占位符接收技能名后的输入。更新 SKILL.md：

---
description: Greet the user with a personalized message
---

# Hello Skill

Greet the user named "$ARGUMENTS" warmly and ask how you can help them today.

运行 /reload-plugins 拿到改动，再试：

/my-first-plugin:hello Alex

Claude 会按名字问候你。

插件能装什么

技能（Skills）

插件根目录加 skills/，里面放含 SKILL.md 的技能文件夹：

my-plugin/
├── .claude-plugin/
│   └── plugin.json
└── skills/
    └── code-review/
        └── SKILL.md

Claude 根据任务上下文自动调用，或你手动 /plugin-name:skill-name。安装后运行 /reload-plugins 加载。技能写法和独立技能一样，详见技能那章。

子代理（Agents）

agents/ 目录放 Markdown 文件定义子代理：

---
name: code-reviewer
description: 该 agent 的专长以及 Claude 何时调用它
model: sonnet
effort: medium
maxTurns: 20
disallowedTools: Write, Edit
---

详细的系统提示，描述 agent 的角色、专业知识和行为。

插件代理支持 name、description、model、effort、maxTurns、tools、disallowedTools、skills、memory、background、isolation 等字段。

代理启用后出现在 @ 提及的类型提前里，用 my-plugin:code-reviewer 这种作用域名。

钩子（Hooks）

hooks/hooks.json 放钩子配置，格式和设置文件里的 hooks 一样：

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

${CLAUDE_PLUGIN_ROOT} 是插件根目录的变量，方便引用插件内捆绑的脚本。插件钩子响应和用户钩子相同的生命周期事件，类型也一致（command、http、mcp_tool、prompt、agent）。

MCP 服务器

.mcp.json 捆绑 MCP 服务器配置：

{
  "mcpServers": {
    "plugin-database": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
      "env": {
        "DB_PATH": "${CLAUDE_PLUGIN_ROOT}/data"
      }
    }
  }
}

启用插件时自动启动，在 Claude 工具包里显示为标准 MCP 工具。

LSP 服务器

.lsp.json 提供代码智能，让 Claude 跳转定义、查引用、即时看类型错误：

{
  "go": {
    "command": "gopls",
    "args": ["serve"],
    "extensionToLanguage": {
      ".go": "go"
    }
  }
}

后台监视器（Monitors）

monitors/monitors.json 让插件在后台监视日志、文件或外部状态，事件到达时通知 Claude：

[
  {
    "name": "error-log",
    "command": "tail -F ./logs/error.log",
    "description": "Application error log"
  }
]

插件激活时自动启动每个监视器，不用你指示 Claude 启动。command 的每行 stdout 作为通知传给 Claude。

默认设置

插件根目录的 settings.json 在启用插件时应用默认配置。目前只支持 agent 和 subagentStatusLine 键。设 agent 会激活插件的自定义代理作为主线程：

{
  "agent": "security-reviewer"
}

这会让插件启用时改变 Claude Code 的默认行为方式。

本地测试和调试

开发期间用 --plugin-dir 直接加载，不用安装：

claude --plugin-dir ./my-plugin

改了插件后运行 /reload-plugins 拿到更新，不用重启。这会重载插件、技能、代理、钩子、插件 MCP 和 LSP 服务器。

测试各组件：

• 技能用 /plugin-name:skill-name 试
• 代理看 /context 里的 Custom Agents，或 @ 提及
• 钩子看是否按预期触发

插件不工作这样排查：

1. 查结构：目录在插件根，不在 .claude-plugin/ 内
2. 单独测组件：分别检查每个技能、代理、钩子
3. 用验证工具：claude plugin validate 检查插件结构

从独立配置迁移到插件

.claude/ 里已有 skills 或 hooks，想转成插件共享：

1. 建插件结构：

mkdir -p my-plugin/.claude-plugin

创建 my-plugin/.claude-plugin/plugin.json：

{
  "name": "my-plugin",
  "description": "Migrated from standalone configuration",
  "version": "1.0.0"
}

2. 复制现有文件：

cp -r .claude/commands my-plugin/
cp -r .claude/agents my-plugin/
cp -r .claude/skills my-plugin/

3. 迁移钩子。建 my-plugin/hooks/hooks.json，从 .claude/settings.json 复制 hooks 对象，格式一样。

4. 测试：

claude --plugin-dir ./my-plugin

5. 迁移后从 .claude/ 删掉原文件，避免重复。

插件市场：发现和安装

市场（Marketplace）是插件目录，帮你发现和安装别人做好的插件。两步：先添加市场（注册目录），再单独安装插件。像加应用商店—加了能浏览，但要单独选应用下载。

官方市场

官方 Anthropic 市场（claude-plugins-official）启动 Claude Code 时自动可用。运行 /plugin 进「发现」选项卡浏览，或在 claude.com/plugins 看目录。

安装：

/plugin install github@claude-plugins-official

找不到插件时刷新市场：

/plugin marketplace update claude-plugins-official

官方市场包含几类插件：

代码智能：启用 LSP 工具，Claude 能跳转定义、查引用、编辑后即时看类型错误。覆盖 C/C++、Go、Java、Python、Rust、TypeScript 等语言，需要机器上装对应语言服务器二进制文件。

外部集成：捆绑预配置 MCP 服务器，连 GitHub、GitLab、Jira、Linear、Notion、Figma、Vercel、Slack、Sentry 等，不用手动设 MCP。

自动安全审查：security-guidance 插件审查 Claude 每项更改的安全漏洞，并指示 Claude 在同一会话修复。

开发工作流：commit-commands（Git 提交流程）、pr-review-toolkit（PR 审查代理）、plugin-dev（创建插件的工具包）等。

输出样式：自定义 Claude 响应方式，如教学见解、交互式学习模式。

社区市场

anthropics/claude-plugins-community 托管通过 Anthropic 自动验证和安全筛选的第三方插件。需手动添加：

/plugin marketplace add anthropics/claude-plugins-community

安装：

/plugin install <plugin-name>@claude-community

插件管理器

运行 /plugin 打开选项卡式界面，用 Tab 切换：

• 发现：浏览所有市场的可用插件
• 已安装：管理已装插件
• 市场：添加、删除、更新市场
• 错误：查看插件加载错误

选插件看详情，包括上下文成本估算（每回合加多少 token）、最后更新日期、将安装的内容（命令、代理、技能、钩子、MCP/LSP 服务器）。

安装时选范围：

• 用户范围：所有项目给自己装
• 项目范围：此仓库所有协作者
• 本地范围：仅此仓库给自己

安装后

运行 /reload-plugins 激活。插件技能用插件名命名空间，比如 commit-commands 插件提供 /commit-commands:commit。

共享你的插件

插件准备好共享时：

1. 加文档：放个 README.md，写清安装和使用说明
2. 选版本策略：设显式 version，还是靠 git 提交 SHA
3. 创建或用市场：通过插件市场分发
4. 找人测试：让团队成员先试

想提交到社区市场，用应用内表单：

• claude.ai：claude.ai/admin-settings/directory/submissions/plugins/new（需 Team/Enterprise 组织）
• Console：platform.claude.com/plugins/submit（个人作者用这个）

提交前本地跑 claude plugin validate。审查管道会跑相同检查加自动安全筛选。批准的插件固定到目录的特定提交 SHA，你推新提交时 CI 自动提升固定。

几个值得装的插件

顺手推荐几个官方市场里实用的：

• commit-commands：Git 提交工作流，包括提交、推送、PR 创建
• github：GitHub 集成，操作 issue、PR
• security-guidance：自动安全审查
• skill-creator：帮你造技能（技能那章提过）
• pyright-lsp / typescript-lsp 等：对应语言的代码智能

装法都是 /plugin install <名字>@claude-plugins-official。

插件 vs 技能：再理一遍

这俩最容易混，最后说一次：

• 技能（Skill）：单个可复用的能力包，一个 SKILL.md 加支持文件。是「做什么事」的指令
• 插件（Plugin）：一个容器，把多个技能、代理、钩子、MCP、LSP 打包在一起，能版本化、分发、安装。是「一整套扩展」

技能可以独立存在于 .claude/skills/，也可以作为插件的一部分。插件是技能的超集—它能把技能和其他组件一起打包管理。

简单记：技能是零件，插件是工具箱。零件能单用，也能装进工具箱一起卖。