Claude Code Plugins 生态指南

什么是 Plugins

Plugins 是 Claude Code 的扩展包,可以添加新的命令、专业能力和自动化流程,且可跨项目和团队共享。

核心价值

类比理解: Plugins 就像手机 APP

| 手机 | Claude Code | |------|-------------| | 操作系统 | Claude Code 核心 | | App Store | Plugin Marketplace | | 安装的 APP | 已安装的 Plugins | | APP 更新 | Plugin 更新(git pull) |

价值:

可复用性: 一次开发,多个项目使用
易分享性: 通过 GitHub 一键克隆
模块化: 每个 Plugin 专注一个领域
社区驱动: 社区持续贡献优质 Plugin

Plugins vs Commands/Skills/MCP

| 维度 | Commands | Skills | MCP | Plugins | |------|----------|--------|-----|---------| | 定义 | Markdown 提示词 | 专业能力 | 外部服务 | 打包的扩展 | | 位置 | .claude/commands/ | .claude/skills/ | .mcp.json | 本地目录 + 市场 | | 可分享性 | ❌ 手动复制 | ❌ 手动复制 | ⚠️ 需配置 | ✅ 市场安装 | | 包含内容 | 单个提示词 | 多文件+配置 | 服务器配置 | manifest + 多种资源 | | 加载方式 | 自动 | 自动 | 自动 | /plugin 或 --plugin-dir |

关键区别: Plugin 是超集概念

Plugin = manifest + agents + skills + hooks + MCP + LSP + bin + settings

快速开始

安装第一个 Plugin

方式 1: 使用 /plugin 命令(推荐)

在 Claude Code 交互模式中:

/plugin

这会打开插件管理界面,可以:

浏览市场
查看已安装插件
安装新插件
管理现有插件

安装示例:

/plugin install <plugin-name>

方式 2: 本地开发模式(使用 --plugin-dir)

适合开发和调试本地 Plugin:

# 创建 plugins 目录
mkdir -p .claude/plugins

# 克隆 Plugin
git clone https://github.com/author/my-plugin .claude/plugins/my-plugin

# 启动时加载
claude --plugin-dir .claude/plugins/my-plugin

加载多个 Plugin:

claude --plugin-dir ./plugin-a --plugin-dir ./plugin-b

验证 Plugin 已加载

You: /help

# 如果 Plugin 包含命令,会在列表中显示
# 格式: /plugin-name:command-name

卸载 Plugin

市场安装的:

/plugin uninstall <plugin-name>

本地目录的:

rm -rf .claude/plugins/my-plugin
# 下次启动不带 --plugin-dir 参数即可

Plugin Marketplace

访问市场

网页入口:

浏览器访问: https://code.claude.com/plugins

功能:

| 功能 | 说明 | |------|------| | 分类浏览 | 按用途分类(文档、代码质量、项目管理等) | | 搜索 | 按关键词搜索 Plugin | | 详情页 | 查看说明、安装量、评分、仓库链接 | | 安装指引 | 提供安装命令 |

主流 Plugin 来源

Anthropic 官方 Marketplace
- URL: https://code.claude.com/plugins
- 特点: 审核严格,质量保证
社区合集
- URL: https://github.com/jeremylongshore/claude-code-plugins-plus
- 特点: 符合官方 Schema
GitHub 搜索
- 关键词: claude-code-plugin
- 特点: 最丰富,质量参差不齐

管理已安装 Plugins

# 查看已安装
ls .claude/plugins/

# 更新 Plugin
cd .claude/plugins/my-plugin && git pull

# 切换版本
cd .claude/plugins/my-plugin && git checkout v1.2.0

# 查看信息
cat .claude/plugins/my-plugin/.claude-plugin/plugin.json

创建自定义 Plugin

Plugin 结构规范

最小结构:

my-plugin/
├── .claude-plugin/
│   └── plugin.json      # 必需: 元数据清单
├── README.md            # 推荐: 使用文档
├── skills/              # 可选: Agent Skills
│   └── my-skill/
│       └── SKILL.md
├── commands/            # 可选: Slash Commands
│   └── my-command.md
├── agents/              # 可选: Agent 定义
│   └── my-agent.md
└── hooks/               # 可选: Hooks
    └── pre-commit.py

plugin.json 规范:

{
  "name": "my-awesome-plugin",
  "description": "A plugin that does awesome things",
  "version": "1.0.0",
  "author": {
    "name": "Your Name"
  }
}

重要: plugin.json 必须放在 .claude-plugin/ 子目录中。

创建 Hello World Plugin

步骤 1: 创建目录

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

步骤 2: 创建 plugin.json

创建 .claude-plugin/plugin.json:

{
  "name": "hello-world-plugin",
  "description": "A simple hello world plugin",
  "version": "1.0.0",
  "author": {
    "name": "Your Name"
  }
}

步骤 3: 创建 Skill

创建 skills/hello/SKILL.md:

---
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

# Hello World Plugin

A simple plugin that adds a greeting skill.

## Installation

\`\`\`bash
claude --plugin-dir ./hello-world-plugin
\`\`\`

## Usage

\`\`\`
/hello-world-plugin:hello
\`\`\`

步骤 5: 测试

claude --plugin-dir /path/to/hello-world-plugin

# 在交互模式中
You: /hello-world-plugin:hello

进阶: 代码审查 Plugin

目录结构:

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

skills/code-reviewer/SKILL.md:

---
name: code-reviewer
description: Expert code review skill
---

You are an expert code reviewer. When reviewing code:

1. Check for security vulnerabilities
2. Identify performance bottlenecks
3. Suggest readability improvements
4. Verify error handling
5. Check naming conventions

Output format:
- 🔴 CRITICAL: Must fix
- 🟡 WARNING: Should fix
- 🟢 INFO: Nice to have

commands/review.md:

Review the current git diff and provide detailed analysis.
Use the code-reviewer skill.
Focus on security, performance, and maintainability.

测试:

claude --plugin-dir ./code-review-plugin

You: /code-review-plugin:review

Plugin 最佳实践

| 原则 | 说明 | |------|------| | 单一职责 | 每个 Plugin 专注一个领域 | | 清晰文档 | README 包含安装、使用、配置说明 | | 版本管理 | 使用语义化版本号,打 git tag | | 最小依赖 | 减少外部依赖,保持轻量 | | 安全第一 | 不硬编码密钥,使用环境变量 |

发布与分享

发布前检查清单

✅ .claude-plugin/plugin.json 字段完整
✅ README.md 包含安装和使用说明
✅ 所有命令和 Skills 已测试
✅ 无硬编码密钥或敏感信息
✅ .gitignore 排除不必要文件
✅ LICENSE 文件存在

发布到 GitHub

# 初始化 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

推荐设置:

添加 Topics: claude-code-plugin, claude-code, ai-plugin
写清楚 Description
添加使用示例

分享到社区

提交到社区合集
- Fork jeremylongshore/claude-code-plugins-plus
- 添加 Plugin 信息
- 提交 PR
GitHub Discussions
- 到 anthropics/claude-code Discussions 分享
官方 Marketplace
- 访问 code.claude.com/plugins 查看提交指南
- 需通过官方审核

故障排查

Plugin 加载失败

排查步骤:

# 1. 确认路径正确
ls /path/to/plugin/.claude-plugin/plugin.json

# 2. 验证 JSON 格式
cat /path/to/plugin/.claude-plugin/plugin.json | python3 -m json.tool

# 3. 使用 debug 模式
claude --plugin-dir /path/to/plugin --debug

命令不显示

可能原因:

| 原因 | 解决方案 | |------|----------| | commands 目录路径错误 | 确认在根目录下有 commands/ | | 文件不是 .md 格式 | 命令文件必须是 .md 后缀 | | plugin.json 缺失 | 确认 .claude-plugin/plugin.json 存在 | | 文件权限问题 | chmod 644 commands/*.md |

Skills 不生效

检查:

# 确认 SKILL.md 存在
cat /path/to/plugin/skills/my-skill/SKILL.md

# 确认 frontmatter 格式
# 必须以 --- 开头和结尾

多 Plugin 冲突

# 后加载的覆盖先加载的
# 调整 --plugin-dir 顺序控制优先级
claude --plugin-dir ./low-priority --plugin-dir ./high-priority

常见问题

Q: Plugin 和 Skill 有什么区别?

Skill 是单个能力定义,Plugin 是完整扩展包,可包含多个 Skills + Commands + Hooks + MCP。

Q: 如何安装 Plugin?

优先使用 /plugin install,本地开发使用 --plugin-dir。

Q: Plugin 会访问我的代码吗?

Plugin 在沙箱中运行,遵循相同的权限模型,不能绕过权限系统。

Q: 如何更新 Plugin?

cd .claude/plugins/my-plugin
git pull origin main

Q: 如何卸载 Plugin?

市场安装: /plugin uninstall <name> 本地目录: rm -rf .claude/plugins/my-plugin

Q: 可以同时加载多少个 Plugin?

没有硬性限制,但建议不超过 5 个,按需加载。

Q: Plugin 开发需要懂编程吗?

不一定。简单 Plugin 只需 Markdown。只有 Hooks 需要编程。

Q: Plugin 可以离线使用吗?

可以。Plugin 是本地文件,加载后不需要网络。但 MCP 连接外部服务需要网络。

Q: 如何让 Plugin 全局生效?

# 方法 1: 每次指定
claude --plugin-dir ~/.claude/global-plugins/my-plugin

# 方法 2: shell 别名
alias claude='claude --plugin-dir ~/.claude/global-plugins/my-plugin'

Q: Plugin 报错如何获取帮助?

查看 GitHub Issues
使用 claude --debug 查看日志
检查 README 的 Troubleshooting

速查表

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 | | 卸载 | rm -rf .claude/plugins/<name> | | 查看信息 | cat .claude/plugins/<name>/.claude-plugin/plugin.json | | 调试 | claude --plugin-dir <path> --debug |

Plugin 目录结构

my-plugin/
├── .claude-plugin/
│   └── plugin.json      # 必需: 元数据
├── .mcp.json            # 可选: MCP 配置
├── README.md            # 推荐: 文档
├── commands/*.md        # 可选: 命令
├── skills/*/SKILL.md    # 可选: 能力
├── agents/*.md          # 可选: Agent
└── hooks/*.py           # 可选: 脚本

命名空间: Plugin 中的 Skills 自动添加前缀 /plugin-name:skill-name。

总结

通过本指南,你已经掌握了:

Plugins 概念 - 理解扩展包的作用
安装使用 - 掌握 /plugin 和 --plugin-dir
Marketplace - 浏览和安装社区 Plugin
自定义开发 - 创建自己的 Plugin
发布分享 - 将 Plugin 分享给社区
故障排查 - 解决常见问题

下一步学习:

Agent SDK 开发
综合实战案例
企业级应用

参考资源

更新日期: 2026年4月29日
适用版本: Claude Code v2.1.92+

Claude Code Plugins 生态指南

分享这篇文章