09-Plugins 上篇：安装、使用与社区生态 —— 一键安装全家桶

Plugins 上篇：安装、使用与社区生态 —— 一键安装全家桶

前面我们分别学了 Skills（工作流）、MCP（工具接入）、Hooks（事件自动化）。但实际项目中，这三者往往是配套使用的。Plugin 就是把它们打包成一个"全家桶"——一条命令，全套配置到位。

Plugin 是什么：不是新概念，是打包器

一句话定义

Plugin = Skills + MCP Server + Hooks + Agents 的打包发布单元 单独用： → 手动装 Skill、手动配 MCP、手动写 Hook → 三个东西的配置散落在不同文件里 → 换一台机器要重来一遍 打包成 Plugin： → 一条命令：claude plugin install my-plugin → Skills、MCP、Hooks 全部就位 → 换机器：装好 Claude Code，运行同一个命令就行

Plugin 最小结构

my-plugin/ ├── plugin.json # Plugin 的"身份证"——名字、版本、作者、依赖 ├── skills/ # Skill 文件（和独立 Skill 的结构完全一样） │ ├── code-review/ │ │ ├── metadata.yml │ │ ├── SKILL.md │ │ └── references/ │ └── deploy/ │ ├── metadata.yml │ └── SKILL.md ├── hooks/ # Hook 脚本 │ ├── pre-commit-check.sh │ └── session-start.sh ├── .mcp.json # Plugin 自带的 MCP Server 配置 └── README.md # Plugin 说明文档

plugin.json 详解

{"name":"@company/coding-toolkit","version":"1.2.0","description":"公司统一编码工具箱：代码审查 + 安全扫描 + 部署流程","author":"platform-team","license":"MIT","keywords":["code-review","deploy","security"],"claude_code":{"min_version":"2.0.0","skills":["skills/code-review","skills/deploy"],"hooks":["hooks/pre-commit-check.sh"],"mcp":".mcp.json"},"dependencies":{"plugins":[],"mcp_servers":["github"]}}

从 Marketplace 安装：完整生命周期

浏览

# 在终端搜索claude plugin search code-review# 返回结果示例# @anthropic/code-review ⭐ 2.3K v1.5.0 标准化代码审查# @community/security-pack ⭐ 1.8K v2.1.0 安全检查全家桶# @team/deploy-toolkit ⭐ 892 v1.0.0 一键部署流程

查看详情

claude plugin info @anthropic/code-review# 返回：# - 版本历史# - 包含的 Skill 列表# - 依赖的 MCP Server# - 安装量# - 最近更新时间

安装

# 安装到用户级（所有项目生效）claude plugininstall@anthropic/code-review# 安装到项目级（只当前项目生效）claude plugininstall@anthropic/code-review--project# 安装后自动生效，不需要重启 Claude Code

验证

# 查看已安装的 Pluginclaude plugin list# 输出：# @anthropic/code-review v1.5.0 [user] 代码审查# @company/coding-toolkit v1.2.0 [project] 公司编码工具箱

更新

# 检查所有 Plugin 是否有更新claude plugin outdated# 更新特定 Pluginclaude plugin update @anthropic/code-review# 更新全部claude plugin update--all

卸载

claude plugin uninstall @anthropic/code-review# 注意：卸载不会删除 Plugin 产生的数据，只移除功能

社区热门 Plugin 实测

以下 5 个 Plugin 是社区中使用最广泛的，每个都经过实际项目验证。

1. @anthropic/code-review

定位：官方出品的代码审查 Plugin 安装：claude plugin install @anthropic/code-review 包含内容： ├── code-review Skill（按 🔴🟡🟢 分级审查） ├── security-scan Skill（12 类安全问题检查） └── PreToolUse Hook（编辑后自动提示审查） 实测效果： 安装前：PR Review 平均漏掉 3-4 个问题 安装后：漏掉的问题降至 1 个以下 额外收益：团队 Code Review 标准统一，不再有"谁的标准更严"的争议 推荐指数：⭐⭐⭐⭐⭐（必装） 适用场景：任何需要 Code Review 的团队

2. @community/security-pack

定位：安全检查全家桶 安装：claude plugin install @community/security-pack 包含内容： ├── security-scan Skill（SQL 注入/XSS/CSRF/硬编码密钥等） ├── dependency-audit Skill（检查依赖的已知漏洞） ├── secret-detector Skill（检测代码中的 API Key/Token 泄露） └── PreToolUse Hook（编辑前检查是否有危险操作） 实测效果： 安装前：有两次线上事故是因为密钥被提交到 GitHub 安装后：secret-detector 在提交前就拦截了敏感信息 额外收益：依赖审计自动发现 3 个高危 CVE 推荐指数：⭐⭐⭐⭐⭐（必装） 适用场景：任何生产级项目

3. @anthropic/deploy

定位：标准化部署流程 安装：claude plugin install @anthropic/deploy 包含内容： ├── deploy Skill（构建 → 测试 → 部署 → 验证 → 回滚） ├── PostToolUse Hook（部署后自动健康检查） └── 依赖 GitHub MCP（自动创建 Release） 实测效果： 安装前：部署步骤靠"老员工的肌肉记忆" 安装后：新人也敢独立部署，因为 Skill 里写了完整 checklist 部署事故率：从月均 2 次 → 季度 1 次 推荐指数：⭐⭐⭐⭐ 适用场景：有高频部署需求的团队

4. @community/api-blueprint

定位：API 设计与文档生成 安装：claude plugin install @community/api-blueprint 包含内容： ├── api-design Skill（检查 API 命名、版本、错误码规范） ├── api-doc-gen Skill（自动生成 OpenAPI 文档） └── 不需要额外 MCP Server 实测效果： 安装前：6 个微服务的 API 风格各不一样 安装后：所有新增 API 自动统一格式 文档覆盖率：30% → 90%+ 推荐指数：⭐⭐⭐⭐ 适用场景：微服务架构、对外提供 API 的团队

5. @community/onboarding

定位：新人上手自动化 安装：claude plugin install @community/onboarding 包含内容： ├── onboarding Skill（分析项目结构 → 生成入门指南） └── 不依赖其他 Plugin 实测效果： 安装前：新人平均 2-3 天才能跑通项目 安装后：30 分钟内能跑通，半天开始写第一个 Feature 额外收益：生成的指南随项目演进自动更新 推荐指数：⭐⭐⭐⭐ 适用场景：频繁有新人加入的团队

Plugin 的加载与优先级

三级 Plugin 体系

全局 Plugin（~/.claude/plugins/） │ ├── 用户级（~/.claude/plugins/） │ 安装时指定 --user，所有项目共享 │ 例：code-review、security-pack 这种通用 Plugin │ └── 项目级（.claude/plugins/） 安装时指定 --project，只当前项目生效 例：公司内部的 deploy-toolkit、api-blueprint 优先级： 项目级 Plugin > 用户级 Plugin > 全局 Plugin 项目级会覆盖用户级和全局级的同名配置。 但不同名的配置会合并，不会互相覆盖。

覆盖规则详解

假设你同时装了： 用户级：@anthropic/code-review v1.5.0 → SKILL.md 里的 Checklist 有 5 项 项目级：@company/code-review v2.0.0（同名但不同源） → SKILL.md 里的 Checklist 有 8 项 结果： Claude Code 使用项目级的 @company/code-review（8 项 Checklist） 用户级的 @anthropic/code-review 被覆盖（不生效） 如果是不同名的 Plugin： 用户级：@anthropic/code-review 项目级：@company/deploy-toolkit → 两个都生效，各自加载各自的 Skills

实际推荐配置

# 用户级——通用工具，每个项目都要用claude plugininstall@anthropic/code-review--userclaude plugininstall@community/security-pack--userclaude plugininstall@community/onboarding--user# 项目级——项目专用claude plugininstall@company/my-project-toolkit--project

Plugin 的故障排查

Plugin 没加载

# 检查 Plugin 是否已安装claude plugin list# 检查 Plugin 的结构是否完整claude plugin validate @anthropic/code-review# 如果报错，通常是因为 plugin.json 格式不对或缺少文件# 重新安装claude plugin uninstall @anthropic/code-review claude plugininstall@anthropic/code-review

Plugin 的 Skill 没触发

1. 确认 Plugin 的 skills/ 目录结构是否正确 skills/my-skill/ ├── metadata.yml（必须有） └── SKILL.md（必须有） 2. 检查 metadata.yml 的 trigger 配置 3. claude skill list 确认 Skill 是否在列表中 注意：Plugin 带的 Skill 会显示来源 Plugin 名称

Plugin 的 MCP Server 启动失败

# 检查 Plugin 自带的 .mcp.json 配置cat~/.claude/plugins/@anthropic/deploy/.mcp.json# 检查 MCP Server 日志claude mcp logs

Plugin 版本冲突

# 查看冲突claude plugin outdated# 如果 A Plugin 依赖 B Plugin v1.0，但你装了 B v2.0# 先检查 B v2.0 的 changelog 是否有 breaking change# 如果不兼容，锁定 B 的版本：claude plugininstallB@1.0.0--user

延伸阅读

• Claude Code Plugins 官方文档