📌 本讲摘要
前 24 讲我们学了 6 种扩展机制（Skills / SubAgent / Hooks / MCP / Tools / Rules）以及 Headless、Agent SDK，这些都是散装零件——单独配置在 .claude/ 目录。本讲进入 Plugins，把多种零件打包成可安装、可分享、可复用的整体。核心要点：

• plugin.json manifest 规范：描述插件的元数据与依赖
• 标准目录结构：.claude-plugin/ 根目录 + skills/ / agents/ / commands/ / hooks/ / .mcp.json 五个子目录
• 团队能力包：把团队沉淀的 Skills / SubAgent / Hooks 打包成一个 plugin
• marketplace 分发：把 plugin 推到 GitHub / 公司内部 registry / Anthropic 官方 marketplace
  本讲的三条主线：
• 第一、Plugin 是什么 + 目录结构 + manifest 规范——把 6 种扩展机制打包成整体，类比 npm 包；plugin.json 含 6 字段（name / version / description / author / dependencies / minClaudeVersion）；目录结构为 .claude-plugin/ 根 + 5 子目录。
• 第二、团队能力包 + Plugin 安装加载——把代码审查全家桶（SubAgent + Skill + Hook）打包成 1 个 plugin；claude plugin install 一行命令完成 onboarding；3 种安装方式（从 name / git URL / 本地路径）。
• 第三、marketplace 分发 + 5 个最佳实践——marketplace 是 plugin 商店（5 种类型）；5 个实践：写通用能力、进 git 共享、写 README、配版本号、CI 测试。
  **学完本讲你应该能：**写 plugin.json manifest、配 Plugin 完整目录结构、打包团队能力包、熟练使用 claude plugin install / publish 等 5 个核心命令，并能清晰区分 Plugin 与散装配置的工程定位。

📖 详细内容

Plugin 是什么？为什么需要它？

前 24 讲我们学的 6 种扩展机制（Skills / SubAgent / Hooks / MCP / Tools / Rules）是散装零件——每种都要单独配置在 .claude/ 目录下。这种方式适合自己用或小团队用，但不适合团队通用能力沉淀和跨团队分享。

**举个例子：**假设团队花了 3 个月沉淀出一套代码审查全家桶，包含 code-reviewer SubAgent（独立上下文审查）+ review-checklist Skill（检查清单）+ pre-commit Hook（提交前跑 lint）。这 3 个零件散装在 .claude/ 目录，新成员 onboarding 要走 4 步：

1. 复制 SubAgent 文件到 .claude/agents/。
2. 复制 Skill 文件到 .claude/skills/。
3. 配置 Hook 到 .claude/settings.json。
4. 写 README 解释怎么用。

4 步繁琐、容易遗漏、新成员 onboarding 慢。Plugin 正是为了解决这个痛点而生：把 3 个零件 + README + manifest 打包成 1 个 plugin，新成员只需一行命令 claude plugin install code-review-suite 即可搞定。

Plugin 的 5 个核心价值

• 可安装——一行命令安装，不用手动复制配置。
• 可分享——推到 GitHub / 内部 registry / Anthropic marketplace，跨团队、跨公司分享。
• 可复用——同一份 plugin 在多个项目使用，不用每个项目重写。
• 可版本管理——plugin 有版本号，可以升级、回滚、锁定。
• 可依赖管理——plugin 声明依赖，装 plugin 时自动装依赖。

这 5 个价值让 Plugin 成为团队能力沉淀的标准方式。

类比 npm 包 / pip 包

Plugin 之于 Claude Code ≈ npm 包之于 Node.js / pip 包之于 Python。npm 包是 JS 库的打包方式，Plugin 是 Claude Code 扩展机制的打包方式。同样的包概念，不同的生态。

Plugin 目录结构 + plugin.json manifest 规范

Plugin 有标准的目录结构和 manifest 文件，任何 plugin 作者按规范编写，任何 Claude Code 用户按规范安装。

Plugin 完整目录结构

code-review-suite/                 ← plugin 根目录（与 plugin 同名）
├── .claude-plugin/                ← plugin 元数据目录
│   └── plugin.json                ← manifest 文件（必填）
├── skills/                        ← Skill 目录（可选）
│   └── review-checklist/
│       └── SKILL.md               ← 检查清单 Skill
├── agents/                        ← SubAgent 目录（可选）
│   └── code-reviewer.md           ← 代码审查 SubAgent
├── commands/                      ← Command 目录（可选）
│   └── review.md                  ← /review 命令
├── hooks/                         ← Hook 脚本目录（可选）
│   └── pre-commit.sh              ← 提交前跑 lint
├── .mcp.json                      ← MCP server 配置（可选）
└── README.md                      ← 用法说明（推荐）

.claude-plugin/ 根目录加上 5 个扩展机制子目录，恰好覆盖前 24 讲学的所有扩展机制。Plugin 作者按需填写，不必 5 个子目录都填——例如纯 Skill plugin 只用 skills/ + plugin.json，纯 Hook plugin 只用 hooks/ + plugin.json。

plugin.json manifest 规范

plugin.json 共 6 个必填/选填字段：

• name——plugin 名称（英文、小写、连字符）。例："code-review-suite"。
• version——语义化版本。例："1.0.0"（major.minor.patch）。
• description——plugin 描述（给安装者看的简要说明）。
• author——作者信息（姓名 + 邮箱）。
• dependencies——依赖列表（其他 plugin / 工具）。
• minClaudeVersion——最低 Claude Code 版本要求。

完整示例见后面完整 plugin.json manifest 示例代码块。

团队能力包：从散装配置到打包分发

团队能力包 = 把团队沉淀的多种零件（Skills / SubAgent / Hooks / MCP）打包成 1 个 plugin，只需 3 个步骤。

step 1：识别团队通用能力

团队能力 ≠ 项目专属配置。识别团队通用能力有 3 个判断标准：

1. 多项目共用——这个能力在 2+ 个项目使用，是团队通用能力。
2. 多成员共用——多个团队成员都会用到，值得打包。
3. 相对稳定——不经常变化（每月 < 1 次更新），适合打包。

3 个条件全部满足 → 属于团队通用能力 → 适合打包成 plugin。

step 2：打包到 .claude-plugin/ 目录

把已有的散装文件复制到 plugin 目录结构中：

• .claude/agents/code-reviewer.md → code-review-suite/agents/code-reviewer.md
• .claude/skills/review-checklist/SKILL.md → code-review-suite/skills/review-checklist/SKILL.md
• .claude/hooks/pre-commit.sh → code-review-suite/hooks/pre-commit.sh

3 个文件复制完成后，加上 plugin.json 和 README.md，一个 plugin 就成型了。

step 3：新成员 onboarding 一行命令搞定

新成员只需执行 claude plugin install code-review-suite，3 个零件和配置全部装好，无需手动复制。

完整代码见后面团队能力包：code-review-suite 完整 plugin 代码块。

团队能力包 vs 项目专属配置

**团队能力包（打包分发）：**code-reviewer SubAgent、review-checklist Skill、pre-commit Hook 等团队通用、跨项目使用的能力。

**项目专属配置（散装存放）：**本项目的 src/ 路径、本项目的数据库名、本项目的部署脚本等只在本项目使用的配置。

Plugin 适合前者，散装适合后者。

Plugin 安装与加载机制

Plugin 支持 3 种安装方式、3 级加载、1 个卸载命令，覆盖完整的生命周期管理。

3 种安装方式

• 方式 1：从名字装（从 marketplace 搜索）——claude plugin install code-review-suite。Claude Code 从配置的 marketplace 搜索并安装最新版本。
• 方式 2：从 git URL 装（直接装 GitHub 仓库）——claude plugin install https://github.com/your-team/code-review-suite。执行 git clone 仓库并安装到本地。
• 方式 3：从本地路径装（开发调试用）——claude plugin install /path/to/code-review-suite。从本地目录直接加载，适合开发阶段测试。

3 种方式覆盖用户装、团队装、开发装 3 个典型场景。

3 级加载

• 级别 1：项目级 plugin——位于 .claude/plugins/（项目根目录），只在本项目生效。
• 级别 2：全局 plugin——位于 ~/.claude/plugins/（用户家目录），所有项目共享。
• 级别 3：用户级 plugin——位于 ~/.claude/plugins/<user>/（特定用户目录），个人专属。

3 级叠加机制：项目级、全局级、用户级都会加载，并合并到 Claude Code 配置。优先级规则：项目级 > 全局级 > 用户级（项目级覆盖）。

卸载

claude plugin uninstall code-review-suite——删除 .claude-plugin/ 目录并清理相关配置。

完整命令清单见后面 Plugin 安装/发布命令完整清单代码块。

marketplace 分发：从内部使用到社区分享

Plugin 写好不能只在本地，需要推到 marketplace 才能让别人安装。marketplace 就是 plugin 的商店——托管 plugin 列表，提供 claude plugin install <name> 的搜索后端。

5 种 marketplace 类型

• 类型 1：GitHub 仓库——plugin 推到 GitHub，Claude Code 直接 clone 仓库安装。最简单，适合小团队或个人。
• 类型 2：公司内部 registry——公司搭建私有 registry（类似 npm 私有源），托管公司内部 plugin。安全可控。
• 类型 3：Anthropic 官方 marketplace——Anthropic 维护的官方 plugin 商店（类似 Apple App Store），托管社区贡献的 plugin。经过质量审核，适合公开发布。
• 类型 4：第三方平台——类似 plugin.ai 之类的第三方平台，托管社区 plugin，自由度高。
• 类型 5：本地文件——plugin 不推任何地方，只在本地文件中加载，适合开发调试。

5 种类型覆盖个人、团队、公开 3 个使用范围。

发布命令

claude plugin publish——在 plugin 根目录执行，plugin 被推到配置的 marketplace（默认 Anthropic 官方）。发布前需要先登录（claude plugin login）。

**发布流程：**写 plugin → 测试 → 写 README → 配版本号 → claude plugin login → claude plugin publish → 用户 claude plugin install。

类型	托管方式	适用	安全性	发现性
GitHub 仓库	git clone 仓库	个人 / 小团队	中（代码可见）	低（靠搜）
公司内部 registry	私有 npm-style 源	企业私有 plugin	高（私有）	中（团队内可搜）
Anthropic 官方 marketplace	官方审核发布	公开发布	高（审核）	高（官方商店）
第三方平台	第三方托管	社区自由发布	中（平台审核）	中（平台内可搜）
本地文件	本地路径	开发调试	高（本地）	无（自己用）

Plugin 开发的 5 个最佳实践 + Plugin vs 散装配置边界

会用 Plugin 是基础，精通 Plugin 开发还需要掌握 5 个最佳实践。

最佳实践 1：Plugin 写团队通用能力，不写项目专属

Plugin 应是通用能力，而不是项目专属配置。反例：plugin 写死项目路径 /Users/me/projects/myapp/，换个项目就用不了。正例：plugin 写代码审查通用能力，不绑死项目路径。

**判断标准：**这个 plugin 换个项目还能用吗？能用 → 通用能力，适合打包；不能用 → 散装配置，适合放在 .claude/ 目录。

最佳实践 2：进 git 团队共享

Plugin 仓库进 git，团队成员都能 clone / pull / push。配合 CI 跑 plugin 集成测试，确保 plugin 改动不会破坏其他项目。

**判断标准：**plugin 在 git 跟踪吗？没在跟踪，赶紧入 git。

最佳实践 3：写 README 说明用法

README 是必填项——plugin 装完怎么用？提供什么 Skill / SubAgent / Hook？有没有示例代码？必填 5 段内容：简介、安装、用法、配置、卸载。

最佳实践 4：配版本号语义化

版本号采用 semver 规范（major.minor.patch）：

• major——不兼容的重大改动。
• minor——向后兼容的新功能。
• patch——向后兼容的 bug 修复。

用户可以根据 major 版本决定是否升级，根据 minor / patch 自动升级。

最佳实践 5：在 CI 跑集成测试

Plugin 改完后，在 CI 跑集成测试——装 plugin → 跑示例代码 → 验证 Skill / SubAgent / Hook 都能正常使用。CI 失败不 merge，确保 plugin 质量。

Plugin vs 散装配置边界

Plugin 适合的场景：

• 团队通用能力（2+ 项目共用）。
• 跨成员共享（2+ 成员共用）。
• 跨团队 / 跨公司分享（推到 marketplace）。
• 需要版本管理（升级 / 回滚）。

散装配置适合的场景：

• 项目专属配置（本项目专用）。
• 个人偏好（用户级配置）。
• 一次性脚本（用完即弃）。

**边界判断：**这个配置是通用还是专属？通用 → Plugin；专属 → 散装。

维度	Plugin	散装配置
打包形式	整体（.claude-plugin/ 目录 + 5 子目录 + plugin.json)	单文件（.claude/ 下散装）
分享方式	claude plugin install（从 marketplace / git URL / 本地路径）	手动复制文件
版本管理	有（plugin.json version 字段、semver)	无（手动升级 / 回滚）
依赖管理	有（plugin.json dependencies 字段）	无（手动处理依赖）
加载机制	claude plugin install 后自动加载	手动放 .claude/ 目录
适用场景	团队通用能力（2+ 项目 / 2+ 成员）	项目专属配置（本项目用）

🛠️ 实战代码

📄 第 25 讲配套：完整 plugin.json manifest 示例（name / version / description / author / dependencies / minClaudeVersion 6 字段 + 完整 plugin)

// .claude-plugin/plugin.json
// 完整 manifest 示例(code-review-suite)
{
  "name": "code-review-suite",
  "version": "1.2.0",
  "description": "代码审查全家桶:code-reviewer SubAgent + review-checklist Skill + pre-commit Hook。一次安装,全团队用。",
  "author": {
    "name": "黄佳",
    "email": "huangjia@example.com"
  },
  "dependencies": [
    "claude-code >= 1.5.0",
    "@anthropic-ai/sdk >= 0.20.0"
  ],
  "minClaudeVersion": "1.5.0"
}

// === 6 字段详解 ===
// 1. name: plugin 名(英文,小写,连字符)
//    例: "code-review-suite"
//    用作 `claude plugin install code-review-suite`
// 2. version: 语义化版本
//    major.minor.patch
//    1.0.0 → 首次发布
//    1.1.0 → 加新功能(兼容)
//    1.1.1 → 修 bug
//    2.0.0 → 不兼容改动
// 3. description: 一句话描述(给安装者看)
//    应该写"做什么" + "对谁有用"
// 4. author: 作者信息(姓名 + 邮箱)
// 5. dependencies: 依赖列表
//    其他 plugin / npm 包 / 系统工具
// 6. minClaudeVersion: 最低 Claude Code 版本
//    老版本 Claude Code 不支持新 plugin 字段
//    配这个字段,装 plugin 时检查版本

// === 可选字段(扩展)===
// keywords: ["review", "code-quality", "team"]
// repository: "https://github.com/your-team/code-review-suite"
// license: "MIT"
// homepage: "https://your-plugin-docs.com"

📄 第 25 讲配套：Plugin 完整目录结构（.claude-plugin/ 根 + skills/ + agents/ + commands/ + hooks/ + .mcp.json 5 子目录）

#!/usr/bin/env bash
# Plugin 完整目录结构
# (以 code-review-suite 为例)

code-review-suite/                 ← plugin 根目录
├── .claude-plugin/                ← plugin 元数据目录(必填)
│   └── plugin.json                ← manifest 文件(必填)
├── skills/                        ← Skill 目录(可选)
│   ├── review-checklist/
│   │   └── SKILL.md               ← 检查清单 Skill
│   └── conventional-commits/
│       └── SKILL.md               ← commit 规范 Skill
├── agents/                        ← SubAgent 目录(可选)
│   ├── code-reviewer.md           ← 代码审查 SubAgent
│   ├── security-reviewer.md       ← 安全审查 SubAgent
│   └── test-runner.md             ← 测试运行 SubAgent
├── commands/                      ← Command 目录(可选)
│   ├── review.md                  ← /review 命令(用户主动审查)
│   ├── lint.md                    ← /lint 命令
│   └── test.md                    ← /test 命令
├── hooks/                         ← Hook 脚本目录(可选)
│   ├── pre-commit.sh              ← 提交前跑 lint
│   ├── auto-format.sh             ← 写完代码自动 ruff format
│   └── audit-log.sh               ← 审计日志
├── .mcp.json                      ← MCP server 配置(可选)
└── README.md                      ← 用法说明(推荐)

// === 6 子目录对应 6 种扩展机制 ===
// .claude-plugin/  →  plugin.json(元数据)
// skills/          →  Skills(自动发现本地能力)
// agents/          →  SubAgent(独立上下文角色)
// commands/        →  Commands(用户主动命令)
// hooks/           →  Hooks(事件驱动拦截)
// .mcp.json        →  MCP(连接外部 API)

// === 6 子目录都是可选的 ===
// plugin.json 必填, 5 子目录按需填
// 例: 纯 Skill plugin 只有 skills/ + plugin.json
// 例: 纯 Hook plugin 只有 hooks/ + plugin.json

// === 加载机制 ===
// Claude Code 启动时, 加载 plugin 的 5 子目录
// - skills/   → 加载到 .claude/skills/
// - agents/   → 加载到 .claude/agents/
// - commands/ → 加载到 .claude/commands/
// - hooks/    → 合并到 .claude/settings.json 的 hooks
// - .mcp.json → 合并到 .mcp.json

📄 第 25 讲配套：团队能力包：code-review-suite 完整 plugin（包含 code-reviewer SubAgent + review-checklist Skill + pre-commit Hook)

#!/usr/bin/env bash
# 团队能力包:code-review-suite 完整 plugin
# 假设团队已经写了 3 个散装文件:
# - .claude/agents/code-reviewer.md
# - .claude/skills/review-checklist/SKILL.md
# - .claude/hooks/pre-commit.sh

# === step 1:创建 plugin 目录结构 ===
mkdir -p code-review-suite/.claude-plugin
mkdir -p code-review-suite/skills/review-checklist
mkdir -p code-review-suite/agents
mkdir -p code-review-suite/hooks

# === step 2:复制已有散装文件到 plugin ===
cp .claude/agents/code-reviewer.md code-review-suite/agents/
cp .claude/skills/review-checklist/SKILL.md code-review-suite/skills/review-checklist/
cp .claude/hooks/pre-commit.sh code-review-suite/hooks/
chmod +x code-review-suite/hooks/pre-commit.sh

# === step 3:写 plugin.json ===
cat > code-review-suite/.claude-plugin/plugin.json << 'EOF'
{
  "name": "code-review-suite",
  "version": "1.0.0",
  "description": "团队代码审查全家桶:SubAgent + Skill + Hook 一次装齐",
  "author": {
    "name": "黄佳",
    "email": "huangjia@example.com"
  },
  "minClaudeVersion": "1.5.0"
}
EOF

# === step 4:写 README.md ===
cat > code-review-suite/README.md << 'EOF'
# code-review-suite

团队代码审查全家桶。

## 安装

\`\`\`bash
claude plugin install code-review-suite
\`\`\`

## 用法

装完提供 3 个能力:

### 1. code-reviewer SubAgent

\`\`\`
@code-reviewer 审查 src/api/users.py
\`\`\`

### 2. review-checklist Skill

Claude 改代码时自动触发检查清单。

### 3. pre-commit Hook

git commit 时自动跑 ruff + mypy。

## 卸载

\`\`\`bash
claude plugin uninstall code-review-suite
\`\`\`
EOF

# === step 5:本地测试 ===
cd code-review-suite
claude plugin install .  # 从本地路径装
claude plugin list        # 确认装上
@code-reviewer 审查 src/api/users.py  # 验证能用

# === step 6:推到 git ===
cd ..
git init code-review-suite
cd code-review-suite
git add .
git commit -m "feat: code-review-suite v1.0.0"
git remote add origin https://github.com/your-team/code-review-suite
git push -u origin main

# === step 7:发布到 marketplace ===
claude plugin login
claude plugin publish  # 推到 Anthropic 官方 marketplace

# === 团队新成员 onboarding ===
# 新成员:
# claude plugin install code-review-suite
# 一行命令, 3 个能力全装好

📄 第 25 讲配套：Plugin 安装/发布命令完整清单（install / uninstall / list / update / publish 5 命令）

#!/usr/bin/env bash
# Plugin 安装/发布命令完整清单

# === 命令 1:install(安装)===
# 从 marketplace 装
claude plugin install code-review-suite

# 从 git URL 装
claude plugin install https://github.com/your-team/code-review-suite

# 从本地路径装(开发调试)
claude plugin install /path/to/code-review-suite

# 装指定版本
claude plugin install code-review-suite@1.2.0

# === 命令 2:uninstall(卸载)===
claude plugin uninstall code-review-suite

# === 命令 3:list(列出已装)===
claude plugin list

# 输出示例:
# NAME                  VERSION  SOURCE
# code-review-suite     1.2.0    marketplace
# my-team-tools         2.0.0    local:/Users/me/plugins/my-team
# test-helpers          0.5.0    git:https://github.com/me/test-helpers

# === 命令 4:update(更新)===
# 更新指定 plugin
claude plugin update code-review-suite

# 更新所有 plugin
claude plugin update --all

# === 命令 5:publish(发布)===
# 发布到 marketplace
# 前提:在 plugin 根目录,已 login
cd code-review-suite
claude plugin login  # 第一次发布前要登录
claude plugin publish

# 发布到指定 marketplace
claude plugin publish --marketplace company-internal

# === 命令 6:search(搜索)===
# 在 marketplace 搜 plugin
claude plugin search code-review

# === 命令 7:info(查 plugin 信息)===
claude plugin info code-review-suite
# 输出: name / version / description / dependencies / 安装次数

# === 命令 8:enable / disable(临时启停)===
# 临时禁用(不卸载)
claude plugin disable code-review-suite

# 重新启用
claude plugin enable code-review-suite

# === 5 个最常用命令 ===
# install / uninstall / list / update / publish

📊 流程图

⚠️ 常见坑

⚠️ 把项目路径写死在 plugin 里，导致换个项目就用不了
**陷阱：**写 plugin 时把项目路径写死（如 /Users/me/projects/myapp/）或绑定项目专属命令（如 deploy-to-staging 只对当前项目有效），换个项目就用不了。
**修正：**Plugin 应写通用能力——不绑死项目路径，使用相对路径或参数化；不绑死项目命令，写通用操作（如代码审查、测试、部署）。
**判断标准：**你的 plugin 换个项目还能用吗？能用 → 通用能力、适合打包；不能用 → 散装配置、放在 .claude/ 目录。
⚠️ plugin.json 缺少 minClaudeVersion 字段，老版本不兼容
**陷阱：**plugin 用了新版本 Claude Code 才支持的字段（如新的 frontmatter 字段），老版本 Claude Code 装上后不识别，加载失败。
**修正：**plugin.json 中配置 minClaudeVersion 字段，装 plugin 时检查 Claude Code 版本，版本不够则提示升级。
**判断标准：**你的 plugin.json 有 minClaudeVersion 字段吗？没有的话，赶紧加上（先查当前 Claude Code 版本）。
⚠️ 多个 plugin 名字冲突，后装的覆盖先装的
**陷阱：**装了 2 个 plugin 都有 code-reviewer skill，Claude Code 加载时冲突，后装的覆盖先装的，或报 duplicate skill 错误。
**修正：**plugin 名加命名空间前缀（如 team-a-code-reviewer / team-b-code-reviewer），或 plugin 内的 skill / agent 加 plugin 名后缀（如 code-reviewer-team-a）。
**判断标准：**你装多个 plugin 时遇到过冲突吗？遇到过的话，赶紧加命名空间前缀。
⚠️ Plugin 不进 git 团队共享，形成 plugin 孤岛
**陷阱：**plugin 写在本地，不进 git 也不推 marketplace，只有作者自己能用。其他成员要装，必须手动复制文件，容易出错。
**修正：**plugin 进 git 团队共享，配合 CI 跑集成测试（plugin 改完跑测试，确保不破坏其他成员的使用）。
**判断标准：**你的 plugin 在 git 跟踪吗？有 CI 测试吗？都没有的话，赶紧入 git 并配置 CI。

💡 一句话备忘

Plugin 把 6 种扩展机制打包成可分享的整体：plugin.json manifest 6 字段定义元数据、.claude-plugin/ + 5 子目录承载能力、一次 claude plugin install 完成团队 onboarding、5 种 marketplace 分发实现跨团队复用。从散装配置到 Plugin，是 Claude Code 能力从个人使用走向团队资产的关键一步。