如何从零开始创建一个Claude Code插件

前言

大家好，我是小溪，见字如面。前面我们Claude Code插件系统有了初步了解和基本使用，这次我们来尝试从0开始创建一个Claude Code插件，更深入的了解Claude Code插件底层逻辑。对对往期内容感兴趣的小伙伴也可以看往期内容：

插件市场、插件目录结构

一个完整的插件系统包含插件市场和插件，插件市场和插件分别有独特的目录结构和配置方式。

插件市场目录结构

插件市场文件目录结构如下：

perl 复制代码

my-marketplace/            # 插件系统目录
├── .claude-plugin/
│   └── marketplace.json # 插件系统配置
└── my-first-plugin/      # 插件目录
    ├── .claude-plugin/plugin.json
    ├── commands/
    ├── agents/
    └── hooks/

marketplace.json 配置信息：

bash 复制代码

{
  "name": "插件市场名称",
  "version": "插件市场版本",
  "description": "插件市场描述",
  "owner": {
    "name": "作者名称",
    "email": "作者邮箱",
    "url": "作者网站首页"
  },
  "plugins": [ # 插件配置
    {
      "name": "插件名称",
      "description": "插件描述",
      "source": "插件路径",
      "version": "插件版本",
      "author": {
        "name": "插件作者名称",
        "email": "插件作者邮箱"
      },
      "category": "插件分类"，
    },
  ]
}

插件目录结构

插件文件目录结构如下：

perl 复制代码

my-first-plugin/
├── .claude-plugin/
│   └── plugin.json   # 插件配置
├── commands/          # 自定义命令
│   └── hello.md
├── agents/            # 自定义Agents
│   └── helper.md
├── skills/            # 自定义Skills
│   └── my-skill/
│       └── SKILL.md
├── .mcp.json          # MCP服务配置
└── hooks/             # 自定义hooks
    └── hooks.json

插件目录可以包含 commands、agents、hooks、skills、.mcp.json 等目录配置：

commands：自定义命令目录，存放自定义命令 .md文件
agents：自定义子Agent目录，存放自定义Agent .md文件
hooks：自定义Hooks目录，存放自定义Hooks hooks.json 和脚本文件
skills：自定义Skills目录，存放Skills结构目录
.mcp.json：自定义MCP服务配置文件

plugin.json 配置信息：

perl 复制代码

{
  "name": "agent-sdk-dev",
  "description": "Claude Agent SDK Development Plugin",
  "version": "1.0.0",
  "author": {
    "name": "Ashwin Bhat",
    "email": "ashwin@anthropic.com"
  }
}

自定义插件路径

1、自定义插件路径方式和默认目录方式不可同时配置，会出现路径异常问题

2、自定义路径方式需指定

在插件市场中除了默认目录配置方式，还可以使用自定义路径的形式自己指定各个指令的路径，配置格式如下所示：

json 复制代码

{
    "name": "插件市场名称",
    "version": "插件市场版本",
    "description": "插件市场描述",
    "owner": {
        "name": "作者名称",
        "email": "作者邮箱",
        "url": "作者网站首页"
    },
    "plugins": [
       {
            "name": "插件名称",
            "version": "插件版本",
            "description": "插件描述",
            "source": "./",
            "author": {
                "name": "插件作者",
                "email": "插件作者邮箱",
                "url": "https://github.com/author"
            },
            "homepage": "https://docs.example.com/plugin",
            "repository": "https://github.com/author/plugin",
            "license": "MIT",
            "keywords": [
                "keyword1",
                "keyword2"
            ],
            "commands": [
                "./custom/commands/special.md"
            ],
            "agents": "./custom/agents/",
            "hooks": "./config/hooks.json",
            "mcpServers": "./mcp-config.json"
        }
    ]
}

自定义插件路径的典型的代表可以查看Claude Code Templates项目：github.com/davila7/cla...

自定义插件

Claude Code插件是托管在插件市场的，自定义插件可以选择托管在别人创建好的插件市场也可以选择自己创建插件市场，这里我们以后者为例进行演示。

创建插件市场

在非项目工作区目录创建一个文件夹作为插件市场目录，可以手动创建，也可以通过以下命令创建：

shell 复制代码

$ cd /Users/username/Desktop/ai 
$ mkdir my-marketplace

接着创建 .claude-plugin 目录和 marketplace.json 配置，注意插件 source 路径必须相对于插件根目录，以 ./ 开头

bash 复制代码

$ cd my-marketplace
$ mkdir .claude-plugin
$ cat > .claude-plugin/marketplace.json << 'EOF'
{
  "name": "my-marketplace",
  "version": "0.0.1",
  "description": "我的第一个插件市场",
  "owner": {
    "name": "作者名称",
    "email": "作者邮箱",
    "url": "作者网站首页"
  },
  "plugins": [
    {
      "name": "my-first-plugin",
      "source": "./my-first-plugin",
      "description": "My first test plugin"
    }
  ]
}
EOF

创建完成后目录结构和配置如下：

创建插件

在当前插件市场目录下，先创建一个插件目录，可以手动创建，也可以通过以下命令创建：

perl 复制代码

$ mkdir my-first-plugin

接着创建 .claude-plugin 目录和 plugin.json 配置

bash 复制代码

$ cd my-first-plugin
$ mkdir .claude-plugin
$ cat > .claude-plugin/plugin.json << 'EOF'
{
  "name": "my-first-plugin",
  "description": "一个问候插件",
  "version": "0.0.1",
  "author": {
    "name": "作者名称",
    "email": "作者邮箱"
  }
}
EOF

创建完成后目录结构和配置如下：

下面我们为插件创建一个简单的自定义命令，首先创建一个 commands 目录，可以手动创建，也可以通过以下命令创建：

shell 复制代码

$ mkdir commands

接着创建自定义命令 hello.md 文件

yaml 复制代码

$ cat > commands/hello.md << 'EOF'
---
description: 用个性化信息问候用户
---
# Hello Command
热情地问候用户，问问他们今天需要什么帮助。让问候语更具个性化且鼓舞人心。
# 要求
- 问候语以`^_^`开始
EOF

创建完成后目录结构和配置如下：

测试插件

启动Claude Code CLI，在交互式命令中输入以下命令添加插件市场

bash 复制代码

/plugin marketplace add ../my-marketplace

插件市场安装完成后，使用如下命令安装插件

perl 复制代码

/plugin install my-first-plugin@my-marketplace

安装完成后重启Claude Code CLI，在交互式命令中输入插件名称查找对应命令

任务执行完成后，执行结果如下：

自定义插件路径

配置完成后更新 my-marketplace 插件市场，进入插件管理此时就可以看到了刚刚添加的插件 my-second-plugin，安装插件

在交互式命令中输入关键词检索也可以看到刚刚添加的插件

也可以正常执行

自定义MCP服务

MCP服务配置在插件系统中算是比较特殊的存在，它没有默认的文件目录，只是一个 .mcp.json 文件。这里我们以插件默认目录方式为例，首先需要在插件根目录创建 .mcp.json 文件

shell 复制代码

$ touch .mcp.json

输入MCP配置JSON

perl 复制代码

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"]
    }
  }
}

更新插件市场，重启Claude Code CLI，在交互式指令中查看MCP信息，可以看到插件配置中的MCP服务已被正常启动

友情提示

见原文：如何从零开始创建一个Claude Code插件

本文同步自微信公众号 "程序员小溪" ，这里只是同步，想看及时消息请移步我的公众号，不定时更新我的学习经验。友情提示友情提示