第 17 章 Plugins——打包与分发

❓ 引导问题：如何把 MCP、Skills、Hooks、Agents 打包成可分发的 Plugin？Plugin 和独立配置如何选择？

📖 17.1 什么是 Plugin

Plugin（插件）是 Claude Code 中最高级别的扩展机制，用于将命令、代理、Skills、Hooks、MCP、LSP 等能力打包、版本化、共享和分发。

Plugin = 一组可复用的 Claude Code 扩展能力集合

一个 Plugin 可包含：Slash Commands、Agents、Skills、Hooks、MCP 服务器、LSP 服务器。

📖 17.2 Plugin vs 独立配置

方式	命令形式	适合场景
独立配置（.claude/）	/hello	个人使用、单项目、快速实验
Plugin（.claude-plugin/）	/plugin-name:hello	团队共享、跨项目、版本化

用独立配置	用 Plugin
只在当前项目使用	要在多个项目复用
个人工作流	要分享给团队或社区
尚未稳定的实验性配置	需要版本控制、升级、回滚
想要简短命令名	可以接受命名空间命令（避免冲突）

💡 最佳实践：先在 .claude/ 中迭代 → 稳定后打包为 Plugin。

📖 17.3 最小结构

my-plugin/
├── .claude-plugin/
│   └── plugin.json     # 插件清单（唯一必需）
├── commands/           # 斜杠命令（Markdown 文件）
├── agents/             # 子代理
├── skills/             # Skills
├── hooks/              # 钩子
├── .mcp.json           # MCP 配置
└── .lsp.json           # LSP 配置

⚠️ .claude-plugin/ 目录中只能放 plugin.json，其他目录必须在插件根目录。

📖 17.4 插件清单（plugin.json）

{
  "name": "my-first-plugin",
  "description": "A greeting plugin to learn the basics",
  "version": "1.0.0",
  "author": { "name": "Your Name" }
}

字段	作用
name	唯一标识 + 命令命名空间
description	插件市场中展示
version	语义化版本控制
author	可选，归属说明

📖 17.5 斜杠命令

命令文件放在 commands/ 目录，文件名即命令名：

commands/hello.md → /my-first-plugin:hello

---
description: Greet the user with a friendly message
---

Greet the user warmly and ask how you can help them today.

支持用 $ARGUMENTS 捕获参数：/my-first-plugin:hello Alex

📖 17.6 本地测试

使用 --plugin-dir 直接加载，无需安装：

claude --plugin-dir ./my-plugin
claude --plugin-dir ./plugin-a --plugin-dir ./plugin-b  # 同时加载多个

修改后需重启 Claude Code。

📖 17.7 插件市场

安装插件：

/plugin install plugin-name@claude-plugins-official

管理命令：

/plugin                # 打开插件管理器
/plugin install        # 安装插件
/plugin uninstall      # 卸载
/plugin enable/disable # 启用/禁用
/plugin marketplace add # 添加市场
/plugin marketplace rm  # 移除市场

📖 17.8 安装范围

范围	说明
用户范围	仅你自己，所有项目
项目范围	当前仓库，团队共享
本地范围	当前仓库，仅你

推荐：团队工具 → 项目范围；个人效率工具 → 用户范围。

📖 17.9 从 .claude/ 迁移到 Plugin

原来	迁移后
.claude/commands	plugin/commands
.claude/agents	plugin/agents
settings.json hooks	plugin/hooks/hooks.json

迁移后插件版本优先生效，可删除旧 .claude/ 配置避免重复。

📖 17.10 何时必须用 Plugin

• 已经有稳定的 Claude 工作流，不想在每个项目重复配置
• 在反复复制 .claude/ 目录
• 团队成员开始问："这个怎么配置？"
• 需要版本控制、升级、回滚
• 希望 Claude 能力像 IDE 插件一样可控

💡 Plugin 是 Claude Code 从「个人 AI 助手」走向「工程化工具」的分水岭。

---

📖 17.XX 要点总结

1. Plugin 是最高级扩展机制——把 Commands + Agents + Skills + Hooks + MCP + LSP 打包为一个可分发的版本化单元
2. 先迭代后打包：先在 .claude/ 中独立配置快速实验，稳定后再打包为 Plugin 分发
3. .claude-plugin/plugin.json 是唯一必需文件，定义名称、版本和命名空间
4. --plugin-dir 用于本地开发测试，不需要安装即可加载
5. Plugin 命名空间命令（/plugin-name:command）避免与内置命令冲突，适合团队共享