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.

What is a Claude Code marketplace?

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.

Directory structure

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.

What can a plugin do?

Quite a bit more than you'd expect. A plugin can ship:

• Skills - 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.
• Hooks - Scripts that run before or after Claude uses a tool. Common uses: blocking dangerous shell commands, auto-formatting files after edits, logging.
• Agents - Named subagents with specific roles and tool access.
• MCP servers - Registered via .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.

A note on CLAUDE.md inside a plugin

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.

The marketplace.json

.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.

Creating your first plugin

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.

Publish on GitHub

Push the repo. It needs to be public - Claude Code fetches marketplaces directly from GitHub.

Install from your marketplace

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.

Auto-versioning and CI

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 keep marketplace.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.

Enable auto-updates

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

Get started

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.

In this series

1. Build Your Own Claude Code Marketplace: Scaffold, Structure, and Auto-Updates ← you are here
2. Claude Code Safety: Hooks, Sandboxes, and Running Autonomously Without the Paranoia (coming soon)
3. Install Everything You Need in One Command: Claude Code Plugin Setup (coming soon)
4. Save 60-90% of Your Claude Code Tokens With Two Tools (coming soon)