TL;DR:A Claude Code marketplace is a GitHub repo with a specific folder structure. You create plugins inside it, push to GitHub, and anyone (including yourself) can install your plugins with two commands. This article shows you how to scaffold one from zero and add your first plugin. A one-command setup script comes later in the series, and auto-versioning plus release CI come pre-wired as a bonus in the starter template.
Every time I switched between my work machine and home setup, or got a new laptop, I'd lose an hour reinstalling the same Claude Code plugins and setting up the same tools. Wrong versions, configs I'd forgotten to copy over, the whole thing rebuilt from nothing. So I built a marketplace - a single GitHub repo that holds all my plugins and keeps them versioned.
Before we get into the structure: you can skip the scaffold entirely and use the starter template directly (link below). The rest of this article explains its structure.
Template: github.com/Nagell/claude-marketplace-template
You can pass this article URL directly to Claude Code and follow along.
A marketplace is a GitHub repository with a marketplace.json
registry that Claude Code reads to discover plugins. Each plugin lives in its own subdirectory and has a plugin.json
describing it.
There's no npm package and nothing to host, just a public repo.
your-marketplace/
├── .claude-plugin/
│ └── marketplace.json ← the plugin registry
├── plugins/
│ └── your-plugin/
│ ├── .claude-plugin/
│ │ └── plugin.json ← plugin metadata
│ ├── hooks/
│ │ ├── hooks.json ← hook wiring (which hooks fire when)
│ │ └── your-guard.sh ← the scripts hooks.json points to
│ ├── skills/ ← SKILL.md files (auto-loaded, or run with /name)
│ ├── agents/ ← agent definitions
│ └── .mcp.json ← MCP server config
├── .github/
│ └── workflows/
│ └── release.yml
├── scripts/
│ └── generate-release-config.js
└── CLAUDE.md
A plugin can contain any combination of these. Start with what you actually use - you don't need all of them.
Quite a bit more than you'd expect. A plugin can ship:
SKILL.md
files that give Claude instructions for a domain. Claude loads one on its own when it's relevant, or you run it by name with /your-plugin:skill-name
. A skill can be passive reference (a testing strategy, a code-review approach) or an action you trigger by hand..mcp.json
, giving Claude access to external tools and APIs.A skill isn't limited to passive knowledge. It's Markdown that Claude executes, so a single one can install a package manager, configure your terminal, set up Nerd Fonts, pull files from a repo, walk a whole setup through and so on.
You'll notice the plugin folder structure doesn't include a CLAUDE.md
. That's intentional.
A CLAUDE.md
inside a plugin folder is not a recognized plugin component - Claude Code's plugin system ignores it. If you want a plugin to ship AI instructions, SKILL.md
files in a skills/
directory are the correct mechanism. A plugin-level CLAUDE.md
has no automatic effect.
That said, there's a useful pattern: a plugin can ship a skill that explicitly offers to copy an opinionated CLAUDE.md
into the user's global ~/.claude/CLAUDE.md
. The user opts in, the skill handles the copy, and the result is a consistent global configuration across machines. We'll cover exactly this in the article about one-command setup.
.claude-plugin/marketplace.json
is the registry file Claude Code reads when someone adds your marketplace. Here's what it looks like when you're done:
{
"name": "your-marketplace-name",
"owner": { "name": "Your Name" },
"version": "1.0.0",
"description": "What your marketplace is for",
"plugins": [
{
"name": "your-plugin",
"source": "./plugins/your-plugin",
"version": "0.1.0",
"keywords": ["relevant", "tags"]
}
]
}
You'll manage this file yourself as you add plugins - updating the list and bumping versions when things change. The starter template automates that for you: a CI script syncs this registry from your individual plugin.json
files on every push, so you never have to touch it by hand, and auto-versioning from conventional commits rides along with it.
A plugin needs exactly one file to exist: plugins/your-plugin-name/.claude-plugin/plugin.json
.
{
"name": "your-plugin",
"version": "0.1.0",
"description": "What this plugin does",
"author": {
"name": "Your Name",
"email": "you@example.com"
},
"keywords": ["relevant", "tags"]
}
That's the minimum. Create the subdirectories for whatever components you're shipping (hooks, skills, agents) alongside it.
Push the repo. It needs to be public - Claude Code fetches marketplaces directly from GitHub.
Two commands inside Claude Code:
/plugin marketplace add your-username/your-marketplace-repo
This registers the marketplace with Claude Code. Replace your-username/your-marketplace-repo
with your GitHub username and repo name.
/plugin install your-plugin-name@your-marketplace-name
This installs a specific plugin. The format is <plugin-name>@<marketplace-name>
- the marketplace name comes from the
name
field in your marketplace.json
.
Bonus in the template:The starter template ships a GitHub Actions workflow and a sync script that drive version bumps from conventional commits (feat:
→ minor,fix:
→ patch) and keepmarketplace.json
in sync automatically. You don't build any of it - it's wired up and ready the moment you start from the template.
Under the hood it uses the Release Please GitHub Action and a small Node.js script. (The Action wraps the Release Please tool, which is where the docs live.) Conventional commits on main
create a Release PR; merging it publishes a tagged GitHub Release.
Once your marketplace is live, Claude Code can check for plugin updates automatically.
Via the UI: run /plugin
→ Marketplaces tab → select your marketplace → Enable "Auto-update". After an update, Claude will prompt you to run /reload-plugins
. No full restart required.
Alternatively - edit settings.json directly (useful if you're setting this up by hand or passing it to an agent):
{
"extraKnownMarketplaces": [
{
"url": "https://github.com/your-username/your-marketplace-repo",
"autoUpdate": true
}
]
}
Use the starter template to get a clean slate with everything pre-wired: github.com/Nagell/claude-marketplace-template.
The template gives you one empty plugin, a CLAUDE.md
with sensible defaults, and a GitHub Actions workflow that handles versioning and releases automatically. Hit "Use this template" on GitHub and you're ready to add your first plugin.
If you want to see a fuller working example with multiple plugins and real hook scripts, github.com/Nagell/claude-marketplace is the reference repo used throughout this series.