Claude Code 插件开发完整指南：从入门到精通

📖 前言

Claude Code 插件系统是一个强大的功能，允许开发者通过自定义命令、代理、钩子和 MCP 服务器来扩展 Claude Code 的功能。本指南将带你从零开始，逐步掌握 Claude Code 插件开发的各个方面。

💡 提示：本文基于 Claude Code 官方文档编写，包含实际可操作的示例代码和最佳实践。

🚀 快速入门

让我们从一个简单的问候插件开始，熟悉插件系统的基本概念和工作流程。

📋 先决条件

• ✅ 已在本地安装 Claude Code
• ✅ 具备基本的命令行工具使用经验

🛠️ 创建你的第一个插件

步骤 1：创建市场结构

1
2

mkdir test-marketplace
cd test-marketplace

步骤 2：创建插件目录

1
2

mkdir my-first-plugin
cd my-first-plugin

步骤 3：创建插件清单

创建 .claude-plugin/plugin.json 文件：

1
2
3
4
5
6
7
8
9
10
11

mkdir .claude-plugin
cat > .claude-plugin/plugin.json << 'EOF'
{
  "name": "my-first-plugin",
  "description": "A simple greeting plugin to learn the basics",
  "version": "1.0.0",
  "author": {
    "name": "Your Name"
  }
}
EOF

步骤 4：添加自定义命令

创建 commands/hello.md 文件：

1
2
3
4
5
6
7
8

mkdir commands
cat > commands/hello.md << 'EOF'
---
description: Greet the user with a personalized message
---
# Hello Command
Greet the user warmly and ask how you can help them today. Make the greeting personal and encouraging.
EOF

步骤 5：创建市场清单

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

cd ..
mkdir .claude-plugin
cat > .claude-plugin/marketplace.json << 'EOF'
{
  "name": "test-marketplace",
  "owner": {
    "name": "Test User"
  },
  "plugins": [
    {
      "name": "my-first-plugin",
      "source": "./my-first-plugin",
      "description": "My first test plugin"
    }
  ]
}
EOF

步骤 6：安装并测试插件

1
2
3
4
5
6
7
8
9

# 返回父目录启动 Claude Code
cd ..
claude

# 添加测试市场
/plugin marketplace add ./test-marketplace

# 安装你的插件
/plugin install my-first-plugin@test-marketplace

选择”立即安装”，然后重启 Claude Code 以使用新插件。

1
2

# 尝试你的新命令
/hello

你将看到 Claude 使用你的问候命令！运行 /help 查看列出的新命令。

🏗️ 插件结构概览

你的插件遵循这个基本结构：

1
2
3
4
5
6
7
8
9

my-first-plugin/
├── .claude-plugin/
│   └── plugin.json        # 插件元数据
├── commands/              # 自定义斜杠命令（可选）
│   └── hello.md
├── agents/                # 自定义代理（可选）
│   └── helper.md
└── hooks/                 # 事件处理器（可选）
    └── hooks.json

🔧 可添加的额外组件：

• Commands（命令）：在 commands/ 目录中创建 Markdown 文件
• Agents（代理）：在 agents/ 目录中创建代理定义
• Hooks（钩子）：创建 hooks/hooks.json 用于事件处理
• MCP 服务器：创建 .mcp.json 用于外部工具集成

💡 后续步骤：准备添加更多功能了吗？跳转到开发更复杂的插件来添加代理、钩子和 MCP 服务器。完整的插件组件技术规范，请参阅插件参考文档。

📦 安装和管理插件

学习如何发现、安装和管理插件来扩展你的 Claude Code 功能。

📋 先决条件

• ✅ 已安装并运行 Claude Code
• ✅ 具备基本的命令行界面知识

🏪 添加市场

市场是可用插件的目录。添加它们来发现和安装插件：

1
2
3
4
5

# 添加一个市场
/plugin marketplace add your-org/claude-plugins

# 浏览可用插件
/plugin

📚 详细管理：有关 Git 仓库、本地开发和团队分发的详细市场管理，请参阅插件市场。

💿 安装插件

通过交互式菜单（推荐用于发现）

1
2

# 打开插件管理界面
/plugin

选择”浏览插件”查看可用的选项、描述、功能和安装选项。

通过直接命令（用于快速安装）

1
2
3
4
5
6
7
8
9
10
11

# 安装特定插件
/plugin install formatter@your-org

# 启用已禁用的插件
/plugin enable plugin-name@marketplace-name

# 禁用而不卸载
/plugin disable plugin-name@marketplace-name

# 完全移除插件
/plugin uninstall plugin-name@marketplace-name

✅ 验证安装

安装插件后：

• 检查可用命令：运行 /help 查看新命令
• 测试插件功能：尝试插件的命令和功能
• 查看插件详情：使用 /plugin → “管理插件” 查看插件提供的内容

👥 设置团队插件工作流

在仓库级别配置插件，确保整个团队的工具一致性。当团队成员信任你的仓库文件夹时，Claude Code 会自动安装指定的市场和插件。

🔧 设置团队插件

1. 将市场和插件配置添加到仓库的 .claude/settings.json
2. 团队成员信任仓库文件夹
3. 插件为所有团队成员自动安装

📋 完整指南：包含配置示例、市场设置和推广最佳实践的完整说明，请参阅配置团队市场。

🔧 开发更复杂的插件

一旦你熟悉了基本插件，就可以创建更复杂的扩展。

📁 组织复杂插件

对于包含许多组件的插件，按功能组织你的目录结构。完整的目录布局和组织模式，请参阅插件目录结构。

🧪 本地测试插件

开发插件时，使用本地市场来迭代测试更改。这个工作流程基于快速入门模式，适用于任何复杂度的插件。

步骤 1：设置开发结构

1
2
3

mkdir dev-marketplace
cd dev-marketplace
mkdir my-plugin

这将创建：

1
2
3
4
5
6
7

dev-marketplace/
├── .claude-plugin/marketplace.json (你将创建这个)
└── my-plugin/                   # 正在开发的插件
    ├── .claude-plugin/plugin.json
    ├── commands/
    ├── agents/
    └── hooks/

步骤 2：创建市场清单

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

mkdir .claude-plugin
cat > .claude-plugin/marketplace.json << 'EOF'
{
  "name": "dev-marketplace",
  "owner": {
    "name": "Developer"
  },
  "plugins": [
    {
      "name": "my-plugin",
      "source": "./my-plugin",
      "description": "Plugin under development"
    }
  ]
}
EOF

步骤 3：安装和测试

1
2
3
4
5
6
7
8
9

# 从父目录启动 Claude Code
cd ..
claude

# 添加你的开发市场
/plugin marketplace add ./dev-marketplace

# 安装你的插件
/plugin install my-plugin@dev-marketplace

测试你的插件组件：

• 使用 /command-name 尝试你的命令
• 检查代理是否出现在 /agents 中
• 验证钩子是否按预期工作

步骤 4：迭代你的插件

对插件代码进行更改后：

1
2
3
4
5

# 卸载当前版本
/plugin uninstall my-plugin@dev-marketplace

# 重新安装测试更改
/plugin install my-plugin@dev-marketplace

在开发和优化插件时重复这个循环。

💡 对于多个插件：在子目录中组织插件，如 ./plugins/plugin-name，并相应地更新你的 marketplace.json。组织模式请参阅插件源码。

🐛 调试插件问题

如果你的插件没有按预期工作：

• 检查结构：确保你的目录在插件根目录，而不是在 .claude-plugin/ 内部
• 单独测试组件：分别检查每个命令、代理和钩子
• 使用验证和调试工具：请参阅调试和开发工具了解 CLI 命令和故障排除技术

📤 分享你的插件

当你的插件准备好分享时：

• 添加文档：包含 README.md 文件，提供安装和使用说明
• 版本化你的插件：在你的 plugin.json 中使用语义版本控制
• 创建或使用市场：通过插件市场分发以便安装
• 与他人测试：在更广泛分发之前让团队成员测试插件

📚 技术规范：完整的技术规范、调试技术和分发策略，请参阅插件参考。

🎯 后续步骤

现在你了解了 Claude Code 的插件系统，以下是针对不同目标的建议路径：

🔍 对于插件用户

• 发现插件：浏览社区市场寻找有用工具
• 团队采用：为你的项目设置仓库级插件
• 市场管理：学习管理多个插件源
• 高级使用：探索插件组合和工作流程

💻 对于插件开发者

• 创建你的第一个市场：插件市场指南
• 高级组件：深入研究特定插件组件：
  • 斜杠命令 - 命令开发详情
  • 子代理 - 代理配置和功能
  • 钩子 - 事件处理和自动化
  • MCP - 外部工具集成
• 分发策略：有效打包和分享你的插件
• 社区贡献：考虑为社区插件集合做贡献

👨‍💼 对于团队负责人和管理员

• 仓库配置：为团队项目设置自动插件安装
• 插件治理：建立插件审批和安全审查指南
• 市场维护：创建和维护组织特定的插件目录
• 培训和文档：帮助团队成员有效采用插件工作流程

🔗 相关资源

• 插件市场 - 创建和管理插件目录
• 斜杠命令 - 理解自定义命令
• 子代理 - 创建和使用专用代理
• 钩子 - 使用事件处理器自动化工作流程
• MCP - 连接外部工具和服务
• 设置 - 插件的配置选项

🎉 总结

Claude Code 插件系统为开发者提供了一个强大而灵活的平台，用于扩展和定制 AI 辅助编程体验。通过本指南，你已经学会了：

✅ 基础概念：理解插件系统的核心组件和工作原理
✅ 实践开发：从简单到复杂的插件开发流程
✅ 团队协作：如何在团队环境中配置和管理插件
✅ 最佳实践：调试、测试和分享插件的推荐方法

无论你是想要提高个人开发效率，还是为团队构建标准化工具链，Claude Code 插件系统都能满足你的需求。开始构建你的第一个插件，探索 AI 辅助编程的无限可能吧！

🚀 立即开始你的 Claude Code 插件开发之旅！