DEV Community

Haruki Nakada
Haruki Nakada

Posted on

How to distribute and install a Claude Code mod with marketplace.json and /plugin install

#claude #plugin #softwaredevelopment

A mod is a plugin, so it's distributed and installed the same way as any plugin. To distribute, put .claude-plugin/marketplace.json in the repo and push. To install, add the marketplace with /plugin marketplace add owner/repo, then install with /plugin install name@marketplace-name. In the desktop app you can also install from + next to the prompt → Plugins → Add plugin (official install page).

Terms

Term Meaning
Plugin A single folder holding mods, skills, commands, MCP servers and so on. A mod is one kind
Marketplace A JSON file (marketplace.json) listing plugins and where to fetch each one. Usually kept in a GitHub repo
Plugin id name@marketplace-name. Used to install, remove and configure

Distributing: add marketplace.json

The simplest setup is to make the mod's own repo the marketplace. Put marketplace.json next to plugin.json.

hello-band/
├── .claude-plugin/
│   ├── plugin.json
│   └── marketplace.json
└── hooks/
    ├── hooks.json
    └── register.tsx
Enter fullscreen mode Exit fullscreen mode 
{
  "name": "hello-tools",
  "owner": { "name": "Your Name" },
  "description": "A mod that shows one line above the prompt",
  "plugins": [
    { "name": "hello-band", "source": "./" }
  ]
}
Enter fullscreen mode Exit fullscreen mode
  • name, owner and plugins are required. owner requires name
  • Each entry in plugins requires name and source
  • source: "./" points to the repo root (one level above .claude-plugin/)
  • Match the entry's name to the name in plugin.json (the official docs say to)
  • The marketplace name uses letters, digits, ., _ and -, and starts with a letter or digit. Official names like claude-plugins-official, names that look official, and names containing non-ASCII letters are rejected

Validate before pushing.

claude plugin validate .
Enter fullscreen mode Exit fullscreen mode

It's public the moment the files are pushed. There's no application process. If the repo is private, it becomes a private marketplace that only people who can clone it can install from.

Listing several mods in one repo

As your mods grow, you can create one repo for the marketplace and line them up under plugins/.

{
  "name": "hello-tools",
  "owner": { "name": "Your Name" },
  "plugins": [
    { "name": "hello-band", "source": "./plugins/hello-band" },
    { "name": "hello-pane", "source": "./plugins/hello-pane" }
  ]
}
Enter fullscreen mode Exit fullscreen mode

To list a mod that lives in another repo, make source an object.

{
  "name": "hello-band",
  "source": {
    "source": "github",
    "repo": "your-name/hello-band",
    "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
  }
}
Enter fullscreen mode Exit fullscreen mode

Pinning a version

A github source can have ref (a branch or tag) and sha (a 40-character lowercase commit). With sha, only that commit's contents are distributed. Even if the author changes things later, users won't get them until the marketplace's sha is updated.

When you list someone else's mod in your marketplace, pinning to the sha of the commit you read is the safe choice (part 10).

Bumping the version

If you put a version in plugin.json, bump it every time you change something. If you push without bumping, users' claude plugin update says "already up to date" and they keep the old copy. For git marketplaces you can also omit version, in which case the commit SHA becomes the version.

Installing: with commands

Type these inside a Claude Code session.

/plugin marketplace add your-name/hello-band
/plugin install hello-band@hello-tools
Enter fullscreen mode Exit fullscreen mode

your-name/hello-band on the first line is the GitHub owner/repo. What follows @ on the second line is the name in marketplace.json, not the repo name. Mixing these up and getting "not found" is very common.

  • Add # like owner/repo#v1.2.0 to pin to a branch or tag
  • For non-GitHub hosts use an https://...git URL; for a local folder use a path starting with ./
  • Both in one step: /plugin install hello-band --marketplace your-name/hello-band (Claude Code 2.1.275 and later)

/plugin install inside a session doesn't install immediately; it opens a details screen. There you review the contents (commands, hooks, MCP servers and so on) and pick a scope.

Scope Applies to Settings file written
User All your projects ~/.claude/settings.json
Project Everyone working in this repo .claude/settings.json (committed)
Local Only you, only this repo .claude/settings.local.json

You can do the same from a shell.

claude plugin marketplace add your-name/hello-band
claude plugin install hello-band@hello-tools
Enter fullscreen mode Exit fullscreen mode

When installed from a shell, type /reload-plugins in an open session to load it.

Installing: from the desktop app UI

The official install page describes these steps for the desktop app's Code tab (local or SSH sessions):

  1. Press + next to the prompt and choose Plugins → Add plugin
  2. A list of marketplace plugins opens; pick the one to install
  3. Choose the scope (user, project or local)

To disable or remove later, use + → Plugins → Manage plugins. This screen isn't available in cloud sessions.

However, the steps to add a marketplace itself from the desktop app UI aren't on the official page, so that is not verified. The list above shows only plugins from marketplaces you've already added. The terminal, local desktop sessions and VS Code read the same settings files, so if you run claude plugin marketplace add in a shell, it should show up in the desktop list as well. Whether typing /plugin marketplace add in the Code tab prompt works the same way on desktop is also not verified.

After installing, open a new session in the desktop app and check whether the band or pane appears.

Updating

  • By the user: claude plugin update hello-band@hello-tools, or Update now in the Installed tab of /plugin
  • Auto-update: off by default for marketplaces you added yourself. You can turn it on per marketplace in the Marketplaces tab of /plugin

With auto-update on, whatever the author pushes keeps coming in. Mods are code that runs without a sandbox, so for marketplaces from unfamiliar authors it's safer to leave it off and read before updating (part 10).

Don't rename

Don't change the name of a published mod. Users' installs are recorded as name@marketplace-name, so renaming makes the mod disappear for people who installed it. If you really must rename, map the old name to the new one with renames in marketplace.json. If you only want to change the display name, use displayName.

Distributing to Windows users

A source that uses command (a folder produced by a local command) with mode: "link" can't be installed on Windows (official marketplace reference). If you have Windows users, use copy. With ordinary github or ./ sources you don't need to worry about this.

Finding mods you can install

Among public mods on GitHub, fewer than you'd expect are listed in their repo's own marketplace.json and installable with the steps in this article. In the modscode review, 269 of 1,383 didn't meet this condition (as of 2026-10-06).

All 49 mods in the modscode reviewed gallery can be installed from their repo's marketplace.json, and each page shows the install commands. If you want to search reviewed mods inside a conversation with Claude, or have Claude read a mod's UI structure and review results, you can also connect the modscode MCP connector to Claude (read-only, no login).

This article was written with AI assistance (Claude) and checked against the official Claude Code docs; anything marked "not verified" could not be confirmed there.

Top comments (0)