github.com/bfreis/claude-mart

A Claude Code plugin marketplace.

Adding a New Plugin

1. Create the plugin directory structure

plugins/your-plugin-name/
├── .claude-plugin/
│   └── plugin.json
└── ... (skills, commands, agents, etc.)

2. Create the plugin manifest (plugins/your-plugin-name/.claude-plugin/plugin.json)

This file contains metadata about the installed plugin, shown in the Manage Plugins interface and /help output.

{
  "name": "your-plugin-name",
  "version": "1.0.0",
  "description": "Brief summary of what the plugin does",
  "author": {
    "name": "Your Name",
    "email": "you@example.com"
  },
  "skills": ["./skills/skill-name.md"],
  "commands": ["./commands/command-name.md"],
  "agents": ["./agents/agent-name.md"]
}

Field	Required	Purpose
name	Yes	Plugin identifier (kebab-case)
version	Yes	Semantic version
description	Yes	Brief summary shown to users who have the plugin installed
author	Yes	Object with name, email, and optionally url
skills, commands, agents, hooks, mcpServers	No	Relative paths (starting with ./) to component files

3. Register the plugin in marketplace.json (.claude-plugin/marketplace.json)

Add an entry to the plugins array. This description is shown in the Browse Plugins interface when users discover new plugins.

{
  "plugins": [
    {
      "name": "your-plugin-name",
      "source": "./plugins/your-plugin-name",
      "description": "Detailed description for plugin discovery. Explain what the plugin does, its benefits, and use cases to help users decide whether to install it."
    }
  ]
}

Field	Required	Purpose
name	Yes	Must match the plugin's plugin.json name
source	Yes	Relative path to the plugin directory
description	No	Detailed description for browsing/discovery (can be longer than plugin.json's)
category, tags	No	Optional marketplace-specific metadata for organization

Description field differences

The two description fields serve different purposes:

• marketplace.json description: Shown when users browse available plugins (/plugin → Browse). Use a detailed, promotional description to help users understand the value before installing.

• plugin.json description: Shown after installation in the management interface and /help. Use a brief summary of what the plugin does.

Versioning Policy

This marketplace follows strict semantic versioning. Plugin authors must bump the version number in plugin.json for every change that users should receive.

Why version bumps are required

The Claude Code plugin update mechanism may not automatically detect code changes without a version bump. To ensure users receive updates reliably:

1. Always bump the version when pushing changes to a plugin
2. Never push code changes without a version bump — users may not receive the update
3. Use semantic versioning to communicate the nature of changes

Semantic versioning rules

Change type	Version bump	Example
Bug fixes, minor tweaks	Patch	1.0.0 → 1.0.1
New features, backward-compatible	Minor	1.0.1 → 1.1.0
Breaking changes	Major	1.1.0 → 2.0.0

What counts as a breaking change?

• Removing or renaming skills, commands, or agents
• Changing behavior that users depend on
• Requiring new permissions or dependencies

Version consistency

Two users with the same version number should always have identical plugin behavior. This means:

• Don't push multiple commits under the same version
• If you find a bug right after releasing, bump to a new patch version rather than amending
• Treat each version as immutable once pushed