把一个只在本地好用的 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 里有三个"栖息地"，它们的优先级决定了谁能覆盖谁。这是后续所有分发决策的底层逻辑。

关键规则：项目级 > 个人级 > 插件级。这意味着同名 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 内容：

---
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 | ... | ... | ... |

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

操作说明：

# 在测试项目里临时挂载验证（项目级）
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 写清单：

{
  "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 浏览器里，写清楚一句话用途。

验证清单合法性：

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：

{
  "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 的机器上执行两步：

# 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 里的插件列表、描述、版本，点选安装。适合不熟命令行的同事。

安装范围控制（重要）：

# 装到当前项目（随 .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 后：

# 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      # 重装即升级到新版本

卸载与清理：

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 里放这一段即可）：

#!/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 绑定，再无"你装的版本不对"。

整体工作流程图

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 — 官方市场分发文档，strict 模式与 marketplace.json 规范权威来源
2. Extend Claude with skills — Claude Code Docs — 官方 Skills 文档，name/description frontmatter 与触发机制说明
3. How to Install Skills in Claude Code: 3 Methods — 个人级 ~/.claude/skills/、项目级、插件级三种安装路径对比
4. marketplace.json Schema and Plugin Types — DeepWiki — marketplace.json 的 plugins 数组与 name/source 最小字段解析
5. Claude Code Plugin Marketplace: A Deep Dive — 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 等场景全覆盖。