大家好，我是讯享网，很高兴认识大家。这里提供最前沿的Ai技术和互联网信息。



Plugin 是 Claude Code 的扩展包——把 Commands、Skills、Hooks、MCP 配置打包成一个可安装、可分享、可自动更新的整体。

类比理解：

核心价值：

很多人问：“我已经有 Commands 和 Skills 了，为什么还要 Plugin？”

一张表说清楚：

关键区别：Plugin 是一个“超集”概念——Plugin = Commands + Skills + Hooks + MCP 配置 + 文档，打包成一个可以一键安装和分享的整体。

何时用什么？决策指南：

• Commands：项目内简单重复任务（如 /format-code）——够用就行，别上 Plugin
• Skills：项目内复杂专业任务（如代码注释生成）——能力需要积累和复用
• MCP：需要调用外部服务（如 GitHub API、数据库）——解决连接问题
• Plugins：✅ 想分享给团队或社区的任何功能——打包分发的**选择

三大 Marketplace：

热门 Plugin 分类速查：

说明：document-skills 是 Anthropic 官方出品的文档处理套件（来自 anthropics/skills 源），安装后包含 document-skills:pdf、document-skills:pptx、document-skills:xlsx 等多个 Skill，一次安装全部可用。

# 1. 确认 Claude Code 版本（需 v2.1+） claude --version # 2. 确认在项目目录中 cd /path/to/your/project

Plugin 功能于 2025 年 10 月 9 日随 Claude Code v2.1 发布。如果版本过低，先升级。

方式一：对话内 /plugin 命令（最方便）

在 Claude Code 对话中直接输入：

/plugin

会进入 Plugin 管理界面，切换到 Marketplace 标签页即可浏览所有可用 Plugin。

方式二：CLI 命令

# 添加社区 Marketplace 源（第一次用需要先添加） claude plugin marketplace add anthropics/skills # 查看已添加的 Marketplace 源 claude plugin marketplace list

添加成功后，就能从该源浏览和安装 Plugin 了。

实战：添加 Marketplace 源并安装 Plugin

以添加 VoltAgent Subagent 代理库为例，完整流程：

# 1. 添加 Marketplace 源 claude plugin marketplace add VoltAgent/awesome-claude-code-subagents

# 2. 从该源安装你需要的 Plugin claude plugin install 
  
    
    

或者在对话中输入 /plugin，切换到 Installed 界面自行浏览安装。

网络问题？ 如果安装过程中遇到超时或下载失败，需要检查代理软件配置：

# Windows PowerShell（根据自己的代理端口修改） $env:HTTP_PROXY = "http://127.0.0.1:7897" $env:HTTPS_PROXY = "http://127.0.0.1:7897"

# macOS / Linux export HTTP_PROXY="http://127.0.0.1:7897" export HTTPS_PROXY="http://127.0.0.1:7897"

方式三：Web 浏览器

直接访问官方 Marketplace 网页：https://code.claude.com/plugins

在 Claude Code 对话中输入 /plugin，进入图形化管理界面。界面顶部有四个标签页，覆盖所有管理场景：

界面导航：↑↓ 上下移动，空格 快速安装/切换，回车 进入详情，ESC 返回上级

打开 /plugin，默认进入 Discover 标签页，列出所有已添加 Marketplace 源中的可用 Plugin。

安装步骤：

1. 用 ↑↓ 移动光标，选中想安装的 Plugin
2. 按回车查看详情（或直接按空格快速安装）
3. 在详情页选择安装范围，确认安装

安装范围说明：

三种安装来源：

找不到想装的 Plugin？ 先去 Marketplaces 标签页添加对应的源，再回 Discover 刷新列表。

切换到 Installed 标签页，查看所有已启用的 Plugin。

列表中同时显示 Plugin 系统安装的扩展和 MCP 连接，每条显示名称、版本和状态。

更新 / 禁用 / 卸载操作：

选中某个 Plugin，按回车进入详情，可执行以下操作：

自动更新：Claude Code 启动时会自动检查所有 Plugin 更新，无需手动触发。

切换到 Marketplaces 标签页，管理 Plugin 的来源。

界面列出所有已添加的 Marketplace 源，每个源显示可用 / 已安装的 Plugin 数量，以及最后更新时间。

添加新 Marketplace 源：

1. 在 Marketplaces 标签页选择“添加源”
2. 输入源地址（格式：用户名/仓库名）
3. 确认添加后，Discover 标签页自动同步新来源的 Plugin

推荐 Marketplace 源：

Marketplace 源详情示例（anthropics/skills）：

anthropic-agent-skills (anthropics/skills) 3 available · 1 installed · Updated 2026/3/6   ✅ document-skills (installed)    Collection of document processing suite including Excel...   ○  example-skills    Collection of example skills demonstrating various capabi...

推荐先装：document-skills（官方文档处理套件），安装后自动获得 pdf、pptx、xlsx 等全套 Skill，一次搞定所有文档格式。

Plugin 本质上是一个目录，里面有个 .claude-plugin/plugin.json 清单文件，加上你要打包的各种能力。

最小结构（一个 Skill）：

my-plugin/ ├── .claude-plugin/ │ └── plugin.json    # 必需：Plugin 清单 └── skills/ └── my-skill/       └── SKILL.md

完整结构（所有能力）：

my-plugin/ ├── .claude-plugin/ │ └── plugin.json    # 必需：Plugin 清单（只有这个在 .claude-plugin/ 内） ├── README.md          # 推荐：使用文档 ├── LICENSE             # 推荐：开源协议 ├── skills/             # 可选：Agent Skills │ └── my-skill/ │    └── SKILL.md ├── commands/          # 可选：Slash Commands │ └── my-command.md ├── agents/             # 可选：自定义 Agent 定义 ├── hooks/             # 可选：事件钩子 │ └── hooks.json ├── .mcp.json          # 可选：MCP 服务配置 └── settings.json       # 可选：Plugin 启用时的默认设置

⚠️ 常见踩坑：commands/、skills/、agents/、hooks/ 都放在插件根目录，不要放进 .claude-plugin/ 里——那里只放 plugin.json。

各目录职责速查：

plugin.json 放在 .claude-plugin/ 目录下，是 Plugin 的「身份证」。

完整示例：

{   "name": "my-awesome-plugin",   "description": "一句话说明这个 Plugin 做什么",   "version": "1.0.0",   "author": { "name": "Your Name"   },   "license": "MIT",   "homepage": "https://github.com/yourname/my-plugin",   "repository": "https://github.com/yourname/my-plugin" }

字段速查：

关键点：name 字段决定了 Skill 的调用前缀。Plugin 名叫 my-plugin，里面的 hello Skill 就要用 /my-plugin:hello 来触发——命名空间设计防止多个 Plugin 的 Skill 名称冲突。

5 分钟从零创建并测试你的第一个 Plugin：

Step 1：创建目录结构

mkdir -p hello-plugin/.claude-plugin mkdir -p hello-plugin/skills/hello

Step 2：创建清单 .claude-plugin/plugin.json

{   "name": "hello-plugin",   "description": "一个简单的问候示例 Plugin",   "version": "1.0.0",   "author": { "name": "Your Name"   },   "license": "MIT" }

Step 3：创建 Skill skills/hello/SKILL.md

--- description: Greet the user with a friendly message --- 用友好的方式向用户打招呼。 步骤： 1. 获取当前系统时间 2. 根据时间段（上午/下午/晚上）调整问候语 3. 用轻松愉快的语气回复 示例输出： "早上好！现在是 10:23，新的一天，有什么我能帮你的？"

Step 4：本地测试

不需要安装，直接用 --plugin-dir 标志加载：

# 加载插件并启动 Claude Code claude --plugin-dir ./hello-plugin # 启动后在对话里输入（注意命名空间格式） > /hello-plugin:hello

看到问候输出，第一个 Plugin 就跑通了！

--plugin-dir 是开发专用标志，每次修改 Skill 后重启 Claude Code 即可生效，无需安装。要同时测试多个 Plugin，可以多次指定：claude --plugin-dir ./plugin-a --plugin-dir ./plugin-b

Step 5：带参数的 Skill

$ARGUMENTS 占位符可以捕获用户输入的文本，让 Skill 动态响应：

--- description: Greet the user with a personalized message --- 用友好的方式向名叫 "$ARGUMENTS" 的用户打招呼，让问候更有温度。

重启后测试：

> /hello-plugin:hello 凯神 # Claude 会用你传入的名字问候

创建一个代码质量检查 Plugin，演示 Skill + Commands 的组合威力：

项目结构：

code-quality-checker/ ├── .claude-plugin/ │ └── plugin.json ├── README.md ├── skills/ │ └── code-review/ │    └── SKILL.md └── commands/ └── check.md

.claude-plugin/plugin.json：

{   "name": "code-quality-checker",   "description": "自动检查代码质量，按严重程度给出改进建议",   "version": "1.0.0",   "author": { "name": "Your Name" },   "license": "MIT" }

skills/code-review/SKILL.md：

--- description: Reviews code for best practices, security issues, and quality problems. Use when reviewing code, checking PRs, or analyzing code quality. --- # 代码质量检查专家 角色定义 你是一位资深代码审查专家，擅长发现代码质量问题并给出具体改进建议。 检查维度 1.  命名规范：变量名/函数名是否语义清晰 2.  函数复杂度：单个函数是否过长或嵌套过深 3.  重复代码：是否存在可抽取的重复逻辑 4.  错误处理：异常边界是否覆盖 5.  安全隐患：是否存在注入/XSS 等风险 输出格式 按严重程度排序： - 🔴 严重：必须修复 - 🟡 警告：建议修复 - 🟢 建议：可以改进 每条包含：问题描述 + 代码位置 + 修复建议

commands/check.md：

对指定代码进行质量检查。 参数：$ARGUMENTS（可选，指定检查的文件路径） 步骤： 1. 如果指定了文件路径，只检查该文件 2. 如果未指定，检查最近修改的文件（通过 git diff --name-only 获取） 3. 按 5 个维度逐项分析，输出分级报告

测试：

claude --plugin-dir ./code-quality-checker # 触发 Skill（自动识别） > 帮我检查这段代码的质量 # 显式调用命令（注意命名空间） > /code-quality-checker:check src/app.ts

Plugin 的「超集」威力在这里体现得很清楚：Commands 提供触发入口，Skills 提供专业能力，打包在一起就是可分享的完整工具。

1. 先用独立配置，再转 Plugin

2. 语义化版本号

版本号格式：主.次.补丁（如 1.2.3）   - 主版本（1.x.x）：破坏性变更，不向后兼容   - 次版本（x.2.x）：新增功能，向后兼容   - 补丁版（x.x.3）：Bug 修复

3. README 必须包含四个部分

4. Skill description 是关键

SKILL.md frontmatter 中的 description 决定 Claude 能否自动识别场景并激活 Skill：

# ❌ 太模糊，自动激活不准 description: Code review tool # ✅ 明确触发场景，自动识别准确 description: Reviews code for best practices and potential issues. Use when reviewing code, checking PRs, or analyzing code quality.

必须完成：

• ✅ .claude-plugin/plugin.json 格式正确，name/description/version 填写完整
• ✅ README.md 包含安装和使用说明（含 Skill 调用格式 /插件名:skill名）
• ✅ LICENSE 文件存在（推荐 MIT）
• ✅ 用 claude --plugin-dir . 本地测试通过，所有 Skill 和命令正常工作

推荐完成：

• ⭐ CHANGELOG.md 记录每个版本的变更内容
• ⭐ GitHub 仓库添加 Topics 标签（如 claude-code-plugin），便于被搜索
• ⭐ README 中注明最低 Claude Code 版本要求

# 1. 初始化仓库 cd my-plugin git init git add . git commit -m “feat: initial release v1.0.0” # 2. 推送到 GitHub git remote add origin https://github.com/yourname/my-plugin.git git branch -M main git push -u origin main

创建 Release（让别人能按版本安装）：

1. 进入 GitHub 仓库页面，点击 Releases → Draft a new release
2. Tag version 填 v1.0.0（必须以 v 开头）
3. 填写本次发布说明
4. 点击 Publish release

发布后，其他人就能通过 GitHub URL 直接安装：

# 在 /plugin 界面的 Discover 页顶部输入 GitHub 地址安装 # 或用 CLI claude plugin install https://github.com/yourname/my-plugin

在 README 中加个版本徽章，一眼看出当前版本： ![Version](https://img.shields.io/github/v/release/yourname/my-plugin)

想让全球 Claude Code 用户都能搜到你的 Plugin？直接用应用内提交表单，不需要 Fork 仓库、提 PR，一个表单搞定：

提交前确认：

提交后等待 Anthropic 审核（通常 1-3 个工作日）。审核通过后，你的 Plugin 就会出现在官方 Marketplace，全球 Claude Code 用户都能一键安装。

# 网络问题？换国内镜像源 npm config set registry https://registry.npmmirror.com # 需要代理？（根据自己的代理端口修改） export HTTP_PROXY="http://127.0.0.1:7897" export HTTPS_PROXY="http://127.0.0.1:7897"

# 启用详细日志排查问题 export CLAUDE_LOG_LEVEL=debug claude –plugin-dir ./my-plugin

Q1：Plugin 和 Skill 到底啥区别？

一句话：Skill 是能力本身，Plugin 是把能力打包成可安装、可分享的形式。 Plugin 可以包含 Skill，也可以包含 Commands、Hooks、MCP 配置等。

Q2：Plugin 更新会覆盖我的配置吗？

不会。更新时保留你的 config.json（个人配置），只更新 Plugin 代码文件（skills/、commands/ 等）。

Q3：Plugin 开发需要懂编程吗？

Q4：Plugin 可以离线使用吗？

安装在本地的 Plugin 可以离线使用。但如果 Plugin 内部调用了外部 API（如 GitHub API），那部分功能需要联网。

Q5：Plugin 支持哪些编程语言？

Q6：如何查看 Plugin 使用了多少 Token？

可以通过 /cost 命令查看整体 Token 消耗。Plugin 本身不单独计费，Token 消耗取决于 Plugin 加载的提示词量和对话内容。

Q7：可以同时安装多个版本的 Plugin 吗？

不可以。同一个 Plugin 只能安装一个版本。如果需要在不同项目使用不同版本，可以用项目级安装（默认）隔离。

Q8：Plugin 报错如何获取帮助？

1. 查看 Plugin 的 README 和 GitHub Issues
2. 在 Anthropic Discord 的 #claude-code-plugins 频道提问
3. 提 GitHub Issue 时包含：系统环境、Claude Code 版本、Plugin 版本、完整错误信息

本章你已掌握：

1. Plugin 本质：可分享的 Commands + Skills + Hooks + MCP 打包体，一键安装、自动更新
2. 核心区别：Plugin 是“超集”概念，解决了 Commands/Skills 无法便捷分享的痛点
3. 生态现状：官方 Marketplace + 社区 200+ Plugin，按需选择
4. 安装管理：/plugin 界面的 Discover / Installed / Marketplaces 三大标签页，全程图形化操作
5. 自定义开发：.claude-plugin/plugin.json 清单 + skills/ + commands/ 标准结构，–plugin-dir 秒测试
6. 发布分享：GitHub Release 发布 + 官方 Marketplace 表单提交，让全世界用上你的 Plugin

希望这份指南能帮助你充分挖掘 Claude Code 插件的潜力，无论是提升个人效率，还是为社区贡献优秀的 开源项目。更多技术深度探讨，欢迎访问 云栈社区。