How to build a custom Claude plugin?

In this article, you will learn how to build a custom Claude plugin. We will look at the following:

What is a Claude plugin?
Build a simple Claude plugin.

What is a Claude plugin?

You can create custom plugins to extend Claude Code with skills, agents, hooks, and MCP servers. Plugins let you extend Claude Code with custom functionality that can be shared across projects and teams.

When to use a plugin?

You can use a plugin when you want to share directories containing skills, agents, hooks etc., with teammates, things that are reusable across projects.

There is a also a standalone configuration, defined in .claude folder and this can be specific to a project, can include personal workflows or for quick experiments.

Learn more about when to use a plugin vs standalone configuration.

Let’s build a simple plugin following the official docs quick start guide..

Build a simple Claude plugin

There are 5 steps involved to create your first plugin.

Create the plugin directory

mkdir my-first-plugin

This folder can contain:

Skills
Agents or hooks
optionally, a .claude-plugin/plugin.json manifest

Create the plugin manifest.

You will define the metadata such as name, description, and version of your plugin. In plugin manager, this info is used by Claude Code to display your plugin.

// run this first
mkdir my-first-plugin/.claude-plugin

and then add this to my-first-plugin/.claude-plugin/plugin.json.

{
  "name": "my-first-plugin",
  "description": "A greeting plugin to learn the basics",
  "version": "1.0.0",
  "author": {
    "name": "Your Name"
  }
}

Learn more about the manifest schema..

Add a skill

Skills are added in the skills/ directory. Folder name becomes the skill name. First, create the skills directory in your plugin folder:

mkdir -p my-first-plugin/skills/helloaxios zustand

Then create the SKILL.md file in my-first-plugin/skills/hello/ folder:

---
description: "Greet the user with a friendly message"
disable-model-invocation: true
---

Greet the user warmly and ask how you can help them today.

Test your plugin

You need to load your plugin by running the below command:

claude --plugin-dir ./my-first-plugin

Once the Claude Code starts, you can try your new skill by running the below command:

/my-first-plugin:hello

You’ll see Claude respond with a greeting. Run /help to see your skill listed under the plugin namespace.

Add a skill argument

You can pass user input as an argument to your skill to make it dynamic. $ARGUMENTS placeholder captures any text user provides after the skill name.

Update your SKILL.md to use this $ARGUMENTS variable in your file.

---
description: Greet the user with a personalized message
---

# Hello Skill

Greet the user named "$ARGUMENTS" warmly and ask how you can help them today. Make the greeting personal and encouraging.

At this point, it is important that you run /reload-plugins to pick up changes and then you can run your skill as shown below: