A Step-by-Step Guide: How to Create Your First Claude Code Plugin

Published: October 14, 2025 | Read time: 5 minutes

Ready to dive deep into Claude Code and create your own custom tools? This guide will walk you through the entire process of creating your first plugin. We'll build a simple "greeter" plugin that adds a custom slash command. It's the perfect starting point to familiarize yourself with the core concepts of the plugin system.

Prerequisites

Before you begin, make sure you have the following:

• Claude Code installed on your machine.
• A basic understanding of command-line tools.

Create Your First Plugin in Five Simple Steps

Let's get building! We'll create a local plugin marketplace and your very first plugin.

Step 1: Create the Marketplace Directory Structure

First, we need a directory to house our test marketplace and plugin.

mkdir test-marketplace
cd test-marketplace

Step 2: Create the Plugin Directory

Inside the marketplace directory, create a dedicated folder for your plugin.

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

Step 3: Create the Plugin Manifest (plugin.json)

Every plugin needs a manifest file to describe its metadata. This file is named plugin.json and is located in the .claude-plugin directory.

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

This JSON file tells Claude Code the essential information about your plugin, such as its name, description, and version.

Step 4: Add a Custom Slash Command

Now, let's add the first feature to our plugin: a custom /hello command. Commands are defined as Markdown files in the commands directory.

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

---

description: This part defines the command description that users will see when they list commands in Claude Code. Body Content: This is the instruction for Claude, telling it how to respond when the /hello command is executed.

Step 5: Create the Marketplace Manifest and Test

To make your local plugin discoverable by Claude Code, we need to create a marketplace manifest file in the test-marketplace directory.

First, navigate back to the test-marketplace directory:

cd .. 

Then, create the marketplace manifest:

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

This file registers my-first-plugin with your local test-marketplace.

Now, it's time to test your creation!

1. Launch Claude Code:

   cd .. 
   claude
   

2. Add Your Test Marketplace:

   /plugin marketplace add ./test-marketplace
   

3. Install Your Plugin:

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

   Select "Install Now" and restart Claude Code.

4. Try Your New Command:

   /hello
   

Congratulations! You'll see Claude greet you with the message you defined. You can also run /help to see your newly created /hello command in the list.

Plugin Structure Overview

The plugin you just created follows this basic structure:

my-first-plugin/
├── .claude-plugin/
│   └── plugin.json          # Plugin metadata
└── commands/                # Custom slash commands
    └── hello.md

Next Steps

You've successfully created and tested your first plugin! Now you can start exploring more complex features:

• Add More Commands: Create more Markdown files in the commands/ directory.
• Add Subagents: Define specialized AI assistants in an agents/ directory.
• Use Hooks: Automatically execute actions at specific events with hooks/hooks.json.
• Connect External Tools: Integrate MCP servers using a .mcp.json file.

For advanced development techniques and the complete technical specification, refer to the official Claude Code documentation.

Ready to see what others have built? Explore a rich ecosystem of community-made plugins at https://claudecodeplugins.dev/. Add the official community marketplace to get started:

/plugin marketplace add ccplugins/marketplace

Happy plugin developing!