Claude Code Plugins生态完整指南：从安装到自定义开发

Claude Code Plugins生态完整指南：从安装到自定义开发 Claude Code Plugins生态完整指南：从安装到自定义开发 Modified June 10 Code block Plain Text ✅ 所有命令和Skills已测试通过 ✅ 无硬编码密钥或敏感信息 ✅ .gitignore 排除了不必要的文件 ✅ LICENSE 文件存在 ⠀ 5.2 发布到GitHub ⠀ Code block Plain Text 初始化git仓库 cd my plugin git init git add A git commit m "feat: initial release v1.0.0" 创建GitHub仓库并推送 gh repo create my plugin public source=. push 打版本标签 git tag v1.0.0 git push tags ⠀ 推荐的GitHub仓库设置： ⠀ • 添加 Topics：claude code plugin、claude code、ai plugin • 写清楚 Description • 添加 claude code plugin topic 方便社区搜索发现 ⠀ 5.3 分享到社区 ⠀ 1. 提交到 claude code plugins plus： ◦ Fork jeremylongshore/claude code plugins plus ◦ 添加你的Plugin信息 ◦ 提交PR 2. 在GitHub Discussions分享： ◦ 到 anthropics/claude code 的 Discussions 板块分享 3. 提交到官方Marketplace： ◦ 访问 code.claude.com/plugins 查看提交指南 ◦ 需要通过官方审核第6章：故障排查指南 ⠀ 6.1 Plugin加载失败 ⠀ 症状： plugin dir 指定后，Plugin的命令/Skills没有生效 ⠀ 排查步骤： ⠀ Code block Plain Text 1. 确认路径正确 ls /path/to/your/plugin/.claude plugin/plugin.json 2. 验证plugin.json格式 cat /path/to/your/plugin/.claude plugin/plugin.json | python3 m json.tool 3. 使用debug模式启动 claude plugin dir /path/to/your/plugin debug ⠀ 6.2 命令不显示 ⠀ 可能原因： ⠀ 原因解决方案 commands目录路径错误确认在Plugin根目录下有 commands/ 目录命令文件不是.md格式命令文件必须是 .md 后缀 .claude plugin/plugin.json 缺失确认Plugin根目录下有 .claude plugin/plugin.json 文件权限问题确认文件可读：chmod 644 commands/ .md ⠀ 6.3 Skills不生效 ⠀ 排查： ⠀ Code block Plain Text 确认SKILL.md存在且格式正确 cat /path/to/plugin/skills/my skill/SKILL.md 确认frontmatter格式必须以开头和结尾，包含name和description ⠀ 6.4 多Plugin冲突 ⠀ 如果多个Plugin定义了同名命令： ⠀ Code block Plain Text 后加载的Plugin会覆盖先加载的调整 plugin dir 的顺序来控制优先级 claude plugin dir ./plugin low priority plugin dir ./plugin high priority 第7章：FAQ（常见问题） ⠀ Q1：Plugin和Skill有什么区别？ ⠀ Skill 是单个能力定义（一个SKILL.md文件），Plugin 是一个完整的扩展包，可以包含多个Skills + Commands + Hooks + MCP配置。Plugin是Skill的超集。 ⠀ Q2：有没有 claude plugins install 命令？ ⠀ Claude Code 现在同时提供两类入口： 1. 交互模式里的 /plugin 2. CLI 里的 claude plugin（别名 claude plugins） ⠀ 日常使用更推荐 /plugin，本地开发和自动化更常用 claude plugin ... 或 plugin dir。 ⠀ Q3：Plugin会访问我的代码吗？ ⠀ Plugin中的Skills和Commands在Claude Code的沙箱中运行，遵循与内置工具相同的权限模型。Plugin不能绕过权限系统。 ⠀ Q4：如何更新Plugin？ ⠀ Code block Plain Text cd .claude/plugins/my plugin git pull origin main ⠀ 下次启动Claude Code时会自动加载最新版本。 ⠀ Q5：如何卸载Plugin？ ⠀ Code block Plain Text 删除Plugin目录 rm rf .claude/plugins/my plugin 启动时不再指定该 plugin dir 即可 ⠀ Q6：可以同时加载多少个Plugin？ ⠀ 没有硬性限制，但每个Plugin都会增加上下文占用。建议同时加载不超过5个Plugin，按需加载。 ⠀ Q7：Plugin开发需要懂编程吗？ ⠀ 不一定。最简单的Plugin只需要写Markdown文件（Commands和Skills都是Markdown）。只有需要Hooks（自动化脚本）时才需要编程能力。 ⠀ Q8：Plugin可以离线使用吗？ ⠀ 可以。Plugin是本地文件，加载后不需要网络。但如果Plugin包含MCP配置连接外部服务，那部分功能需要网络。 ⠀ Q9：如何让Plugin在所有项目中生效？ ⠀ Code block Plain Text 方法1：每次启动时指定 claude plugin dir /.claude/global plugins/my plugin 方法2：设置shell别名 alias claude='claude plugin dir /.claude/global plugins/my plugin' ⠀ Q10：Plugin报错如何获取帮助？ ⠀ 1. 查看Plugin的GitHub Issues 2. 使用 claude debug 查看详细日志 3. 检查Plugin的README中的Troubleshooting部分 🔗 相关链接 ⠀ 资源链接说明上一节 07 Skills定制完整指南创建可复用功能包 code.claude.com/plugins ⠀ 5.2 发布到GitHub ⠀ ⠀ 推荐的GitHub仓库设置： ⠀ • 添加 Topics：claude code plugin、claude code、ai plugin • 写清楚 Description • 添加 claude code plugin topic 方便社区搜索发现 ⠀ 5.3 分享到社区 ⠀ 1. 提交到 claude code plugins plus： ◦ Fork jeremylongshore/claude code plugins plus ◦ 添加你的Plugin信息 ◦ 提交PR ◦ Fork jeremylongshore/claude code plugins plus ◦ 添加你的Plugin信息 ◦ 提交PR 2. 在GitHub Discussions分享： ◦ 到 anthropics/claude code 的 Discussions 板块分享 ◦ 到 anthropics/claude code 的 Discussions 板块分享 3. 提交到官方Marketplace： ◦ 访问 code.claude.com/plugins 查看提交指南 ◦ 需要通过官方审核 code.claude.com/plugins ◦ 访问 code.claude.com/plugins 查看提交指南 code.claude.com/plugins ◦ 需要通过官方审核第6章：故障排查指南 ⠀ 6.1 Plugin加载失败 ⠀ 症状： plugin dir 指定后，Plugin的命令/Skills没有生效 ⠀ 排查步骤： ⠀ ⠀ 6.2 命令不显示 ⠀ 可能原因： ⠀ 原因解决方案 commands目录路径错误确认在Plugin根目录下有 commands/ 目录命令文件不是.md格式命令文件必须是 .md 后缀 .claude plugin/plugin.json 缺失确认Plugin根目录下有 .claude plugin/plugin.json 文件权限问题确认文件可读：chmod 644 commands/ .md 原因原因解决方案解决方案 commands目录路径错误 commands目录路径错误确认在Plugin根目录下有 commands/ 目录确认在Plugin根目录下有 commands/ 目录命令文件不是.md格式命令文件不是.md格式命令文件必须是 .md 后缀命令文件必须是 .md 后缀 .claude plugin/plugin.json 缺失 .claude plugin/plugin.json 缺失确认Plugin根目录下有 .claude plugin/plugin.json 确认Plugin根目录下有 .claude plugin/plugin.json 文件权限问题文件权限问题确认文件可读：chmod 644 commands/ .md 确认文件可读：chmod 644 commands/ .md ⠀ 6.3 Skills不生效 ⠀ 排查： ⠀ ⠀ 6.4 多Plugin冲突 ⠀ 如果多个Plugin定义了同名命令： ⠀ 第7章：FAQ（常见问题） ⠀ Q1：Plugin和Skill有什么区别？ ⠀ Skill 是单个能力定义（一个SKILL.md文件），Plugin 是一个完整的扩展包，可以包含多个Skills + Commands + Hooks + MCP配置。Plugin是Skill的超集。 ⠀ Q2：有没有 claude plugins install 命令？ ⠀ Claude Code 现在同时提供两类入口： 1. 交互模式里的 /plugin 2. CLI 里的 claude plugin（别名 claude plugins） ⠀ 日常使用更推荐 /plugin，本地开发和自动化更常用 claude plugin ... 或 plugin dir。 ⠀ Q3：Plugin会访问我的代码吗？ ⠀ Plugin中的Skills和Commands在Claude Code的沙箱中运行，遵循与内置工具相同的权限模型。Plugin不能绕过权限系统。 ⠀ Q4：如何更新Plugin？ ⠀ ⠀ 下次启动Claude Code时会自动加载最新版本。 ⠀ Q5：如何卸载Plugin？ ⠀ ⠀ Q6：可以同时加载多少个Plugin？ ⠀ 没有硬性限制，但每个Plugin都会增加上下文占用。建议同时加载不超过5个Plugin，按需加载。 ⠀ Q7：Plugin开发需要懂编程吗？ ⠀ 不一定。最简单的Plugin只需要写Markdown文件（Commands和Skills都是Markdown）。只有需要Hooks（自动化脚本）时才需要编程能力。 ⠀ Q8：Plugin可以离线使用吗？ ⠀ 可以。Plugin是本地文件，加载后不需要网络。但如果Plugin包含MCP配置连接外部服务，那部分功能需要网络。 ⠀ Q9：如何让Plugin在所有项目中生效？ ⠀ ⠀ Q10：Plugin报错如何获取帮助？ ⠀ 1. 查看Plugin的GitHub Issues 2. 使用 claude debug 查看详细日志 3. 检查Plugin的README中的Troubleshooting部分 🔗 相关链接 ⠀ 资源链接说明上一节 07 Skills定制完整指南创建可复用功能包资源资源链接链接说明说明上一节上一节 07 Skills定制完整指南 07 Skills定制完整指南创建可复用功能包创建可复用功能包下一节 09 Agent SDK完整指南编程开发AI Agent 📋 附录：速查表 ⠀ Plugin操作速查 ⠀ 操作命令安装Plugin /plugin install <name 浏览市场交互里输入 /plugin，或浏览器访问 code.claude.com/plugins 本地开发加载 claude plugin dir .claude/plugins/<name 本地加载多个 claude plugin dir ./a plugin dir ./b 更新本地克隆 cd .claude/plugins/<name && git pull 卸载本地Plugin rm rf .claude/plugins/<name 查看Plugin信息 cat .claude/plugins/<name /.claude plugin/plugin.json 开发时重载修改后重新启动会话，或重新以 plugin dir 进入调试调试Plugin claude plugin dir <path debug code.claude.com/plugins 操作操作命令命令安装Plugin 安装Plugin /plugin install <name /plugin install <name 浏览市场浏览市场交互里输入 /plugin，或浏览器访问 code.claude.com/plugins code.claude.com/plugins 交互里输入 /plugin，或浏览器访问 code.claude.com/plugins code.claude.com/plugins 本地开发加载本地开发加载 claude plugin dir .claude/plugins/<name claude plugin dir .claude/plugins/<name 本地加载多个本地加载多个 claude plugin dir ./a plugin dir ./b claude plugin dir ./a plugin dir ./b 更新本地克隆更新本地克隆 cd .claude/plugins/<name && git pull cd .claude/plugins/<name && git pull 卸载本地Plugin 卸载本地Plugin rm rf .claude/plugins/<name rm rf .claude/plugins/<name 查看Plugin信息查看Plugin信息 cat .claude/plugins/<name /.claude plugin/plugin.json cat .claude/plugins/<name /.claude plugin/plugin.json 开发时重载开发时重载修改后重新启动会话，或重新以 plugin dir 进入调试修改后重新启动会话，或重新以 plugin dir 进入调试调试Plugin 调试Plugin claude plugin dir <path debug claude plugin dir <path debug ⠀ Plugin目录结构速查 ⠀ ⠀ 💡 命名空间：Plugin中的Skills会自动添加命名空间前缀，格式为 /plugin name:skill name，避免与其他Plugin冲突。 💡 命名空间：Plugin中的Skills会自动添加命名空间前缀，格式为 /plugin name:skill name，避免与其他Plugin冲突。最后更新：2026年5月30日 | 适用版本：Claude Code v2.1.158 最后更新：2026年5月30日 | 适用版本：Claude Code v2.1.158 课程信息 ⠀ • 作者：老金 • GitHub：https://github.com/KimYx0207 • 公众号：老金带你玩AI • X（Twitter）：老金带你玩AI • 个人博客：https://aiking.dev • 预计学时：4 6小时 • 难度等级：⭐⭐ 入门级 • 更新日期：2026年5月30日 • 适用版本：Claude Code v2.1.158（验证于 2026 05 30；v2.1.90+ 插件市场 env 见文内 release 摘录） 📚 本课学习目标 ⠀ 完成本课学习后，你将能够： ⠀ 1. 理解Plugin生态：掌握Plugin与Commands/Skills/MCP的区别 2. 安装和使用Plugin：掌握当前 /plugin + market 的主路径，以及本地目录开发模式 3. 浏览Marketplace：在官方市场发现和安装 Plugin 4. 创建自定义Plugin：从零开发一个完整的Plugin包 5. 发布Plugin：将Plugin分享到GitHub和社区 6. 排查Plugin问题：独立解决90%的常见故障 🗺️ 学习路径导航（先看这里！） ⠀ 路径A：快速上手（⏱️ 30分钟） ⠀ 适合人群：急着用Plugin，想快速体验 ⠀ 只看这些章节： ⠀ ⠀ 路径B：Plugin开发者（⏱️ 3小时） ⠀ 适合人群：想创建自己的Plugin ⠀ 学习顺序： ⠀ ⠀ 路径C：问题排查（⏱️ 5分钟） ⠀ 适合人群：Plugin出问题了 ⠀ 直接跳到： ⠀ 术语表（小白必读） ⠀ 术语英文解释 Plugin Plugin Claude Code 的扩展包，可封装 agents、skills、hooks、MCP、LSP、bin、settings 等资源 Marketplace Marketplace Plugin商店，浏览和发现Plugin的网页平台 .claude plugin/plugin.json • Plugin的元数据清单文件，位于 .claude plugin/ 子目录中 plugin dir • Claude Code 启动参数，主要用于本地开发 / 调试加载指定目录 Skill Skill Plugin中的核心能力模块（SKILL.md定义） Hook Hook Plugin中的自动化触发器（如代码提交前检查）术语术语英文英文解释解释 Plugin Plugin Plugin Plugin Claude Code 的扩展包，可封装 agents、skills、hooks、MCP、LSP、bin、settings 等资源 Claude Code 的扩展包，可封装 agents、skills、hooks、MCP、LSP、bin、settings 等资源 Marketplace Marketplace Marketplace Marketplace Plugin商店，浏览和发现Plugin的网页平台 Plugin商店，浏览和发现Plugin的网页平台 .claude plugin/plugin.json .claude plugin/plugin.json • • Plugin的元数据清单文件，位于 .claude plugin/ 子目录中 Plugin的元数据清单文件，位于 .claude plugin/ 子目录中 plugin dir plugin dir • • Claude Code 启动参数，主要用于本地开发 / 调试加载指定目录 Claude Code 启动参数，主要用于本地开发 / 调试加载指定目录 Skill Skill Skill Skill Plugin中的核心能力模块（SKILL.md定义） Plugin中的核心能力模块（SKILL.md定义） Hook Hook Hook Hook Plugin中的自动化触发器（如代码提交前检查） Plugin中的自动化触发器（如代码提交前检查）第1章：Plugins生态概览 ⠀ v2.1.139→v2.1.158 插件更新：插件依赖会被强制检查；Marketplace / Browse / Details 会展示 commands、agents、skills、hooks、MCP/LSP servers、更新时间和 projected context cost；插件启用、禁用、安装、HTTPS clone 以及 root level SKILL.md 暴露都有修复。v2.1.153 起 github / git marketplace source 可用 skipLfs 跳过 Git LFS 下载；无 GitHub SSH key 的环境可用 CLAUDE CODE PLUGIN PREFER HTTPS 优先 HTTPS clone。v2.1.154 起插件可在 plugin.json 或 marketplace entry 声明 defaultEnabled: false，由用户通过 /plugin 或 claude plugin enable 显式开启；Discover tab 也会根据当前目录给出 “suggested for this directory” 推荐。v2.1.157 起 .claude/skills 目录里的插件会自动加载，无需 marketplace；claude plugin init <name 可直接脚手架新插件，/plugin 参数也会补全子命令、已安装插件和已知 marketplace 插件。企业环境还要看 pluginSuggestionMarketplaces allowlist，避免把未经允许的组织市场推荐给用户。教程中遇到插件清单差异时，以 /plugin 当前界面为准。 v2.1.139→v2.1.158 插件更新：插件依赖会被强制检查；Marketplace / Browse / Details 会展示 commands、agents、skills、hooks、MCP/LSP servers、更新时间和 projected context cost；插件启用、禁用、安装、HTTPS clone 以及 root level SKILL.md 暴露都有修复。v2.1.153 起 github / git marketplace source 可用 skipLfs 跳过 Git LFS 下载；无 GitHub SSH key 的环境可用 CLAUDE CODE PLUGIN PREFER HTTPS 优先 HTTPS clone。v2.1.154 起插件可在 plugin.json 或 marketplace entry 声明 defaultEnabled: false，由用户通过 /plugin 或 claude plugin enable 显式开启；Discover tab 也会根据当前目录给出 “suggested for this directory” 推荐。v2.1.157 起 .claude/skills 目录里的插件会自动加载，无需 marketplace；claude plugin init <name 可直接脚手架新插件，/plugin 参数也会补全子命令、已安装插件和已知 marketplace 插件。企业环境还要看 pluginSuggestionMarketplaces allowlist，避免把未经允许的组织市场推荐给用户。教程中遇到插件清单差异时，以 /plugin 当前界面为准。 ⠀ 1.1 什么是Claude Code Plugin？ ⠀ 定义： ⠀ Plugin是Claude Code的扩展包，可以添加新的命令、专业能力和自动化流程，且可以跨项目和团队共享。 ⠀ 类比理解： ⠀ ⠀ 核心价值： ⠀ 1. 可复用性：一次开发，多个项目使用 2. 易分享性：通过GitHub一键克隆 3. 模块化：每个Plugin专注一个领域 4. 社区驱动：社区持续贡献优质Plugin ⠀ 1.2 Plugins vs Commands/Skills/MCP ⠀ 维度 Commands Skills MCP Plugins 定义 Markdown提示词专业Agent能力外部服务集成打包的扩展维度维度 Commands Commands Skills Skills MCP MCP Plugins Plugins 定义定义 Markdown提示词 Markdown提示词专业Agent能力专业Agent能力外部服务集成外部服务集成打包的扩展打包的扩展位置 .claude/commands/（兼容层） .claude/skills/ .mcp.json 本地目录 + market 安装可分享性 ❌ 手动复制 ❌ 手动复制 ⚠️ 需配置 ✅ 市场安装 / CLI / 本地开发目录包含内容单个提示词多个文件+配置服务器配置 manifest + agents/skills/hooks/MCP/LSP/bin/settings 加载方式自动（在项目目录中）自动（在项目目录中）自动（配置后） /plugin 为主， plugin dir 为本地开发补充 ⠀ 关键区别：Plugin是一个"超集"概念： ⠀ ⠀ 1.3 Plugins生态现状（2026年4月） ⠀ 官方数据： ⠀ • 当前版本：Claude Code v2.1.158（2026年5月30日验证） • 官方市场：✅ 已上线，可通过 /plugin 和网页入口协同使用 • 社区Plugin：持续增长中 ⠀ 主流Plugin来源： ⠀ 1. Anthropic官方Marketplace： ◦ URL：https://code.claude.com/plugins ◦ 特点：审核严格，质量保证，网页浏览 ◦ URL：https://code.claude.com/plugins ◦ 特点：审核严格，质量保证，网页浏览 2. Jeremy Longshore社区合集： ◦ URL：https://github.com/jeremylongshore/claude code plugins plus ◦ 特点：100%符合Anthropic Skills Schema ◦ URL：https://github.com/jeremylongshore/claude code plugins plus ◦ 特点：100%符合Anthropic Skills Schema 3. GitHub搜索： ◦ 搜索关键词：claude code plugin ◦ 特点：最丰富的来源，质量参差不齐 ◦ 搜索关键词：claude code plugin ◦ 特点：最丰富的来源，质量参差不齐 ⠀ ⚠️ 重要说明：Claude Code 现在既有交互里的 /plugin，也有 CLI 子命令 claude plugin（别名 claude plugins）。对普通用户来说，/plugin 依旧是最顺手的入口；claude plugin 更适合脚本化和精确控制作用域。 ⚠️ 重要说明：Claude Code 现在既有交互里的 /plugin，也有 CLI 子命令 claude plugin（别名 claude plugins）。对普通用户来说，/plugin 依旧是最顺手的入口；claude plugin 更适合脚本化和精确控制作用域。第2章：5分钟快速开始 ⠀ 2.1 安装你的第一个Plugin ⠀ 目标：先用官方主路径装一个 Plugin，再了解本地开发模式 ⠀ 前置条件检查： ⠀ ⠀ 步骤1：在 Claude Code 里打开插件入口 ⠀ ⠀ 在这里你可以浏览市场、查看已安装插件、执行安装和管理操作。 ⠀ 步骤2：按市场路径安装 ⠀ ⠀ 💡 实际名称取决于当前 market 提供的条目。最稳妥的做法是先 /plugin 浏览，再从列表里安装。 💡 实际名称取决于当前 market 提供的条目。最稳妥的做法是先 /plugin 浏览，再从列表里安装。 ⠀ 步骤3：确认插件已生效 ⠀ 安装后，检查对应的命令、skill 或行为是否已经出现在会话里。 2.2 本地开发模式：使用 plugi

在小宇宙note 阅读完整内容