Create your first Claude Code Plugin
Writing and Sharing Claude Code Plugins: A Beginner’s Guide
Claude Code plugins are those command invoked with “/< command name >” in the Code CLI, allowing to extend it with custom commands, agents, hooks, and integrations.
Anthropic has created a system that allows to create and distribute your own plugins, and in this guide I will walk you through creating your first one, using the classical “hello-world” example as a foundation: at the end of this tutorial you will be able to print the string “hello world!” on the Claude Code CLI invoking the command “/hello-world”
What Are Claude Code Plugins?
Plugins let you package reusable functionality that can be shared across projects and teams. Unlike standalone configurations in `.claude/`, plugins are:
Shareable: Distribute through marketplaces for easy installation
Versioned: Track releases using semantic versioning
Namespaced: Skill names like `/my-plugin:hello` prevent conflicts between plugins
Portable: Install the same skills/agents across multiple projects
Plugin Architecture
Every plugin requires a specific directory structure:
my-plugin/
├── .claude-plugin/
│ └── plugin.json # Plugin manifest (required)
├── commands/ # Slash command definitions
│ └── my-command.md
├── skills/ # Agent Skills with SKILL.md files
│ └── my-skill/
│ └── SKILL.md
├── agents/ # Custom agent definitions
│ └── my-agent.md
├── hooks/ # Event handlers
│ └── hooks.json
├── .mcp.json # MCP server configurations (optional)
└── .lsp.json # LSP server configurations (optional)The Hello-World Example
Let’s examine the simplest possible plugin to understand the fundamentals. You can find an implementation on my personal plugins marketplace on github here: https://github.com/GiacomoRobino/jack-claude-plugins . You can also try to add this plugin to your Claude Code to test the mechanism by yourself, as explained later
Directory Structure
plugins/hello-world/
├── .claude-plugin/
│ └── plugin.json
└── commands/
└── hello-world.mdStep 1: Create the Plugin Manifest
The `plugin.json` file defines your plugin’s identity. Claude Code uses this metadata to display your plugin in the plugin manager.
.claude-plugin/plugin.json
{
"name": "hello-world",
"version": "1.0.0",
"description": "A simple example plugin that prints 'hello world!' to the CLI",
"author": {
"name": "Author Name"
}
}Field definitions:
- name: Unique identifier and skill namespace. Skills are prefixed with this (e.g., `/hello-world:hello`).
- version: Track releases using semantic versioning (e.g., “1.0.0”).
- description: Shown in the plugin manager when browsing or installing plugins.
- author: Optional. Helpful for attribution.
Additional optional fields include `homepage`, `repository`, `license`, and `keywords`.
Step 2: Create a Command
Commands are markdown files with instructions for Claude to follow. The filename determines the command name.
commands/hello-world.md
# /hello-world Command
A simple example command that prints “hello world!” to the CLI.
## Instructions
When this command is invoked, simply output:
hello world!
That’s it! No other actions needed.
Step 3: Test Your Plugin
Run Claude Code with the `--plugin-dir` flag to load your plugin during development:
claude --plugin-dir ./plugins/hello-world
Then invoke your command:
/hello-world:hello-world
Creating a Plugin Marketplace
A marketplace is a catalog that lets you distribute plugins to others. It provides centralized discovery, version tracking, and automatic updates.
Marketplace Directory Structure
my-marketplace/
├── .claude-plugin/
│ └── marketplace.json # Marketplace catalog (required)
└── plugins/
├── hello-world/
│ ├── .claude-plugin/
│ │ └── plugin.json
│ └── commands/
│ └── hello-world.md
└── other-plugin/
└── ...The Marketplace File
Create `.claude-plugin/marketplace.json` in your repository root:
{
“$schema”: “https://anthropic.com/claude-code/marketplace.schema.json”,
“name”: “my-plugins”,
“version”: “1.0.0”,
“metadata”: {
“description”: “My collection of Claude Code plugins”
},
“owner”: {
“name”: “Your Name”,
“email”: “you@example.com”
},
“plugins”: [
{
“name”: “hello-world”,
“description”: “A simple example plugin that prints ‘hello world!’ to the CLI”,
“source”: “./plugins/hello-world”,
“category”: “examples”,
“keywords”: [”example”, “hello-world”, “tutorial”]
}
]
}Marketplace Schema
Required Fields:
- name (string): Marketplace identifier (kebab-case). Users see this when installing (e.g., `/plugin install my-tool@your-marketplace`).
- owner (object): Marketplace maintainer info (`name` required, `email` optional).
- plugins (array): List of available plugins.
Optional Metadata:
- metadata.description (string): Brief marketplace description.
- metadata.version (string): Marketplace version.
- metadata.pluginRoot (string): Base directory for relative plugin paths (e.g., `”./plugins”` lets you write `”source”: “formatter”` instead of `”./plugins/formatter”`).
Plugin Entry Fields
Each plugin in the `plugins` array requires:
- name (string): Plugin identifier (kebab-case).
- source (string|object): Where to fetch the plugin from.
Optional fields include `description`, `version`, `author`, `homepage`, `repository`, `license`, `keywords`, `category`, and `tags`.
Plugin Sources
Relative paths (for plugins in the same repository):
{
“name”: “my-plugin”,
“source”: “./plugins/my-plugin”
}GitHub repositories:
{
“name”: “github-plugin”,
“source”: {
“source”: “github”,
“repo”: “owner/plugin-repo”,
“ref”: “v2.0.0”
}
}Git repositories (GitLab, Bitbucket, self-hosted):
{
“name”: “git-plugin”,
“source”: {
“source”: “url”,
“url”: “https://gitlab.com/team/plugin.git”,
“ref”: “main”
}
}Hosting and Distributing Your Marketplace
Host on GitHub (Recommended, for other hostings look at Anthropic documentation in the links at the end of the article)
1. Create a repository for your marketplace
2. Add `.claude-plugin/marketplace.json` with your plugin definitions
3. Users add your marketplace with the command (note: the command must be invoked outside of Claude Code):
claude /plugin marketplace add owner/repo
Installing Plugins from a Marketplace
Add the Marketplace
/plugin marketplace add owner/repoBrowse Available Plugins
Run `/plugin` to open the plugin manager, then navigate to the **Discover** tab.
Install a Plugin
/plugin install plugin-name@marketplace-nameOr use the interactive UI to choose an installation scope:
- User scope: Install for yourself across all projects
- Project scope: Install for all collaborators on this repository
- Local scope: Install for yourself in this repository only
Use the Plugin
Finally, you can use your newly installed plugin. Plugin commands are namespaced by the plugin name:
/hello-world:hello-worldSummary
Creating and sharing Claude Code plugins involves:
1. Create the plugin: Add `.claude-plugin/plugin.json` manifest and your commands/skills/agents
2. Create the marketplace: Define `.claude-plugin/marketplace.json` listing your plugins
3. Host and share: Push to GitHub or another git host
4. Users install: They add your marketplace and install individual plugins
The hello-world example demonstrates the minimum viable plugin structure. From there, you can add agents for complex workflows, skills for model-invoked capabilities, hooks for automation, and MCP/LSP servers for integrations. In future articles I will go in depth examining more complex plugins, to open new possibilities with your agentic setup both for coding and non coding tasks.
References
- Link for testing hello-world plugin and view the files: https://github.com/GiacomoRobino/jack-claude-plugins
- Discover and Install Plugins: https://code.claude.com/docs/en/discover-plugins
- Create and Distribute a Plugin Marketplace: https://code.claude.com/docs/en/plugin-marketplaces
- Create Plugins: https://code.claude.com/docs/en/plugins
- Plugins Reference: https://code.claude.com/docs/en/plugins-reference