Create a Claude Code plugin

A plugin is a directory of skills, agents, hooks, and MCP servers, plus a plugin.json file, called the manifest, that names the plugin. Claude Code loads the directory as one unit, so you can share it with teammates, install it in several projects, or publish it to a marketplace. This page is for people writing their own plugins.

These cases are covered on other pages:

Installing someone else’s plugin: see Install plugins
Not sure you need a plugin: see Decide whether you need a plugin on the overview
Your plugin’s users are on claude.ai or in Cowork: the same folder installs there with a different subset of components. See Plugin structure and testing and the component support table

Start from the section that matches what you already have:

Nothing yet: follow Create your first plugin, then Develop without a marketplace and Test and debug.
Files under .claude/ already: do the first-plugin walkthrough once to learn the layout, then follow Convert an existing .claude/ setup.

Decide when to use a plugin

Skills, agents, hooks, and MCP servers all work standalone in your project or home directory. Keep that standalone setup while it serves one project or only you. Make a plugin when you want to share the setup with teammates, install it in several projects, or publish versioned releases. When you move standalone skills, agents, hooks, and MCP config into a plugin, their location and names change:

Where the files go: under the plugin’s own directory, called the plugin root, as skills/, agents/, hooks/hooks.json, and .mcp.json.
How they’re named: plugin skills and agents get the plugin name as a prefix, such as /my-plugin:hello, so two plugins can each provide a hello skill without colliding.

To move an existing setup into a plugin, see Convert an existing .claude/ setup.

Create your first plugin

In this walkthrough, you create a plugin whose only component is one skill, a greeting, and run it with --plugin-dir, which loads a plugin for one session without installing it. A plugin can hold any mix of components, such as skills, agents, hooks, and MCP servers, and none is required; one skill is the smallest example that shows the layout. You need Claude Code installed and signed in. Open a terminal in the directory where you want to keep the plugin, such as ~/projects, and run the commands in these steps from it. You can keep a plugin anywhere, because you pass its path to Claude Code when you start a session.

Create the plugin directory

Create the plugin directory, with a .claude-plugin/ folder inside it to hold the manifest:

mkdir -p my-first-plugin/.claude-plugin

Write the manifest

The manifest is a JSON file named plugin.json that tells Claude Code the plugin’s name and describes it. Save this one as my-first-plugin/.claude-plugin/plugin.json:

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"
  }
}

The four fields do this:

name: required. It identifies the plugin and becomes the prefix on every skill and agent the plugin provides. Don’t put spaces in it.
description: the text users see for the plugin in /plugin.
version: optional. Setting it keeps users on that version until you change it; Release a new version says when to set or omit it.
author: who to credit. name is required inside it; email and url are optional.

Every other field is on the manifest reference.Only plugin.json goes inside .claude-plugin/. The skill you add next goes directly under my-first-plugin/, next to that folder.

Add a skill

This plugin’s one component is a skill. Each skill is a directory under skills/ that contains a SKILL.md file. Create the skill’s directory:

mkdir -p my-first-plugin/skills/hello

Then create my-first-plugin/skills/hello/SKILL.md with this content:

my-first-plugin/skills/hello/SKILL.md

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

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

The disable-model-invocation: true line means Claude doesn’t run the skill on its own. Remove that line from a skill you want Claude to run on its own. The skill’s command combines the plugin name and the skill’s name, so you run this one as /my-first-plugin:hello. For the other frontmatter fields, see the skill frontmatter reference.

Validate the plugin

Check the manifest and the skill’s frontmatter before you run anything:

claude plugin validate ./my-first-plugin

The command prints the manifest path it checked and ✔ Validation passed. If it prints ✘ Validation failed instead, each line above that result line names the field to fix. Look up each message under claude plugin validate reports errors.

Run Claude Code with the plugin

Start a session with the plugin loaded:

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

Once Claude Code starts, run the skill:

Plugins

Use plugins

Create plugins

Mods

Run a marketplace

Manage plugins for your organization

Troubleshooting

Reference

Decide when to use a plugin

Create your first plugin

​Decide when to use a plugin

​Create your first plugin

Decide when to use a plugin

Create your first plugin