Plugins — 创建可分发的扩展包

是什么

Plugin 是包含 Skills、Agents、Hooks、MCP Servers 等组件的自包含目录，可以跨项目和团队分发。与直接在 .claude/ 目录下配置的区别是：Plugin 有命名空间（/plugin-name:skill-name），支持版本管理和通过 Marketplace 分发。

核心机制

Plugin 结构：

my-plugin/
├── .claude-plugin/
│   └── plugin.json    # 必需：插件元数据
├── skills/            # Skills 目录
├── agents/            # Subagents 目录
├── hooks/             # Hooks 配置
└── mcp-servers/       # MCP Server 配置

plugin.json 关键字段：name（唯一标识符，也是 Skill 命名空间）、description、version（设置后只在版本变更时更新）、author。

本地测试：claude --plugin-dir ./my-plugin 加载本地 Plugin，无需发布到 Marketplace。

命名空间：Plugin 的 Skills 以 plugin-name:skill-name 形式调用，防止与其他 Plugin 或项目 Skill 冲突。

何时用 Plugin vs 独立配置：

• 独立配置（.claude/）：个人工作流、项目特定、快速实验、短命令名
• Plugin：团队分发、跨项目复用、版本控制、Marketplace 发布

关键细节

• 安装 Plugin：/plugin install <name>@<marketplace>
• 本地加载：claude --plugin-dir <path>
• 重载 Plugin：/reload-plugins
• 查看已安装 Plugin：/plugin
• Plugin 安全限制：不支持 hooks、mcpServers、permissionMode frontmatter（防止 Plugin 提升权限）

关联

• discover-plugins — 发现和安装现有 Plugin
• plugin-marketplaces — 创建和分发 Plugin Marketplace
• skills — Plugin 中的 Skills 组件
• mcp — Plugin 中的 MCP Server 组件

实践要点

• 先在 .claude/ 中快速迭代，确定后再打包为 Plugin
• version 字段控制更新频率：设置后只在版本号变更时推送更新
• Plugin 的 Agents 不支持 hooks、mcpServers、permissionMode，这是安全设计
• 用 --plugin-dir 本地测试，确认功能后再发布到 Marketplace
• 官方 Plugin 提交：claude.ai/settings/plugins/submit