AI Weekly

Guides ·

How to build and distribute a Claude Code plugin — bundle skills and agents into a one-line install

A Claude Code plugin bundles skills, subagents, hooks and MCP servers into one folder. What goes in plugin.json, how to test with --plugin-dir, how to check it with claude plugin validate, how to distribute through marketplace.json, and an example of shipping it all from one repo.

Key takeaways

A Claude Code plugin is a folder that bundles skills, subagents, hooks and MCP servers into one unit. The manifest is .claude-plugin/plugin.json, and the only required field is name. skills/, agents/, hooks/hooks.json and .mcp.json go at the plugin root, not inside .claude-plugin/. Plugin skills are called as /plugin-name:skill-name. While building, load it for a single session with claude --plugin-dir and check it with claude plugin validate. There are three ways to distribute: hand over the folder or a .zip, your own marketplace (a git repo containing .claude-plugin/marketplace.json), or submitting to the Anthropic directory. Users install with claude plugin marketplace add owner/repo followed by claude plugin install name@marketplace. If you set version, you must bump it on every release for updates to reach users.

Claude Code: A Hands-On Guide · Part 6 of 10

The short version: a plugin is packaging that bundles skills, subagents and hooks into one folder so other people can install them with one command. Put .claude-plugin/plugin.json at the top of the folder, and folders like skills/ and agents/ next to it. To distribute it, add one more file, marketplace.json, to the git repo that holds the folder, and you're done. This post was written by AI (Claude) and checked against the official Claude Code docs — Plugins and the pages under it.

When to make a plugin

Skills, subagents, hooks and MCP servers all work without a plugin. The skills from part 5 work in all your projects if you put them in ~/.claude/skills/. The official docs draw the line like this:

Two things change when you move them into a plugin. The files move under the plugin folder, and the plugin name is prefixed to their names. A hello skill becomes /my-plugin:hello. So two plugins can have skills with the same name without clashing.

There is a cost too. An enabled plugin comes into every session. Its skills' and agents' names and descriptions go into context on every turn, and its hooks run on every event. All of it runs with your permissions.

Folder layout

The top folder of a plugin is called the "plugin root." Only create the folders you use.

Location Contains
.claude-plugin/plugin.json The manifest (name, description, version, etc.)
skills/<name>/SKILL.md Skills. One per folder
agents/<name>.md Subagents. One per file
hooks/hooks.json Hooks configuration
.mcp.json MCP server definitions
commands/ Old-style commands. Use skills/ for new ones

Two things the official docs flag as warnings:

plugin.json fields

From the official docs: the manifest is optional, and if you write one, the only required field is name. Without a manifest, whatever is found in the default folders is loaded, and the name comes from the folder name (or the marketplace entry).

Field What it controls
name Plugin identifier. kebab-case. Prefixed to every skill and agent name
displayName Name shown on screen instead of name. Spaces allowed
version Version string. If set, users stay on that version until you change it
description Description shown in /plugin
author name required, email and url optional
homepage Docs URL. If it doesn't parse as a URL, the plugin won't load
repository, license, keywords Repo address, SPDX license (MIT etc.), search tags
userConfig Values to ask the user for when enabling (use sensitive: true for tokens)

The skills, agents, hooks and mcpServers fields can point to locations other than the default folders. Paths are relative to the plugin root, must start with ./, and the plugin won't load if .. points outside the root.

Unknown top-level fields are dropped without an error, and validation only shows a warning.

Build your first plugin and run it

This is the order of the first example in the official docs.

mkdir -p my-first-plugin/.claude-plugin
mkdir -p my-first-plugin/skills/hello

my-first-plugin/.claude-plugin/plugin.json:

{
  "name": "my-first-plugin",
  "description": "A greeting plugin to learn the basics",
  "version": "1.0.0",
  "author": { "name": "Your Name" }
}

skills/hello/SKILL.md is a skill file exactly like the ones in part 5. Now validate it and load it.

claude plugin validate ./my-first-plugin
claude --plugin-dir ./my-first-plugin

If validation passes, it prints ✔ Validation passed. Once the session starts, type /my-first-plugin:hello.

If you already built things in .claude/

Copy skills, agents and commands from under .claude/ to the plugin root, and move the hooks block from settings.json into hooks/hooks.json in the same shape. One caution: until you delete the originals, hooks run twice, because hooks have no plugin-name prefix to tell them apart. Confirm the plugin works, then delete the originals.

Three ways to distribute

Route Who installs Updates
Hand over the folder or a .zip Whoever receives it None. They keep the copy they got
Your own marketplace Anyone with access to the repo (private repos work) When the user runs claude plugin update, or has auto-update on
Submit to the Anthropic directory People who add it in claude.ai or Cowork. It also reaches Claude Code via account sync After the submitted version is published

Directory submission requires a paid claude.ai plan and is done in the developer portal at claude.ai/directory/manage. The official marketplace (claude-plugins-official) does not take submissions through this portal.

Making a marketplace

A marketplace is a list, not a store. It is a folder or repo containing .claude-plugin/marketplace.json, where you write plugin names and where to fetch them from. The three required fields are name, owner and plugins, and each entry in plugins needs name and source.

Choose source based on where the plugin lives:

source When to use
A relative path like "./plugins/my-plugin" The plugin is in the same repo
github The plugin is its own GitHub repo
git-subdir It's a subfolder of another repo (a monorepo)
url, archive, npm, command Another git host, an HTTPS zip, an npm package, command output

Relative paths are counted from the marketplace root, outside .claude-plugin/. The official docs say most install failures come from getting that base wrong, or from the entry's name not matching the name in plugin.json. Keep the two names the same.

After you push, users type two lines in their shell:

claude plugin marketplace add your-org/your-marketplace
claude plugin install deploy-helper@your-marketplace

The install ID is plugin-name@marketplace-name. From Claude Code v2.1.275, you can do both at once inside a session with /plugin install deploy-helper --marketplace your-org/your-marketplace.

Example: marketplace and plugin in one repo

This is a common layout when you're shipping a single plugin on your own. One repo is both the marketplace and the plugin's home. The example name is team-tools.

team-tools/
├── .claude-plugin/
│   └── marketplace.json      (marketplace list)
└── plugin/                   (plugin root)
    ├── .claude-plugin/
    │   ├── plugin.json
    │   └── icon.png
    ├── skills/review/SKILL.md
    ├── agents/               (checker.md etc.)
    └── README.md

marketplace.json at the top of the repo:

{
  "name": "team-tools",
  "owner": { "name": "your-org" },
  "plugins": [
    { "name": "team-tools", "source": "./plugin" }
  ]
}

plugin/.claude-plugin/plugin.json:

{
  "name": "team-tools",
  "displayName": "Team Tools",
  "version": "0.1.0",
  "description": "Review skill and checker agent for our team",
  "author": { "name": "your-org" },
  "license": "MIT",
  "icon": "./.claude-plugin/icon.png",
  "privacyPolicyUrl": "https://example.com/privacy"
}

Checked against the official docs:

  1. The plugin lives in a plugin/ subfolder. That's why source is "./plugin", and it doesn't mix with the repo's other code.
  2. Both the marketplace entry and plugin.json use the name team-tools. The install ID becomes team-tools@team-tools.
  3. Agents get the plugin name prefixed, like team-tools:checker. The skill is /team-tools:review too. Writing /review in the README is a common mistake. Plugin agents ignore the permissionMode, hooks, mcpServers and initialPrompt frontmatter, so put hooks and MCP servers at the plugin level.
  4. icon and privacyPolicyUrl are fields Claude Code doesn't read. The Anthropic directory listing reads them. The official docs say to put these fields only in plugin.json, not in the marketplace entry.
  5. version is set. So the number has to go up on every release (see the mistakes list below).

The install instructions in the README can be one line:

/plugin install team-tools --marketplace your-org/team-tools

On versions older than v2.1.275, type /plugin marketplace add your-org/team-tools and then /plugin install team-tools@team-tools separately.

Common mistakes

FAQ

What is the difference between a plugin and a skill?

A skill is a single SKILL.md describing how to do a job, and a plugin is the packaging that bundles skills, subagents, hooks and MCP servers. Bundle them into a plugin when you share them with others or ship them with a version number.

What should I check before distributing?

Run claude plugin validate --strict ./your-plugin in your shell. --strict treats warnings as failures too. Run it on a marketplace folder and it also checks marketplace.json and the plugin.json of every relative-path plugin.

Can I put "claude" in the name?

A name starting with claude- or anthropic- fails validation with an error. Having it as a word in the middle, like mcp-for-claude, gives a warning. Marketplace names also can't use official names like claude-plugins-official.

Sources

#Claude Code#plugins#Claude Code plugins#plugin.json#marketplace#marketplace.json#distribution

Written with AI (Claude) and checked against the linked sources.

Lab

Experiment 01

AI Type Test

How do you actually use AI? 15 types, Lv.1–10, and where you rank among people in your line of work.

3 min10 questions15 typesStart

More posts