你已经会写单个 SKILL.md，但把同一个 Skill 复制粘贴到十个项目、分享给三十个同事时，问题就来了：版本对不齐、触发词各写各的、更新要逐个仓库改。本教程教你把一个（或几个）Skill 升级为自包含 Plugin，通过 marketplace 一键分发、命名空间隔离、版本化更新。适合已经写过至少一个 Skill、想把能力沉淀给团队的 Claude Code 中级用户。
/plugin 命令；看不到就升级到最新版）.claude/skills/xxx/SKILL.md），理解 name / description / 渐进式披露一个人用 Skill 很爽：丢进 .claude/skills/，下次会话自动加载。但当规模上去，三个痛点同时爆发——和当年 CLAUDE.md 膨胀是同一类病：
git pull + 手动改，十几个仓库改下来人麻了。review Skill 和李四的 review Skill 名字一样，装到同一台机器上互相覆盖。Plugin 正是为这三件事设计的：它是一个带清单的目录，把 Skills / Commands / Subagents / Hooks / MCP 打包成一个整体，通过 marketplace 统一发布、带版本、靠命名空间避免冲突。一句话——Skill 是"能力"，Plugin 是"可分发的能力包"。
不是所有 Skill 都值得打包。Claude Code 官方给了清晰的判断标准：
| 维度 | 独立配置（.claude/） |
Plugin |
|---|---|---|
| 适用场景 | 个人、单项目、快速实验 | 团队共享、社区分发、跨项目复用 |
| Skill 调用名 | 短，如 /hello |
命名空间化，如 /my-plugin:hello |
| 版本管理 | 靠人工 | 清单 version 字段 + git |
| 更新方式 | 手动改文件 | /plugin marketplace update |
经验法则：先在 .claude/ 里快速迭代，等它稳定、且第二个项目也想用时，再升级成 Plugin。 别一上来就打包——大多数 Skill 死在"过度工程化"上。
假设你已经有一个"代码质量审查"Skill，原本躺在 .claude/skills/quality-review/SKILL.md。先把它复制出来作为打包的原料。
Plugin 的身份认证文件是 plugin.json，必须放在插件根目录下的 .claude-plugin/ 里。
mkdir -p quality-review-plugin/.claude-plugin
mkdir -p quality-review-plugin/skills/quality-review
创建 quality-review-plugin/.claude-plugin/plugin.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 校验报错。
这是新手翻车重灾区。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 放进去：
cp .claude/skills/quality-review/SKILL.md \
quality-review-plugin/skills/quality-review/SKILL.md
SKILL.md 内容保持你原来的，frontmatter 照旧：
---
description: Review code for bugs, security, and performance. Triggers on "review this", "code review", "check my changes".
---
# Quality Review
审查当前选中的代码或最近改动，关注：
- 潜在 bug 与边界条件
- 安全隐患
- 性能问题
- 可读性改进
输出要简洁、可执行。
不用发布就能测。两种方式：
方式 A：一次性加载（开发调试用）
claude --plugin-dir ./quality-review-plugin
启动后在会话里：
/quality-review-plugin:quality-review
看到 Claude 按你的 Skill 内容回应，说明打包成功。改完文件后用 /reload-plugins 热加载，不用重启。
方式 B：自动加载（长期开发用）
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/。
Plugin 本身只是"一个包"，要分发还需要一个目录文件 marketplace.json，告诉 Claude Code 这里有哪些 Plugin、各自从哪取。它放在仓库根目录的 .claude-plugin/ 里。
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：
{
"name": "company-tools",
"owner": { "name": "DevTools Team", "email": "[email protected]" },
"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。
本地测试安装（分发前的最后一关）：
/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 |
光说不练假把式。下面这个案例把"质量审查"做成一个包含 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{
"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---
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）{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{ "type": "command", "command": "npx --no-install lint-staged || true" }
]
}
]
}
}
agents/deep-review.md（隔离上下文的子代理）---
name: deep-review
description: Performs an exhaustive review of complex changes in an isolated context, returning a structured report.
tools: Read, Grep, Glob, Bash
---
你是一个资深代码审查专家。对给定改动做深度分析，重点关注架构影响、回归风险、
并发与时序问题。输出结构化报告：**确认问题** / **可疑项** / **改进建议**。
不修改任何文件，只读分析。
# 1. 推到 GitHub
git init && git add . && git commit -m "release quality-review-plugin 1.2.0"
git remote add origin [email protected]: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 给不了的。
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
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
skills/ 被错放进 .claude-plugin/。记住只有 plugin.json 住那儿。../shared-utils 找不到" → Plugin 安装时被整体复制到缓存，无法访问目录外的文件。需要跨插件共享就用 symlink。claude-*、anthropic-*、agent-skills 等），换个非官方前缀。plugin.json bump version，或用户没跑 /plugin marketplace update。/a:review vs /b:review），但描述太像会让模型纠结触发哪个——靠 description 写清边界。disable-model-invocation: true，变成纯命令式 Skill。plugin 少了 s），或 source 类型不匹配。用 $schema 字段接上 JSON Schema 拿到编辑器校验提示。code.claude.com/docs/en/plugins 的 "Plugins reference" 页，含全部 manifest 字段（homepage / repository / license 等）与 LSP / background monitors 高级组件metadata.pluginRoot）、容器内预装插件、strict mode——都在 plugin-marketplaces 文档后半段.claude/ 一键转 Plugin 的迁移步骤claude-plugins-community（官方保留名对应的社区目录）里别人怎么组织多 Plugin 仓库，是最好的结构范本| 训练营类型 | 适用性 | 说明 |
|---|---|---|
| 企业内训（研发团队） | ★★★★★ | 最匹配。直接产出团队内部 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/ 里"这个关键陷阱。
--plugin-dir 与 claude plugin init 本地测试流程[!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 等场景全覆盖。