<!-- title: 把Skill打包成Plugin分发实战 -->

## 概述

你已经会写单个 `SKILL.md`，但把同一个 Skill 复制粘贴到十个项目、分享给三十个同事时，问题就来了：版本对不齐、触发词各写各的、更新要逐个仓库改。本教程教你把一个（或几个）Skill 升级为**自包含 Plugin**，通过 **marketplace** 一键分发、命名空间隔离、版本化更新。适合已经写过至少一个 Skill、想把能力沉淀给团队的 Claude Code 中级用户。

## 前置条件

- Claude Code 已安装并认证（能看到 `/plugin` 命令；看不到就升级到最新版）
- 写过至少一个独立 Skill（`.claude/skills/xxx/SKILL.md`），理解 `name` / `description` / 渐进式披露
- 一个 Git 仓库（GitHub / GitLab / 内部 GitLab 均可）用于托管 marketplace
- 基本的 JSON 语法常识

---

## 一、为什么"单个 Skill"撑不起团队

一个人用 Skill 很爽：丢进 `.claude/skills/`，下次会话自动加载。但当规模上去，三个痛点同时爆发——和当年 `CLAUDE.md` 膨胀是同一类病：

1. **复制漂移**：同一个"代码质量审查"Skill，A 仓库的版本加了安全检查、B 仓库没有。一周后两个仓库行为不一致，没人知道哪个是对的。
2. **更新无门**：你想给所有项目的 Skill 升级 description 触发词，只能挨个 `git pull` + 手动改，十几个仓库改下来人麻了。
3. **命名打架**：张三的 `review` Skill 和李四的 `review` Skill 名字一样，装到同一台机器上互相覆盖。

Plugin 正是为这三件事设计的：它是**一个带清单的目录**，把 Skills / Commands / Subagents / Hooks / MCP 打包成一个整体，通过 marketplace 统一发布、带版本、靠命名空间避免冲突。一句话——**Skill 是"能力"，Plugin 是"可分发的能力包"**。

## 二、Plugin vs 独立配置：什么时候该升级

不是所有 Skill 都值得打包。Claude Code 官方给了清晰的判断标准：

| 维度 | 独立配置（`.claude/`） | Plugin |
|------|----------------------|--------|
| 适用场景 | 个人、单项目、快速实验 | 团队共享、社区分发、跨项目复用 |
| Skill 调用名 | 短，如 `/hello` | 命名空间化，如 `/my-plugin:hello` |
| 版本管理 | 靠人工 | 清单 `version` 字段 + git |
| 更新方式 | 手动改文件 | `/plugin marketplace update` |

经验法则：**先在 `.claude/` 里快速迭代，等它稳定、且第二个项目也想用时，再升级成 Plugin。** 别一上来就打包——大多数 Skill 死在"过度工程化"上。

## 三、动手：六步把 Skill 封进 Plugin

### Step 1：准备一个待打包的 Skill

假设你已经有一个"代码质量审查"Skill，原本躺在 `.claude/skills/quality-review/SKILL.md`。先把它复制出来作为打包的原料。

### Step 2：创建 Plugin 清单（最关键的一步）

Plugin 的身份认证文件是 `plugin.json`，**必须放在插件根目录下的 `.claude-plugin/` 里**。

```bash
mkdir -p quality-review-plugin/.claude-plugin
mkdir -p quality-review-plugin/skills/quality-review
```

创建 `quality-review-plugin/.claude-plugin/plugin.json`：

```json
{
  "name": "quality-review-plugin",
  "description": "Adds a quality-review skill for quick code reviews, with a pre-commit safety hook.",
  "version": "1.0.0",
  "author": { "name": "DevTools Team" },
  "homepage": "https://github.com/yourorg/quality-review-plugin",
  "license": "MIT"
}
```

**字段含义**：

- `name`：唯一标识，同时是**命名空间前缀**。Skill 会被调用为 `/quality-review-plugin:quality-review`。改成短名也行，但要 kebab-case、全程唯一。
- `description`：显示在 plugin manager 浏览/安装界面，**写给人类看**的（和 Skill description 写给模型看不同）。
- `version`：可选但强烈建议设。设了之后，用户**只在 bump 这个字段时才收到更新**；不设则每个 git commit 都算新版本——团队场景下会让你被无意义的更新淹没。

**常见问题**：
- *Q：我能把 `plugin.json` 放在插件根目录而不是 `.claude-plugin/` 里吗？* A：不能。Claude Code 只认 `.claude-plugin/plugin.json` 这个路径。
- *Q：`name` 能用大写或空格吗？* A：不行，必须 kebab-case，否则 marketplace 校验报错。

### Step 3：组织目录结构（最容易踩的坑）

这是新手翻车重灾区。Plugin 可以包含多种组件，但**只有 `plugin.json` 待在 `.claude-plugin/` 里，其余目录全部放在插件根目录**：

```
quality-review-plugin/
├── .claude-plugin/
│   └── plugin.json          # 唯一住在 .claude-plugin/ 里的文件
├── skills/
│   └── quality-review/
│       └── SKILL.md          # 你的 Skill
├── commands/                 # 扁平 .md，等价于 skills/，新插件优先用 skills/
├── agents/
│   └── deep-review.md        # 可选：子代理
├── hooks/
│   └── hooks.json            # 可选：PreToolUse/PostToolUse 事件处理
├── .mcp.json                 # 可选：MCP 服务器配置
└── settings.json             # 可选：随插件下发的默认设置
```

**致命错误**：把 `skills/`、`commands/`、`hooks/` 放进 `.claude-plugin/` 目录里。Claude Code 找不到它们，Plugin 看起来装上了但什么 Skill 都没有。记住口诀：**`.claude-plugin/` 只住清单，其它都住根。**

把 Step 1 的 Skill 放进去：

```bash
cp .claude/skills/quality-review/SKILL.md \
   quality-review-plugin/skills/quality-review/SKILL.md
```

`SKILL.md` 内容保持你原来的，frontmatter 照旧：

```markdown
---
description: Review code for bugs, security, and performance. Triggers on "review this", "code review", "check my changes".
---

# Quality Review

审查当前选中的代码或最近改动，关注：
- 潜在 bug 与边界条件
- 安全隐患
- 性能问题
- 可读性改进

输出要简洁、可执行。
```

### Step 4：本地测试 Plugin

不用发布就能测。两种方式：

**方式 A：一次性加载（开发调试用）**

```bash
claude --plugin-dir ./quality-review-plugin
```

启动后在会话里：

```
/quality-review-plugin:quality-review
```

看到 Claude 按你的 Skill 内容回应，说明打包成功。改完文件后用 `/reload-plugins` 热加载，不用重启。

**方式 B：自动加载（长期开发用）**

```bash
claude plugin init quality-review-plugin
```

这会在 `~/.claude/skills/quality-review-plugin/` 下生成带清单和 starter `SKILL.md` 的脚手架，下次会话自动以 `quality-review-plugin@skills-dir` 加载，**无需 marketplace、无需 install**。

**常见问题**：
- *Q：改了 `SKILL.md` 但行为没变？* A：忘了 `/reload-plugins`，或忘了 bump `version`（marketplace 分发时）。
- *Q：Skill 没出现在 `/help`？* A：九成是目录放错位置，或 `plugin.json` 不在 `.claude-plugin/`。

### Step 5：构建 marketplace 清单

Plugin 本身只是"一个包"，要分发还需要一个**目录文件 `marketplace.json`**，告诉 Claude Code 这里有哪些 Plugin、各自从哪取。它放在**仓库根目录的 `.claude-plugin/` 里**。

```bash
mkdir -p my-marketplace/.claude-plugin
mkdir -p my-marketplace/plugins/quality-review-plugin/.claude-plugin
mkdir -p my-marketplace/plugins/quality-review-plugin/skills/quality-review
```

把 Step 3 的 Plugin 整体移进 `plugins/` 下，然后创建 `my-marketplace/.claude-plugin/marketplace.json`：

```json
{
  "name": "company-tools",
  "owner": { "name": "DevTools Team", "email": "devtools@example.com" },
  "plugins": [
    {
      "name": "quality-review-plugin",
      "source": "./plugins/quality-review-plugin",
      "description": "Adds a quality-review skill for quick code reviews",
      "version": "1.0.0",
      "author": { "name": "DevTools Team" }
    }
  ]
}
```

**字段要点**：
- `name`：marketplace 标识，kebab-case，**用户可见**——安装命令长这样 `/plugin install quality-review-plugin@company-tools`。每个用户同名只能注册一个。
- **保留名**：`claude-code-marketplace`、`anthropic-plugins`、`agent-skills`、`claude-for-legal` 等一批名字被官方占用，第三方用了会被拒。带 `official-`、`anthropic-` 前缀的仿冒名也会被 block。
- `owner`：`name` 必填，`email` 选填。
- `plugins[].source`：支持相对路径、`github` 仓库、裸 git URL、npm 包、git 子目录——后面展开。

**常见问题**：
- *Q：一个 marketplace 能放多个 Plugin 吗？* A：能，全列进 `plugins[]` 数组。要发多个包就别建多个同名 marketplace。
- *Q：source 用相对路径还是 git？* A：本地测试用相对路径（`./plugins/xxx`），对外发布用 git/github source。

### Step 6：托管、安装、更新

**本地测试安装**（分发前的最后一关）：

```
/plugin marketplace add ./my-marketplace
/plugin install quality-review-plugin@company-tools
```

**对外发布**：把整个 `my-marketplace` 仓库 push 到 GitHub。用户侧：

```
/plugin marketplace add yourorg/my-marketplace
/plugin install quality-review-plugin@company-tools
```

**版本与更新**：
- 你 bump `plugin.json` 的 `version`（如 `1.0.0` → `1.1.0`）并 push。
- 用户执行 `/plugin marketplace update` 拉到新版本。
- 如果当初**没设** `version`，则每次 git commit 都被视为新版本——团队协作时这会让你被噪音淹没，**务必显式设 version**。

**分发源类型速查**：

| source 形式 | 写法 | 适用 |
|------------|------|------|
| 相对路径 | `"./plugins/quality-review-plugin"` | 本地、同仓库测试 |
| GitHub | `{"source":"github","repo":"yourorg/plugin"}` | 公开仓库首选 |
| 裸 Git | `{"source":"git","url":"https://gitlab.../x.git"}` | GitLab/私有 |
| npm | `{"source":"npm","package":"@org/plugin"}` | 已发布到 npm |
| Git 子目录 | `{"source":"github","repo":"org/mono","subdir":"plugins/x"}` | monorepo |

---

## 四、实战案例：一个三件套团队 Plugin

光说不练假把式。下面这个案例把"质量审查"做成一个**包含 Skill + Hook + Subagent** 的完整 Plugin，体现 Plugin 比 Skill 强在哪——它能打包一整套协作的约定。

### 场景

团队约定：每次代码审查要 (1) 跑标准化审查清单；(2) 编辑文件后自动跑 lint；(3) 复杂变更交给一个隔离上下文的"深度审查"子代理。三条能力若拆成三个 Skill 散落各处，新人根本记不住。打包成一个 Plugin，装一次全有。

### 目录

```
quality-review-plugin/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   └── quality-review/
│       └── SKILL.md
├── hooks/
│   └── hooks.json
└── agents/
    └── deep-review.md
```

### `plugin.json`

```json
{
  "name": "quality-review-plugin",
  "description": "Team code-review toolkit: standardized review skill, post-edit lint hook, deep-review subagent.",
  "version": "1.2.0",
  "author": { "name": "Platform Team" }
}
```

### `skills/quality-review/SKILL.md`

```markdown
---
description: Run the team's standardized code review checklist. Triggers on "review this", "code review", "check my diff".
---

# Quality Review

对最近改动或选中代码执行团队审查清单：
1. **正确性**：边界条件、空值、错误处理
2. **安全**：注入、鉴权、敏感信息泄露
3. **性能**：N+1 查询、无谓分配、热路径
4. **可读性**：命名、复杂度、注释密度

变更复杂时，把审查工作委派给 `deep-review` 子代理（用 `/agents deep-review`），隔离上下文避免污染主会话。
输出简洁、按严重度排序、每条带可执行建议。
```

### `hooks/hooks.json`（编辑后自动 lint）

```json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "npx --no-install lint-staged || true" }
        ]
      }
    ]
  }
}
```

### `agents/deep-review.md`（隔离上下文的子代理）

```markdown
---
name: deep-review
description: Performs an exhaustive review of complex changes in an isolated context, returning a structured report.
tools: Read, Grep, Glob, Bash
---

你是一个资深代码审查专家。对给定改动做深度分析，重点关注架构影响、回归风险、
并发与时序问题。输出结构化报告：**确认问题** / **可疑项** / **改进建议**。
不修改任何文件，只读分析。
```

### 发布与安装闭环

```bash
# 1. 推到 GitHub
git init && git add . && git commit -m "release quality-review-plugin 1.2.0"
git remote add origin git@github.com:yourorg/quality-marketplace.git
git push -u origin main

# 2. 团队成员（一次性）
/plugin marketplace add yourorg/quality-marketplace

# 3. 团队成员（按角色）
/plugin install quality-review-plugin@company-tools

# 4. 用起来
/quality-review-plugin:quality-review    # 跑标准清单
# 编辑文件后 PostToolUse hook 自动 lint
```

**预期结果**：装完一次，团队全员获得统一的审查口径、自动 lint、隔离上下文的深度审查——三者共享同一个版本号，更新只需一条 `/plugin marketplace update`。这正是单个 Skill 给不了的。

---

## 五、全链路流程图

```mermaid
flowchart TD
    A["独立 Skill\n.claude/skills/x/SKILL.md"] -->|稳定后升级| B["Plugin 目录\n.claude-plugin/plugin.json + skills/"]
    B --> C{本地测试}
    C -->|--plugin-dir| D["claude --plugin-dir ./plugin"]
    C -->|长期开发| E["claude plugin init\n~/.claude/skills/ 自动加载"]
    D --> F["/reload-plugins\n调 /plugin:skill 验证"]
    E --> F
    F -->|OK| G["打包进 marketplace\n.claude-plugin/marketplace.json"]
    G --> H["push 到 GitHub/GitLab"]
    H --> I["用户: /plugin marketplace add\n/plugin install X@Y"]
    I --> J["用户: /plugin marketplace update\n（你 bump version 后）"]
    B -.可含.-> K["hooks/ agents/ .mcp.json commands/"]
    K -.命名空间隔离.-> I
```

```mermaid
flowchart LR
    subgraph 开发者
      P["plugin.json\nname/version"]
      M["marketplace.json\nplugins[].source"]
    end
    subgraph 分发渠道
      GH["GitHub repo"]
      GL["私有 GitLab"]
      NPM["npm package"]
    end
    subgraph 用户机器
      CACHE["插件缓存副本\n（复制而来，禁 ../）"]
      NS["命名空间\n/plugin:skill"]
    end
    P --> M --> GH & GL & NPM --> CACHE --> NS
```

---

## 六、常见坑与排查

1. **"装上了但 Skill 不触发"** → 99% 是 `skills/` 被错放进 `.claude-plugin/`。记住只有 `plugin.json` 住那儿。
2. **"Plugin 引用 `../shared-utils` 找不到"** → Plugin 安装时被**整体复制到缓存**，无法访问目录外的文件。需要跨插件共享就用 **symlink**。
3. **"marketplace 名字被拒"** → 撞了官方保留名（`claude-*`、`anthropic-*`、`agent-skills` 等），换个非官方前缀。
4. **"更新推不下去"** → 没在 `plugin.json` bump `version`，或用户没跑 `/plugin marketplace update`。
5. **"两个 Plugin 的 Skill 重名"** → 不会冲突，命名空间隔离（`/a:review` vs `/b:review`），但描述太像会让模型纠结触发哪个——靠 description 写清边界。
6. **"只想手动调用，不想被模型自动触发"** → Skill frontmatter 加 `disable-model-invocation: true`，变成纯命令式 Skill。
7. **"私有仓库认证失败"** → 用带凭据的 git source 或配置 SSH key；marketplace 支持 private repo，但用户侧要能访问。
8. **"marketplace 加载报校验错误"** → JSON 字段名拼错（如 `plugin` 少了 `s`），或 `source` 类型不匹配。用 `$schema` 字段接上 JSON Schema 拿到编辑器校验提示。

---

## 七、延伸阅读

- **Plugins 完整参考**：`code.claude.com/docs/en/plugins` 的 "Plugins reference" 页，含全部 manifest 字段（homepage / repository / license 等）与 LSP / background monitors 高级组件
- **Marketplace 高级特性**：release channels（stable/beta 分流）、依赖版本锁定（`metadata.pluginRoot`）、容器内预装插件、strict mode——都在 plugin-marketplaces 文档后半段
- **从独立配置迁移**：官方 "Convert existing configurations to plugins" 章节，有把散落 `.claude/` 一键转 Plugin 的迁移步骤
- **社区 marketplace**：研究 `claude-plugins-community`（官方保留名对应的社区目录）里别人怎么组织多 Plugin 仓库，是最好的结构范本
- **Skill 设计本身**：Plugin 是分发外壳，Skill 的 description / 渐进式披露质量才是内核——这两者是"包装"与"内容"的关系，别只顾包装

---

## 八、训练营适用性评估

| 训练营类型 | 适用性 | 说明 |
|-----------|--------|------|
| 企业内训（研发团队） | ★★★★★ | 最匹配。直接产出团队内部 marketplace，ROI 立竿见影 |
| Claude Code 进阶营 | ★★★★★ | 承接"会写 Skill"之后的必然一课，填补"分发"环节 |
| 开源社区贡献营 | ★★★★☆ | 教学员把个人 Skill 发布成公开 marketplace，建立作品集 |
| 零基础入门营 | ★★☆☆☆ | 不适合。需要先掌握 Skill 基础，建议作为 Day 2/3 内容 |
| 单人开发者营 | ★★★☆☆ | 价值有限。单人用 `.claude/` 即可，除非跨多项目复用 |

**建议教学时长**：1.5–2 小时（含 30 分钟实操：从空目录到一个能 `/plugin install` 的本地 marketplace）。**前置课程**：Skill 基础（SKILL.md / frontmatter / 渐进式披露）。**考核点**：学员能独立完成"Skill → plugin.json → marketplace.json → 本地 add+install → 命名空间调用"全链路，并指出"skills/ 不能放 .claude-plugin/ 里"这个关键陷阱。

---

## 参考来源

1. [Create plugins - Claude Code Docs](https://code.claude.com/docs/en/plugins) — 官方 Plugin 创建指南，含 plugin.json schema、目录结构、`--plugin-dir` 与 `claude plugin init` 本地测试流程
2. [Create and distribute a plugin marketplace - Claude Code Docs](https://code.claude.com/docs/en/plugin-marketplaces) — 官方 marketplace 文档，含 marketplace.json 字段、source 类型、版本解析、保留名与缓存机制
3. [Claude Code Skills 2026 — Progressive Disclosure and Standardising Workflow for Teams - AnhTu.dev](https://anhtu.dev/claude-code-skills-2026-progressive-disclosure-and-how-to-standardise-workflow-for-engineering-teams-1062) — 深度长文，详述 Skill 四件套定位、Plugin 目录结构与团队级落地案例
4. [Packaging Claude Code Plugins: Bundle Skills, Hooks, Subagents, and MCP - jsManifest](https://jsmanifest.com/claude-code-plugin-packaging-guide) — 实战打包指南，重点讲"不要把 Skill 当独立单元打包"等常见误区
5. [Claude Code Plugin Marketplace & Skills Guide (2026) - alexcloudstar](https://www.alexcloudstar.com/blog/claude-code-plugin-marketplace-skills-2026/) — 2026 年 marketplace 与 skill 协作的补充视角与最佳实践

> [!tip] 51学通信知识星球
> **星主：爱卫生**（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。
> **星球定位**：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。
> **当前规模**：5200 篇主题 / 990 个回答，198 元/年。
> **加入福利**：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。
> **AI 加持**：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。

![51学通信知识星球海报-扫码加入](https://wiki.500nian.com/images/zhixingqiu_qrcode.png)