Claude Code 实战课

主题

3.6 Plugins 插件系统 — 把你的能力打包分享 ​

学习目标 ​

学完这节课，你将能够：

  • 理解 Plugin 是什么，以及它和 skills、agents、hooks 的关系
  • 安装和管理社区插件
  • 理解插件的目录结构和 manifest 规范
  • 从零创建一个可分享的 Plugin

什么是 Plugin ​

前面几节课我们学了不少好东西：子智能体能帮你分身、Hooks 能自动化流程、Skills 能扩展能力、Commands 能定义快捷指令。但有个问题——这些东西散落在不同的目录里，你想分享给朋友或团队，得挨个文件复制，还得告诉别人"这个放 agents 目录、那个放 hooks 里"。太麻烦了。

Plugin 就是解决这个问题的。它把 commands、agents、skills、hooks 这些组件打包成一个整体，变成一个可安装、可卸载、可启用禁用的"能力包"。就像手机上的 App——装上就能用，删掉就干净。

散装模式（手动复制文件）：
  agents/reviewer.md  →  放到 ~/.claude/agents/
  skills/review/       →  放到 ~/.claude/skills/
  hooks/hooks.json     →  合并到 settings.json
  commands/review.md   →  放到 ~/.claude/commands/

Plugin 模式（一条命令搞定）：
  claude plugin install my-review-plugin
  ✅ 全部就绪

一句话总结：Plugin = 把你的 Claude Code 能力打包成别人能一键安装的产品。

插件的目录结构 ​

一个标准的 Claude Code 插件长这样：

my-plugin/
├── .claude-plugin/
│   ├── plugin.json          # 插件清单（必须）
│   └── marketplace.json     # 市场清单（发布到市场时需要）
├── agents/                  # 子智能体定义
│   └── reviewer.md
├── skills/                  # 技能文件
│   └── review-guide/
│       └── SKILL.md
├── commands/                # 斜杠命令
│   └── review.md
├── hooks/                   # 钩子配置
│   └── hooks.json
└── README.md                # 插件说明

核心是 .claude-plugin/plugin.json，它是插件的"身份证"：

json
{
  "name": "pr-review",
  "version": "1.0.0",
  "description": "PR Review 插件 — 自动化代码审查工作流",
  "author": {
    "name": "你的名字",
    "url": "https://github.com/yourname"
  },
  "homepage": "https://github.com/yourname/pr-review-plugin",
  "repository": "https://github.com/yourname/pr-review-plugin",
  "license": "MIT",
  "keywords": ["code-review", "pr", "automation"]
}

字段都很直观：名字、版本号、描述、作者信息。keywords 帮助别人在市场里搜到你的插件。

如果你要把插件发布到市场（marketplace），还需要一个 marketplace.json：

json
{
  "name": "my-marketplace",
  "description": "我的插件市场",
  "owner": {
    "name": "你的名字",
    "url": "https://github.com/yourname"
  },
  "plugins": [
    {
      "name": "pr-review",
      "description": "自动化 PR 审查工作流",
      "version": "1.0.0",
      "source": "./"
    }
  ]
}

[截图: 一个完整的插件目录结构在文件管理器中的展示]

如何安装社区插件 ​

安装插件分两步：先添加市场源，再安装具体插件。

第一步：添加市场源 ​

市场（marketplace）是插件的来源。大多数社区插件托管在 GitHub 上，添加一个市场源就是告诉 Claude Code "去这个仓库找插件"。

bash
# 从 GitHub 仓库添加市场
claude plugin marketplace add github:tanweai/pua

# 从 URL 或本地路径添加也行
claude plugin marketplace add /path/to/local/marketplace

添加完后，可以看看有哪些市场：

bash
claude plugin marketplace list

[截图: 终端显示 marketplace list 的输出，列出几个已添加的市场源]

第二步：安装插件 ​

bash
# 从已添加的市场中安装插件
claude plugin install pua

# 如果多个市场有同名插件，用 @ 指定市场
claude plugin install pua@pua-skills

# 安装到项目级别（只对当前项目生效）
claude plugin install pua --scope project

安装完成后，重启 Claude Code 就能用了。插件带来的 skills、commands、agents 会自动注册，你可以直接使用对应的斜杠命令。

[截图: claude plugin install 命令执行成功的终端输出]

如何管理插件 ​

日常管理就这几个命令，很简单。

查看已安装的插件 ​

bash
claude plugin list

输出长这样：

Installed plugins:

  > pua@pua-skills
    Version: 2.9.0
    Scope: user
    Status: ✔ enabled

  > codex@openai-codex
    Version: 1.0.1
    Scope: user
    Status: ✔ enabled

  > claude-hud@claude-hud
    Version: 0.0.11
    Scope: user
    Status: ✘ disabled

每个插件显示了名称、版本、作用域（user/project/local）和启用状态。

启用 / 禁用插件 ​

有些插件你暂时不想用但也不想卸载，可以禁用它：

bash
# 禁用某个插件
claude plugin disable claude-hud

# 重新启用
claude plugin enable claude-hud

# 一键禁用所有插件（排查问题时有用）
claude plugin disable --all

更新插件 ​

bash
# 更新到最新版本
claude plugin update pua

# 更新后需要重启 Claude Code 才生效

卸载插件 ​

bash
# 完全卸载
claude plugin uninstall pua

# 卸载但保留数据（下次装回来数据还在）
claude plugin uninstall pua --keep-data

[截图: 终端中执行 plugin list、disable、enable 一系列操作的完整过程]

实战：创建一个 PR Review 插件 ​

光会装别人的插件不够，我们来自己做一个。这个插件的功能是：提供一个 /review 命令，自动分析当前分支的改动并输出结构化的代码审查报告。

第一步：创建目录结构 ​

bash
mkdir -p ~/my-plugins/pr-review/.claude-plugin
mkdir -p ~/my-plugins/pr-review/commands
mkdir -p ~/my-plugins/pr-review/agents

第二步：编写 plugin.json ​

bash
# ~/my-plugins/pr-review/.claude-plugin/plugin.json
json
{
  "name": "pr-review",
  "version": "1.0.0",
  "description": "一键 PR 审查 — 自动分析改动并生成结构化审查报告",
  "author": {
    "name": "你的名字"
  },
  "license": "MIT",
  "keywords": ["code-review", "pr", "git"]
}

第三步：编写审查命令 ​

bash
# ~/my-plugins/pr-review/commands/review.md
markdown
# /review — PR 代码审查

分析当前分支相对于主分支的所有改动，生成结构化审查报告。

## 步骤

1. 运行 `git diff main...HEAD` 获取当前分支的所有改动
2. 如果没有改动，提示用户先提交代码
3. 分析改动，从以下维度审查：
   - **逻辑正确性**：是否有明显的 bug 或逻辑漏洞
   - **安全风险**：硬编码密钥、SQL 注入、XSS 等
   - **代码质量**：命名、重复代码、过长函数
   - **测试覆盖**：新增代码是否有对应测试
4. 按 CRITICAL / HIGH / MEDIUM / LOW 分级输出问题
5. 给出总体评价和改进建议

第四步：编写审查子智能体 ​

bash
# ~/my-plugins/pr-review/agents/pr-reviewer.md
markdown
# PR Reviewer

你是一个严格但友善的代码审查员。

## 审查原则
- 只关注本次改动，不评论未修改的代码
- 给出具体的改进建议，不只说"这里不好"
- 安全问题一律标记为 CRITICAL
- 对好的实践给予肯定

## 输出格式

### 概要
- 改动范围：X 个文件，+Y/-Z 行
- 总体评价：通过 / 需修改 / 需重写

### 问题列表
按严重程度排列，每个问题包含：
- 文件和行号
- 问题描述
- 建议修复方式

第五步：验证和本地测试 ​

bash
# 验证插件结构是否正确
claude plugin validate ~/my-plugins/pr-review

# 本地加载测试（不需要安装，临时生效）
claude --plugin-dir ~/my-plugins/pr-review

--plugin-dir 参数特别好用——开发阶段不用反复安装卸载，直接指定目录就能测试。进入 Claude Code 后试试输入 /review，看看命令是否正常注册。

[截图: 使用 --plugin-dir 加载自制插件后，输入 /review 命令的执行效果]

第六步：发布分享 ​

最简单的分享方式是推到 GitHub，别人添加你的仓库为市场源就能安装：

bash
# 你：推送到 GitHub
cd ~/my-plugins/pr-review
git init && git add -A && git commit -m "feat: pr-review plugin v1.0.0"
git remote add origin https://github.com/yourname/pr-review-plugin
git push -u origin main

# 别人：添加市场并安装
claude plugin marketplace add github:yourname/pr-review-plugin
claude plugin install pr-review

小结 ​

  • Plugin 是 Claude Code 的"能力打包器"，把 commands、agents、skills、hooks 打包成可安装的整体
  • 核心文件是 .claude-plugin/plugin.json，定义插件的名称、版本和描述
  • 安装流程：先 marketplace add 添加市场源，再 plugin install 安装具体插件
  • 管理命令一览：list（查看）、enable/disable（启用/禁用）、update（更新）、uninstall（卸载）
  • 开发阶段用 --plugin-dir 本地加载测试，不用反复安装卸载
  • 用 plugin validate 检查插件结构是否合规

安全提示：安装第三方插件和安装 npm 包一样，需要信任来源。插件中的 hooks 脚本会以你的用户权限执行，agents 和 skills 会影响 AI 的行为。安装前务必阅读插件源码，特别关注 hooks 目录下的脚本内容。不要安装来历不明的插件。

用 Claude Code 构建，用 VitePress 驱动

© 2026 Claude Code 实战课