如何创建你的第一个 Claude Code 插件

发布日期: 2025年10月14日 | 阅读时间: 5 分钟

你准备好深入了解 Claude Code 并创建自己的自定义工具了吗？本指南将引导你完成创建第一个插件的全过程。我们将构建一个简单的“问候”插件，它会添加一个自定义的斜杠命令。这是一个绝佳的起点，能帮助你熟悉插件系统的核心概念。

准备工作

在开始之前，请确保你已具备以下条件：

已在你的计算机上安装 Claude Code。
对命令行工具有基本的了解。

创建你的第一个插件：五个简单步骤

让我们开始构建吧！我们将创建一个本地的插件市场和你的第一个插件。

第 1 步：创建市场目录结构

首先，我们需要一个目录来存放我们的测试市场和插件。

mkdir test-marketplace
cd test-marketplace

第 2 步：创建插件目录

在市场目录中，为你的插件创建一个专属文件夹。

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

第 3 步：创建插件清单 (plugin.json)

每个插件都需要一个清单文件，用于描述其元数据。这个文件名为 plugin.json，位于 .claude-plugin 目录中。

mkdir .claude-plugin
cat > .claude-plugin/plugin.json << 'EOF'
{
  "name": "my-first-plugin",
  "description": "一个学习插件基础知识的简单问候插件",
  "version": "1.0.0",
  "author": {
    "name": "你的名字"
  }
}
EOF

这个 JSON 文件告诉 Claude Code 关于你插件的基本信息，如名称、描述和版本。

第 4 步：添加自定义斜杠命令

现在，让我们为插件添加第一个功能：一个自定义的 /hello 命令。命令在 commands 目录中以 Markdown 文件的形式定义。

mkdir commands
cat > commands/hello.md << 'EOF'
---
description: 用个性化的消息问候用户
---

# Hello 命令

热情地问候用户，并询问今天能为他们提供什么帮助。让问候语充满个性和鼓励。
EOF

description: 这部分定义了当用户在 Claude Code 中查看命令列表时将看到的命令描述。正文内容: 这部分是给 Claude 的指令，告诉它在执行 /hello 命令时应该如何回应。

第 5 步：创建市场清单并测试

为了让 Claude Code 能够发现你的本地插件，我们需要在 test-marketplace 目录下创建一个市场清单文件。

首先，返回到 test-marketplace 目录：

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": "我的第一个测试插件"
    }
  ]
}
EOF

这个文件将 my-first-plugin 注册到你的本地 test-marketplace 中。

现在，是时候测试你的成果了！

启动 Claude Code:
```
cd .. 
claude
```

添加你的测试市场:

/plugin marketplace add ./test-marketplace

安装你的插件:
```
/plugin install my-first-plugin@test-marketplace
```
选择“立即安装”，然后重启 Claude Code。
试用你的新命令:
```
/hello
```

恭喜！你将看到 Claude 使用你定义的问候语向你问好。你还可以运行 /help，在命令列表中看到你新创建的 /hello 命令。

插件结构概览

你刚刚创建的插件遵循以下基本结构：

my-first-plugin/
├── .claude-plugin/
│   └── plugin.json          # 插件元数据
└── commands/                # 自定义斜杠命令
    └── hello.md

下一步

你已经成功创建并测试了你的第一个插件！现在你可以开始探索更复杂的功能了：

添加更多命令: 在 commands/ 目录下创建更多的 Markdown 文件。
添加子代理 (Agents): 在 agents/ 目录中定义专门的 AI 助手。
使用钩子 (Hooks): 通过 hooks/hooks.json 在特定事件发生时自动执行操作。
连接外部工具: 使用 .mcp.json 文件集成 MCP 服务器。

有关更高级的开发技术和完整的技术规范，请参阅 Claude Code 的官方文档。祝你插件开发愉快！