Claude Code supports plugins — installable packages that add custom slash commands (called skills), agents, rules, and hooks. You can build your own plugin, publish it through a private Git marketplace, and share it with your team. This guide walks through the full process: creating the plugin structure, defining skills, publishing to a Git-based marketplace, and installing it globally.
The examples in this guide are run on WSL2 Ubuntu in Windows, but they work the same on any system with Claude Code CLI installed.
Prerequisites
- Claude Code CLI v2.1 or later
- A Git repository (GitHub, GitLab, or any Git remote) to host the plugin
- Basic familiarity with Markdown and JSON
What is a Claude Code Plugin?
A Claude Code plugin is a directory with a specific structure that Claude Code can discover, install, and load. Plugins can include:
- Skills — custom slash commands (e.g.,
/my-plugin:deploy) that expand into full prompts - Agents — specialized personas with domain-specific system prompts
- Rules — additional instruction files loaded into context
- Hooks — shell commands that run before or after tool calls
Plugins are distributed through marketplaces — Git repositories that Claude Code can pull from. You can use the official Anthropic marketplace or create your own private one.
Step 1 — Create the Plugin Directory Structure
Start by creating a new directory for your plugin. The minimum structure requires a .claude-plugin/ folder with a plugin.json manifest and a skills/ directory for your slash commands.
mkdir -p my-plugin/.claude-plugin
mkdir -p my-plugin/skillsHere is the full directory structure for a plugin with two skills:
my-plugin/
├── .claude-plugin/
│ ├── plugin.json # Plugin manifest (required)
│ └── marketplace.json # Marketplace catalog (required for distribution)
├── skills/
│ ├── greet/
│ │ └── SKILL.md # Skill definition
│ └── deploy/
│ └── SKILL.md # Another skill
├── CLAUDE.md # System instructions (optional)
└── README.mdStep 2 — Create the Plugin Manifest
The plugin.json file tells Claude Code about your plugin — its name, version, and where to find skills. Create .claude-plugin/plugin.json:
{
"name": "my-plugin",
"description": "A custom Claude Code plugin with deployment and greeting skills.",
"version": "1.0.0",
"author": {
"name": "Your Name"
},
"keywords": ["devops", "deployment", "automation"],
"skills": "./skills/"
}Key fields:
name— the plugin identifier, used as the prefix for skills (e.g.,/my-plugin:greet)version— semver string; bump this on every release or Claude Code won’t detect updatesskills— path to the directory containing skill definitions, relative to the plugin root
The skills field is critical. Without it, Claude Code won’t discover your slash commands even if the skills/ directory exists.
Step 3 — Create the Marketplace Manifest
The marketplace.json file defines which plugins are available in your marketplace. Create .claude-plugin/marketplace.json:
{
"name": "my-plugin-marketplace",
"owner": {
"name": "Your Name"
},
"metadata": {
"description": "Custom plugins for my team"
},
"plugins": [
{
"name": "my-plugin",
"source": "./",
"description": "A custom plugin with deployment and greeting skills."
}
]
}The source field points to the plugin root relative to the marketplace root. Since the marketplace and plugin live in the same repository, ./ means the repo root.
Step 4 — Define a Skill
Each skill lives in its own directory under skills/ and contains a single SKILL.md file. The file has YAML frontmatter (metadata) followed by Markdown instructions that Claude will follow when the skill is invoked.
Create skills/greet/SKILL.md:
---
name: greet
description: Generate a friendly greeting message for a team member or channel.
argument-hint: "[name or channel]"
---
# Greet
Generate a friendly, professional greeting for: $ARGUMENTS
Keep it short — 2-3 sentences max. Match the tone to whether it's a person or a channel.Frontmatter fields:
name— the skill name, used after the colon in the slash commanddescription— shown in the autocomplete menu when typing/argument-hint— placeholder text shown after the skill namedisable-model-invocation— set totrueif the skill should only expand the prompt without automatically invoking the model (optional)
The $ARGUMENTS variable is replaced with whatever the user types after the skill name. For example, /my-plugin:greet Alice replaces $ARGUMENTS with “Alice”.
Step 5 — Add a CLAUDE.md (Optional)
If your plugin needs system-level instructions that apply across all skills, add a CLAUDE.md file at the plugin root. Claude Code loads this file into context whenever the plugin is active.
# My Plugin Instructions
You are a helpful assistant with deployment expertise.
## Rules
- Always confirm before running destructive commands
- Use --dry-run flags when availableThis is useful for plugins that define agents or need consistent behavior across multiple skills.
Step 6 — Push to a Git Repository
Initialize a Git repo, commit everything, and push to your remote. This works with GitHub, GitLab, Bitbucket, or any Git host.
cd my-plugin
git init
git add .
git commit -m "feat: initial plugin with greet skill"
git remote add origin git@gitlab.com:your-group/my-plugin.git
git push -u origin mainStep 7 — Add the Marketplace in Claude Code
Open Claude Code in your terminal:
claudeThen type:
/pluginsNavigate to the Marketplaces tab using the arrow keys or Tab. Select + Add Marketplace and enter your repository URL:
git@gitlab.com:your-group/my-plugin.gitClaude Code clones the repository and registers it as a marketplace. You can enable auto-update so it pulls the latest changes on every startup.
Step 8 — Install the Plugin Globally
Still in /plugins, go to the Discover tab. Scroll down or search for your plugin name — it should appear under your marketplace. Select it and press Enter.
You will see three scope options:
- Install for you (user scope) — available in every project you open. This is the recommended option for global availability.
- Install for all collaborators on this repository (project scope) — available to anyone who clones the repo
- Install for you, in this repo only (local scope) — only available in the current directory
Select Install for you (user scope) to make the plugin available everywhere.
Step 9 — Verify the Installation
Restart Claude Code (exit and reopen), then type /. Your skills should appear in the autocomplete list:
/greet (my-plugin) Generate a friendly greeting message...Claude Code shows the short form (without the plugin prefix) when there are no naming conflicts. Both /greet and /my-plugin:greet work. The full prefix format is always available and recommended when you have multiple plugins installed.
Test it:
/my-plugin:greet the DevOps teamUpdating the Plugin
When you make changes to skills or add new ones:
- Bump the
versionin.claude-plugin/plugin.json(e.g.,1.0.0to1.1.0) - Commit and push to Git
- In Claude Code, run
/plugins→ Installed tab → select your plugin → Update
If you enabled auto-update on the marketplace, Claude Code pulls new versions automatically on startup. But it still compares the version field — if you don’t bump it, the update won’t apply.
Distributing to Your Team
To prompt teammates to install the plugin when they open a specific project, add this to that project’s .claude/settings.json:
{
"extraKnownMarketplaces": {
"my-plugin-marketplace": {
"source": {
"source": "git",
"url": "git@gitlab.com:your-group/my-plugin.git"
}
}
},
"enabledPlugins": {
"my-plugin@my-plugin-marketplace": true
}
}When a team member opens Claude Code in that project directory, they’ll be prompted to install the plugin.
Quick Reference — Plugin File Checklist
| File | Required | Purpose |
|---|---|---|
.claude-plugin/plugin.json |
Yes | Plugin name, version, skills path |
.claude-plugin/marketplace.json |
Yes (for distribution) | Marketplace catalog listing |
skills/<name>/SKILL.md |
Yes (for skills) | Slash command definition |
CLAUDE.md |
No | System instructions for the plugin |
settings.json |
No | Default agent, plugin settings |
hooks/hooks.json |
No | Pre/post tool call hooks |
rules/*.md |
No | Additional instruction files |
Conclusion
You now have a working Claude Code plugin with custom skills, published through a private Git marketplace, and installed globally. The same approach scales to any number of skills, agents, and rules — just add more directories under skills/ and bump the version.
If you’re new to Claude Code, start with How to Install Claude Code CLI on WSL2 Ubuntu. For PowerShell users, see How to Install and Configure Claude Code CLI on Windows PowerShell.
