08-Plugins生态完整指南

08 Plugins生态完整指南 08 Plugins生态完整指南 Modified May 9 Code block Bash Copy mkdir p hello world plugin/.claude plugin mkdir p hello world plugin/skills/hello cd hello world plugin 步骤2：创建 .claude plugin/plugin.json Code block JSON Copy { "name": "hello world plugin", "description": "A simple hello world plugin for learning", "version": "1.0.0", "author": { "name": "Claude Student" } } 步骤3：创建第一个 Skill 创建 skills/hello/SKILL.md： Code block Markdown Copy description: Greet the user with a friendly message disable model invocation: true Greet the user warmly and ask how you can help them today. 步骤4：创建 README.md Code block Markdown Copy Hello World Plugin A simple plugin that adds a namespaced skill to Claude Code. Installation \ \ \ Usage In Claude Code interactive mode: \ \ \ Features Creative greetings Current date display Random programming jokes 步骤5：测试 Plugin Code block Bash Copy 在项目目录中启动Claude Code，加载Plugin claude plugin dir /path/to/hello world plugin 在交互模式中使用 You: /hello world plugin:hello 💡 为什么这里用了 namespaced 命令？ 官方当前规范里，plugin 内的 skill 会自动加上 plugin name: 前缀，例如 /hello world plugin:hello。这样做是为了避免多个 plugin 之间撞名。 4.3 进阶Plugin：带Skills的Plugin 目标：创建一个包含Skill的Plugin，让Claude具备代码审查能力 目录结构： Code block Plain Text Copy code review plugin/ ├── .claude plugin/ │ └── plugin.json ├── README.md ├── commands/ │ └── review.md └── skills/ └── code reviewer/ └── SKILL.md skills/code reviewer/SKILL.md： Code block Markdown Copy name: code reviewer description: Expert code review skill You are an expert code reviewer. When reviewing code: 1. Check for security vulnerabilities (SQL injection, XSS, etc.) 2. Identify performance bottlenecks 3. Suggest improvements for readability 4. Verify error handling completeness 5. Check naming conventions consistency Output format: 🔴 CRITICAL: Must fix before merge 🟡 WARNING: Should fix 🟢 INFO: Nice to have commands/review.md： Code block Markdown Copy Review the current git diff and provide a detailed code review. Use the code reviewer skill for analysis. Focus on security, performance, and maintainability. 测试： Code block Bash Copy claude plugin dir ./code review plugin You: /code review plugin:review Claude会在 plugin 命名空间下调用 review 入口，并结合 code reviewer skill 分析你的代码变更 4.4 Plugin最佳实践 原则 说明 单一职责 每个Plugin专注一个领域（代码审查、文档生成等） 清晰文档 README必须包含安装步骤、使用示例、配置说明 版本管理 使用语义化版本号（SemVer），打git tag 最小依赖 尽量减少外部依赖，保持Plugin轻量 安全第一 不在Plugin中硬编码密钥，使用环境变量 第5章：发布与分享Plugin 5.1 发布前检查清单 Code block Plain Text Copy ✅ .claude plugin/plugin.json 字段完整（至少有 name / version / description；author 推荐但可选） ✅ README.md 包含安装和使用说明 ✅ 所有命令和Skills已测试通过 ✅ 无硬编码密钥或敏感信息 ✅ .gitignore 排除了不必要的文件 ✅ LICENSE 文件存在 5.2 发布到GitHub Code block Bash Copy 初始化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 Bash Copy 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 code.claude.com/plugins 步骤2：创建 .claude plugin/plugin.json 步骤3：创建第一个 Skill 创建 skills/hello/SKILL.md： 步骤4：创建 README.md 步骤5：测试 Plugin 💡 为什么这里用了 namespaced 命令？ 官方当前规范里，plugin 内的 skill 会自动加上 plugin name: 前缀，例如 /hello world plugin:hello。这样做是为了避免多个 plugin 之间撞名。 4.3 进阶Plugin：带Skills的Plugin 目标：创建一个包含Skill的Plugin，让Claude具备代码审查能力 目录结构： skills/code reviewer/SKILL.md： commands/review.md： 测试： 4.4 Plugin最佳实践 原则 说明 单一职责 每个Plugin专注一个领域（代码审查、文档生成等） 清晰文档 README必须包含安装步骤、使用示例、配置说明 版本管理 使用语义化版本号（SemVer），打git tag 最小依赖 尽量减少外部依赖，保持Plugin轻量 安全第一 不在Plugin中硬编码密钥，使用环境变量 原则 原则 说明 说明 单一职责 单一职责 每个Plugin专注一个领域（代码审查、文档生成等） 每个Plugin专注一个领域（代码审查、文档生成等） 清晰文档 清晰文档 README必须包含安装步骤、使用示例、配置说明 README必须包含安装步骤、使用示例、配置说明 版本管理 版本管理 使用语义化版本号（SemVer），打git tag 使用语义化版本号（SemVer），打git tag 最小依赖 最小依赖 尽量减少外部依赖，保持Plugin轻量 尽量减少外部依赖，保持Plugin轻量 安全第一 安全第一 不在Plugin中硬编码密钥，使用环境变量 不在Plugin中硬编码密钥，使用环境变量 第5章：发布与分享Plugin 5.1 发布前检查清单 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定制完整指南 创建可复用功能包 下一节 09 Agent SDK完整指南 编程开发AI Agent 07 Skills定制完整指南 09 Agent SDK完整指南 资源 资源 链接 链接 说明 说明 上一节 上一节 07 Skills定制完整指南 07 Skills定制完整指南 07 Skills定制完整指南 07 Skills定制完整指南 创建可复用功能包 创建可复用功能包 下一节 下一节 09 Agent SDK完整指南 09 Agent SDK完整指南 09 Agent SDK完整指南 09 Agent SDK完整指南 编程开发AI Agent 编程开发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冲突。 最后更新：2026年5月8日 | 适用版本：Claude Code v2.1.133 Claude Code Plugins生态完整指南：从安装到自定义开发 课程信息 • 作者：老金 • GitHub：https://github.com/KimYx0207 • 公众号：老金带你玩AI • X（Twitter）：老金带你玩AI • 个人博客：https://aiking.dev • 预计学时：4 6小时 • 难度等级：⭐⭐ 入门级 • 更新日期：2026年4月 • 适用版本：Claude Code v2.1.133（验证于 2026 05 08；v2.1.90+ 插件市场 env 见文内 release 摘录） https://aiking.dev 课程信息 • 作者：老金 • GitHub：https://github.com/KimYx0207 • 公众号：老金带你玩AI • X（Twitter）：老金带你玩AI • 个人博客：https://aiking.dev https://aiking.dev • 预计学时：4 6小时 • 难度等级：⭐⭐ 入门级 • 更新日期：2026年4月 • 适用版本：Claude Code v2.1.133（验证于 2026 05 08；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%的常见故障 2026 04 差量更新（先读） 这章旧版最大的问题，是把 plugin dir 写成了默认主路径。现在更准确的理解是： • 普通用户安装插件：优先使用交互内置的 /plugin 命令和市场（market）体系。 • 本地开发 / 调试插件： plugin dir 仍然有价值，但它更像开发者入口，不是今天最推荐的日常安装方式。 • Plugin 的边界更清晰了：它不只是“Commands + Skills + MCP 配置”，还涉及 market、scope、manifest、agents、hooks、LSP、bin、settings 等运行面。 因此，下面请把 /plugin 视为主路径，把 plugin dir 视为本地开发补充路径。 v2.1.114+ → v2.1.133 变更 v2.1.114：新增自定义主题能力。Plugin 现在可以通过 manifest 声明颜色主题（color palette），用户也可以在 /theme 中选择。这使 Plugin 不仅提供工具和命令，还能定制 Claude Code 的视觉体验。 v2.1.121+： • plugin url：直接通过 URL 加载远程 Plugin（如 GitHub 仓库的 ZIP 包），无需先 clone • plugin dir 现在也支持加载 .zip 文件（解压后自动加载） • Manifest 支持新的 experimental 字段，用于声明实验性功能 v2.1.126：新增 plugin prune 命令，清理已安装但不再被任何项目引用的 Plugin，释放磁盘空间。 环境变量：CLAUDE CODE PLUGIN KEEP MARKETPLACE ON FAILURE（v2.1.90） 以下为 GitHub Release v2.1.90 原文摘录（便于核对，不二次发挥）： GitHub Release v2.1.90 Added CLAUDE CODE PLUGIN KEEP MARKETPLACE ON FAILURE env var to keep the existing marketplace cache when git pull fails, useful in offline environments 理解要点：仅在 marketplace 的 git pull 失败时，仍保留已有 marketplace 缓存；面向离线等场景。是否在环境中设置该变量，请结合你的网络与合规要求自行决定；变量名与语义以官方后续文档为准。 🗺️ 学习路径导航（先看这里！） 路径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生态概览 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能力 外部服务集成 打包的扩展 位置 .claude/commands/（兼容层） .claude/skills/ .mcp.json 本地目录 + market 安装 可分享性 ❌ 手动复制 ❌ 手动复制 ⚠️ 需配置 ✅ 市场安装 / CLI / 本地开发目录 维度 维度 Commands Commands Skills Skills MCP MCP Plugins Plugins