<!-- title: 把Skill打包成Plugin发团队市场 -->

把一个只在本地好用的 Skill，变成全团队 `claude plugin install` 一行命令就能装上、跟着 Git 版本走、统一升级的 Plugin——这是从"个人提效工具"到"团队基础设施"的最后一公里。本教程面向已经会写 SKILL.md、想让产出被同事复用的开发者与团队负责人。

## 前置条件

- 已安装 Claude Code（`claude --version` 能返回版本号即可，建议 2026 年的较新版本，自带 plugin 子命令）
- 一个 Git 仓库（GitHub/GitLab/Gitea 均可），团队有读取权限
- 会用 Markdown 写 Skill 指令，能看懂最小 JSON 结构
- 了解 SKILL.md 的 `name` / `description` frontmatter（本教程不会再从零讲触发机制）

> 本文聚焦"分发"而非"创造"。如果你还没写过 Skill，建议先补"渐进式披露构建分层 Skill"与"触发优先：从零造精准 Skill"两篇前置内容。

## 第 0 步：先理解三种落地位置与优先级

在动手打包前，必须先搞清楚 Skill 在 Claude Code 里有三个"栖息地"，它们的优先级决定了谁能覆盖谁。这是后续所有分发决策的底层逻辑。

| 位置 | 路径 | 作用域 | 优先级 |
|------|------|--------|--------|
| 项目级 | `<repo>/.claude/skills/` | 仅当前仓库，随 Git 提交共享 | **最高** |
| 个人级 | `~/.claude/skills/` | 你本机所有项目 | 中 |
| 插件级 | 通过 marketplace 安装 | 取决于安装范围（personal/project） | **最低** |

关键规则：**项目级 > 个人级 > 插件级**。这意味着同名 Skill 出现时，项目里的那份会赢。这条规则有一个极其重要的实战含义——当你把 Skill 打包成 Plugin 发布给团队后，仍然允许任何一个具体项目"覆盖"它：在项目的 `.claude/skills/` 放一份定制版即可。这正是分发与定制两不冲突的设计。

为什么要把 Skill 做成 Plugin 而不是直接让大家各自拷贝到 `~/.claude/skills/`？因为直接拷贝有三个死结：版本漂移（A 装了 v1，B 还是 v0）、无依赖管理、更新全靠人工喊话。Plugin + Marketplace 把这三件事一次性解决。

## 第 1 步：先写一个值得分发的 Skill

我们以"团队统一代码风格审查"为例，先在本地把 Skill 跑通。在任意工作目录创建：

```
workdir/
└── review-skill/
    └── SKILL.md
```

`review-skill/SKILL.md` 内容：

```markdown
---
name: review-skill
description: Use when the user asks to review code, check a diff, or enforce
  team style. Reviews against the team's style guide and returns a structured
  findings list with severity (blocker/major/minor/nit) and suggested fix.
---

# 团队代码审查 Skill

## 工作流程
1. 用 Read/Grep 读取待审文件或 `git diff` 输出
2. 按下方规则逐条比对
3. 输出结构化结果，禁止直接改代码（只给建议）

## 团队规则（必须全部检查）
- 函数体不超过 60 行
- 公共函数必须有 JSDoc/docstring
- 禁止 `any` 类型逃逸（TS 项目）
- 错误必须被捕获并记录，禁止静默吞异常
- 命名：变量/函数 camelCase，类 PascalCase，常量 UPPER_SNAKE

## 输出格式
| 严重度 | 文件:行 | 问题 | 建议修复 |
|--------|---------|------|----------|
| blocker | ... | ... | ... |

结尾给一句"通过/不通过"结论。
```

操作说明：

```bash
# 在测试项目里临时挂载验证（项目级）
mkdir -p .claude/skills && cp -r ../workdir/review-skill .claude/skills/
# 进 Claude Code 交互模式触发
claude
# 输入：帮我 review src/auth.ts
```

预期结果：Claude 在对话中主动加载该 Skill 的指令，按表格格式输出审查结果，末尾给通过/不通过结论。

常见问题：
- **不触发？** description 写得太宽泛（如"help with code"）。修法：用"Use when …"句式，列出具体触发动词与场景，参考官方 skills 文档对 description 的要求。
- **`name` 字段缺失？** Claude Code 会回退用目录名作为调用名，但混用容易出问题。始终显式写 `name`，且必须是 kebab-case（小写、连字符），不能含空格、不能含大写字母——这是官方校验器会卡的硬规则。
- **被项目里同名 Skill 覆盖了？** 记住第 0 步的优先级表，排查时把项目 `.claude/skills/` 里的同名项暂时移走再测。

## 第 2 步：把 Skill 装进 Plugin 的目录骨架

Plugin 是一个带清单文件的目录，能同时打包 skills、commands、agents、hooks、甚至 MCP 服务器配置。本例只放一个 skill，但目录结构要按"可扩展"来摆。

```
plugins/
└── review-skill/
    ├── .claude-plugin/
    │   └── plugin.json        # 插件清单（strict 模式必需）
    └── skills/
        └── review-skill/
            └── SKILL.md       # 第 1 步写好的 Skill
```

把第 1 步的 `SKILL.md` 原样放进 `skills/review-skill/`，然后在 `.claude-plugin/plugin.json` 写清单：

```json
{
  "name": "review-skill",
  "version": "1.0.0",
  "description": "团队统一代码风格审查 Skill，输出结构化 findings 与严重度。",
  "author": {
    "name": "Platform Team",
    "url": "https://github.com/myteam"
  },
  "homepage": "https://github.com/myteam/claude-marketplace",
  "keywords": ["review", "style", "quality"],
  "license": "MIT"
}
```

字段说明：`name` 必须与目录名一致且 kebab-case；`version` 用语义化版本，后续升级全靠它驱动；`description` 会显示在 `/plugin` 浏览器里，写清楚一句话用途。

验证清单合法性：

```bash
claude plugin validate plugins/review-skill
```

预期结果：返回 OK / 无错误。常见问题：
- **报错 "name must be kebab-case"**：name 含大写或下划线，改成全小写连字符。
- **报错找不到 plugin.json**：路径写成了 `plugins/review-skill/`，但 `.claude-plugin/plugin.json` 没建。注意是双层目录 `.claude-plugin/`。
- **version 写成了 "v1"**：必须是 `MAJOR.MINOR.PATCH` 三段，如 `1.0.0`。

## 第 3 步：建立团队 Marketplace 清单

Plugin 单独存在装不了——必须挂在一个 Marketplace（目录）下。Marketplace 本质是一个"插件目录的目录"，由根目录的 `.claude-plugin/marketplace.json` 定义。整个 Marketplace 就是一个 Git 仓库。

仓库结构（典型 monorepo 风格）：

```
claude-marketplace/              # 这是一个独立 Git 仓库
├── .claude-plugin/
│   └── marketplace.json
└── plugins/
    └── review-skill/            # 第 2 步做的 plugin
        ├── .claude-plugin/
        │   └── plugin.json
        └── skills/review-skill/SKILL.md
```

`.claude-plugin/marketplace.json`：

```json
{
  "name": "my-team-marketplace",
  "owner": {
    "name": "Platform Team",
    "url": "https://github.com/myteam"
  },
  "plugins": [
    {
      "name": "review-skill",
      "source": "./plugins/review-skill",
      "description": "团队统一代码风格审查 Skill",
      "version": "1.0.0"
    }
  ]
}
```

核心字段：`plugins` 数组，每项最少要有 `name` 和 `source`。`source` 是相对于仓库根的路径（也可以是另一个 Git 地址）。这里用了 **strict 模式**——每个 plugin 有自己的 `plugin.json` 并自管组件（更清晰、更适合多 plugin 仓库）。如果不想为每个 plugin 建清单，也可以在 marketplace.json 里用非 strict 模式直接内联组件定义，但团队场景推荐 strict。

把这个仓库 push 到团队可读的 Git 远端，记下 URL，例如 `https://github.com/myteam/claude-marketplace`。

常见问题：
- **marketplace.json 与 plugin.json 的 `name` 重复了**：没错，这是正常的——一个指 marketplace 里的条目名，一个指插件本身。但两者**必须相同**，否则安装报错。
- **source 路径写错**：用绝对思维容易写成 `/plugins/...`，规范是相对仓库根的 `./plugins/...`。
- **Git 私有仓库**：只要安装者有 SSH token 或 PAT 读取权限即可，Claude Code 用本地 git 凭据拉取，无需额外配置。

## 第 4 步：全员一键安装

现在任何团队成员，只需在装有 Claude Code 的机器上执行两步：

```bash
# 1) 注册团队市场（一次性）
claude plugin marketplace add myteam https://github.com/myteam/claude-marketplace

# 2) 安装插件
claude plugin install review-skill@myteam
```

预期结果：Claude Code 拉取仓库、解析清单、把 plugin 落到本地缓存，并在会话里激活该 Skill。装完用 `claude plugin list` 可见。

交互模式下也能图形化操作：

```
/plugin
```

会打开插件浏览器，能看到 marketplace 里的插件列表、描述、版本，点选安装。适合不熟命令行的同事。

安装范围控制（重要）：

```bash
# 装到当前项目（随 .claude 跟着 Git 走，团队仓库里人人自动有）
claude plugin install review-skill@myteam --scope project

# 装到个人全局（只影响你自己所有项目，默认）
claude plugin install review-skill@myteam --scope personal
```

实战建议：**团队规约类 Skill（代码风格、提交规范、Reviewer）用 `--scope project` 安装并提交 `.claude/settings.json`，让仓库本身自带审查能力，新人 clone 即生效**；个人偏好类 Skill 才用 personal。

常见问题：
- **`install` 报 "marketplace not found"**：marketplace `add` 的名字与 install 时 `@` 后的名字不一致，或 add 没成功。先 `claude plugin marketplace list` 确认。
- **拉取超时/403**：私有仓库权限问题，确认本机能 `git clone` 该仓库。
- **装上了但不触发**：回到 SKILL.md 的 description 调优；插件级 Skill 优先级最低，若你项目里同名覆盖了它，移除项目级副本。

## 第 5 步：版本演进、升级、卸载

分发的价值在于可演进。改了 Skill 后：

```bash
# 1) 改 plugin.json 的 version，如 1.0.0 -> 1.1.0
# 2) commit & push 到 marketplace 仓库
# 3) 团队成员升级
claude plugin marketplace update myteam        # 拉最新目录清单
claude plugin install review-skill@myteam      # 重装即升级到新版本
```

卸载与清理：

```bash
claude plugin uninstall review-skill
claude plugin marketplace remove myteam         # 不再信任该市场
```

版本策略建议：Skill 行为兼容性增强用 MINOR（1.1.0）；触发逻辑/输出格式破坏性变更用 MAJOR（2.0.0）并在 commit 里写清迁移说明。因为 Claude Code 会按 marketplace.json 里的 version 提示更新，团队升级意愿高度依赖你 version 号是否"诚实地"反映破坏性。

## 实战案例：一个完整的团队风格审查插件

把上述步骤串成一个完整可复现的项目。目标：团队所有 PR 在合并前由 Claude 按 `review-skill` 自动审查，且新人 clone 仓库即可用，零额外文档。

完整目录树：

```
claude-marketplace/                        # Git 仓库
├── .claude-plugin/
│   └── marketplace.json
└── plugins/
    └── review-skill/
        ├── .claude-plugin/
        │   └── plugin.json
        └── skills/
            └── review-skill/
                └── SKILL.md
```

`marketplace.json` 用第 3 步的版本。`plugin.json` 用第 2 步的版本。`SKILL.md` 用第 1 步的版本。

上线流程一键脚本（团队 README 里放这一段即可）：

```bash
#!/usr/bin/env bash
set -e

# 注册团队市场（已注册可跳过）
claude plugin marketplace add myteam \
  https://github.com/myteam/claude-marketplace || true

# 按项目范围安装，让仓库自带审查能力
claude plugin install review-skill@myteam --scope project

echo "✅ review-skill 已就绪，可用 /plugin 查看或直接对话触发"
```

把 `.claude/settings.local.json` 里的安装记录纳入版本控制（或用 `--scope project` 让配置写入 `.claude/settings.json` 提交），新人 clone 后跑一次上述脚本即可。之后在 Claude Code 里说"审查当前 diff"就自动走团队规则。

升级循环：维护者改 Skill → bump plugin.json version → push → 团队成员 `claude plugin marketplace update myteam && claude plugin install review-skill@myteam`。整个生命周期与 Git 绑定，再无"你装的版本不对"。

## 整体工作流程图

```mermaid
flowchart TD
    A["写 SKILL.md<br/>name + description"] --> B["本地 .claude/skills/<br/>验证触发与输出"]
    B --> C["打包成 Plugin<br/>.claude-plugin/plugin.json"]
    C --> D["放进 Marketplace 仓库<br/>.claude-plugin/marketplace.json"]
    D --> E["push 到团队 Git"]
    E --> F["成员: marketplace add"]
    F --> G["成员: plugin install<br/>--scope project/personal"]
    G --> H{"运行时优先级仲裁"}
    H -->|"项目级 .claude/skills/"| I["最高: 覆盖一切"]
    H -->|"个人级 ~/.claude/skills/"| J["中"]
    H -->|"插件级 plugin"| K["最低"]
    I & J & K --> L["触发 Skill, 执行指令"]
    C --> M["改 Skill → bump version → push"]
    M --> N["团队 marketplace update + reinstall"]
    N --> L
```

这张图同时表达了两条流：**首发分发流**（A→…→L）和**持续演进流**（M→N→L）。优先级仲裁那一层是很多团队踩坑的根源——记住"插件级最低"，意味着任何项目都能用本地副本覆盖团队统一 Skill，这正是"统一与定制并存"的关键。

## 进阶：Plugin 不止能装 Skill

既然已经走通了 Plugin 分发，值得知道 plugin.json 同一目录下还能并排放哪些组件，让一个市场摊位承载一整套能力：

- `commands/` —— 自定义斜杠命令（`.md` 文件，带 frontmatter）
- `agents/` —— 子智能体定义（专家团队）
- `hooks/hooks.json` —— 钩子（PreToolUse / PostToolUse 等确定性护栏）
- `mcp.json` —— 自动注册的 MCP 服务器配置

例如团队可以发一个 `dev-standards` 插件，同时打包：review-skill（审查）+ `/lint` 命令 + PreToolUse hook（禁止直接写 `.env`）+ 一个只读数据库 MCP。一次 `plugin install dev-standards@myteam`，整套研发规范落地。这才是 Plugin 相比裸 Skill 的真正杠杆——**它是能力集合的分发单元，不是单个文件**。

## 延伸阅读

- 想把命令、hooks、MCP 也打进同一个插件：补"Plugin 多组件打包"与"MCP 三种传输模式横评"。
- 想做插件的安全审计：参考"Skill 权限真相：allowed-tools 不是白名单"与"Skill 注入攻防红队实战"，分发前务必审 description 与 hooks。
- 想用代码自动生成插件骨架：`skill-creator` 是官方的元技能，可一键产出 SKILL.md + 目录结构，再套本教程的打包流程。

## 训练营适用性评估

- **企业内训 / 研发效能训练营**：高度契合，4–6 课时。前 2 课时讲优先级与打包，2 课时做团队 marketplace 实操，最后用真实仓库跑通 install + 升级循环。产出物是团队自己的 Git 市场，可立即投产。
- **AI 编程训练营（中级以上）**：适合作为"工程化"模块的压轴章节，2–3 课时。前置要求学员已写过至少一个 SKILL.md。
- **零基础入门营**：不建议。本教程假设已掌握 Skill 创作与 Git 基础，初学者会卡在 frontmatter 触发与 JSON 校验上。
- 预计教学时长：纯讲授 90 分钟，含动手实操 3 小时，含团队联调上线半天。

## 参考来源

1. [Create and distribute a plugin marketplace — Claude Code Docs](https://code.claude.com/docs/en/plugin-marketplaces) — 官方市场分发文档，strict 模式与 marketplace.json 规范权威来源
2. [Extend Claude with skills — Claude Code Docs](https://code.claude.com/docs/en/skills) — 官方 Skills 文档，name/description frontmatter 与触发机制说明
3. [How to Install Skills in Claude Code: 3 Methods](https://dev.to/samuel_rose_b30991db2b25b/how-to-install-skills-in-claude-code-3-methods-2ofl) — 个人级 `~/.claude/skills/`、项目级、插件级三种安装路径对比
4. [marketplace.json Schema and Plugin Types — DeepWiki](https://deepwiki.com/anthropics/claude-plugins-community/2.1-marketplace.json-schema-and-plugin-types) — marketplace.json 的 plugins 数组与 name/source 最小字段解析
5. [Claude Code Plugin Marketplace: A Deep Dive](https://ice-ice-bear.github.io/posts/2026-04-03-claude-code-plugin-marketplace/) — 2026 年技术深度拆解，含打包、Git 分发与团队共享完整链路

> [!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)