Claude Code 插件体系完全指南：6种组件类型、安装方法与实战避坑

Claude Code 的插件系统在 v2.1.x 系列更新中逐渐成熟，从最初"终端里的AI补全工具"演变成一个可扩展平台。本文基于官方文档整理，覆盖插件的完整组件结构、安装命令和常见问题，帮你少走弯路。

插件到底是什么？

官方的定义很干净：一个插件就是一个自包含的目录，里面可以包含技能（Skills）、Agent、钩子（Hooks）、MCP 服务器、LSP 服务器和后台监控（Monitors）中的一种或多种。

安装后，插件会被缓存到 ~/.claude/plugins/cache/，每个版本是独立目录，旧版本会在更新后 7 天自动清理。这个设计意味着你不能在插件内用相对路径引用外部文件，所有路径必须相对于插件根目录并以 ./ 开头。

6种组件类型详解

1. Skills（技能）

Skills 是最常见的组件，本质是一个 Markdown 文件，描述 Claude 在特定场景下应该做什么。安装后会生成 /名称 的斜杠命令，Claude 也可以根据上下文自动调用。

目录结构：

skills/
  commit-message/
    SKILL.md       ← 技能描述文件
  code-review/
    SKILL.md

如果插件根目录直接放了一个 SKILL.md（没有 skills/ 子目录），Claude Code v2.1.142+ 会自动将整个插件识别为单技能插件，不需要额外配置。

2. Agents（子代理）

Agents 是专用子代理，适合处理固定流程的复杂任务。它们出现在 /agents 界面，Claude 可以自动调用，也可以手动触发。

Agent 的 Markdown 文件支持 frontmatter 配置：

---
name: security-reviewer
description: 审查代码中的安全问题
model: claude-opus-4
effort: high
maxTurns: 20
---

注意：出于安全考虑，插件提供的 Agent 不支持 hooks、mcpServers 和 permissionMode 字段，这些只能在用户级别配置。

3. Hooks（事件钩子）

Hooks 是插件里最强大也最需要谨慎使用的组件，允许在 Claude Code 的各个生命周期事件上注入逻辑。

完整事件列表：

Hook 支持四种执行方式：command（执行 shell 脚本）、http（发送 POST 请求）、mcp_tool（调用 MCP 工具）、prompt（触发 LLM 推理）。

4. MCP Servers

MCP（Model Context Protocol）是 Anthropic 主导的开放协议，让 Claude Code 连接外部服务。配置写在插件根目录的 .mcp.json 文件中，插件启用后 MCP 服务器自动启动，无需手动配置。

支持的外部集成包括：GitHub、GitLab、Jira、Slack、Sentry、Vercel、Firebase 等。

MCP 和普通插件的核心区别在于：MCP 服务器是客户端无关的，同一个 MCP Server 可以同时服务 Claude Code、Cursor、Windsurf 等多个工具。

5. LSP Servers（语言服务器）

LSP 集成让 Claude Code 在编辑代码时获得实时语义分析能力：跳转定义、查找引用、悬停类型信息、即时错误诊断。

官方提供了三个现成的 LSP 插件：

6. Monitors（后台监控）

Monitors 是实验性功能（需要 v2.1.105+），允许插件注册持续运行的后台进程。每一行 stdout 输出都会作为通知传给 Claude，让它能主动响应日志变化、部署状态或轮询事件，而不需要你每次手动询问。

配置在 monitors/monitors.json 中，需要用 experimental.monitors 字段声明（直接放顶层也能用，但会有 deprecation 警告）。

安装与管理：CLI 命令速查

# 浏览可用插件
/plugin Discover

# 安装插件（默认 user 作用域，对所有项目生效）
claude plugin install pyright-lsp@claude-plugins-official

# 安装到项目作用域（写入 .claude/settings.json，可以 git 提交共享给团队）
claude plugin install security-guidance --scope project

# 列出已安装插件
claude plugin list

# 查看插件详情（包含 token 消耗估算）
claude plugin details pyright-lsp

# 更新插件
claude plugin update pyright-lsp

# 卸载并清理依赖
claude plugin uninstall myPlugin --prune

# 验证插件 manifest
claude plugin validate

三种作用域的区别：

插件目录结构参考

一个完整插件的标准布局：

my-plugin/
├── .claude-plugin/
│   └── plugin.json        ← 元数据（可选，但推荐）
├── skills/
│   └── my-skill/
│       └── SKILL.md
├── agents/
│   └── reviewer.md
├── hooks/
│   └── hooks.json
├── .mcp.json              ← MCP 服务器配置
├── .lsp.json              ← LSP 服务器配置
├── monitors/
│   └── monitors.json
└── bin/                   ← 可执行文件，自动加入 PATH

plugin.json 中只有 name 字段是必填的，其他都可以省略：

{
  "name": "my-plugin",
  "displayName": "My Plugin",
  "version": "1.0.0",
  "description": "插件功能说明",
  "author": { "name": "你的名字" }
}

常见问题排查

插件加载了但技能不出现 组件目录放错位置了——skills/、agents/、hooks/ 必须在插件根目录，不能放在 .claude-plugin/ 里面。只有 plugin.json 属于 .claude-plugin/。

Hooks 不触发 两个最常见原因：脚本没有可执行权限（运行 chmod +x script.sh），或者事件名大小写写错（是 PostToolUse，不是 postToolUse）。

LSP 报"Executable not found in $PATH" 需要先在系统里安装对应的语言服务器二进制文件，例如 npm install -g typescript-language-server typescript，Claude Code 本身不会自动安装依赖。

MCP 服务器启动失败 用 claude --debug 启动，可以看到详细的初始化日志。最常见原因是配置里用了绝对路径——所有路径必须用 ${CLAUDE_PLUGIN_ROOT} 变量替代。

安全提醒

插件本质上包含可执行脚本，具有文件系统访问权限。生产环境务必优先使用官方目录的插件；社区插件在安装前先阅读源码，特别关注 hooks/ 和 bin/ 目录下的脚本内容。

插件安装后会被缓存到本地，${CLAUDE_PLUGIN_ROOT} 路径在插件更新后会变化，运行 /reload-plugins 可以让 Hooks 和 MCP 服务器切换到新路径；Monitors 需要重启会话才能更新。

相关链接

• Claude Code 插件官方文档
• anthropics/claude-code GitHub 仓库