Marketplace Publishing Expert

Expert guidance for publishing Claude Code plugins to npm and marketplace.

Publishing Platforms

1. GitHub (Recommended):

Install from GitHub

claude plugin add github:username/plugin-name

Pros:

• Free hosting
• Version control
• Issue tracking
• Easy updates

Requirements:

• Public repository
• Proper directory structure
• README with installation

2. npm:

Install from npm

claude plugin add plugin-name

Pros:

• Centralized registry
• Semantic versioning
• Easy discovery

Requirements:

• npm account
• package.json
• Unique name (prefix: claude-plugin-)

3. Marketplace:

Official Claude Code marketplace

PR to marketplace repository

Requirements:

• Quality standards
• Complete documentation
• No security issues
• Proper licensing

Semantic Versioning

Version Format: MAJOR.MINOR.PATCH

Rules:

MAJOR (1.0.0 → 2.0.0):

• Breaking changes
• Remove commands
• Change skill keywords
• Incompatible API changes

MINOR (1.0.0 → 1.1.0):

• New features
• Add commands
• Add skills
• Backward compatible

PATCH (1.0.0 → 1.0.1):

• Bug fixes
• Documentation updates
• Performance improvements
• No API changes

Examples:

Bug fix

npm version patch # 1.0.0 → 1.0.1

New feature

npm version minor # 1.0.1 → 1.1.0

Breaking change

npm version major # 1.1.0 → 2.0.0

package.json Setup

Minimum:

{ "name": "claude-plugin-my-plugin", "version": "1.0.0", "description": "Expert [domain] plugin for Claude Code", "keywords": ["claude-code", "plugin", "keyword1"], "author": "Your Name", "license": "MIT", "files": [ ".claude-plugin", "commands", "skills", "agents", "README.md", "LICENSE" ] }

Full:

{ "name": "claude-plugin-my-plugin", "version": "1.0.0", "description": "Expert [domain] plugin with [features]", "main": "index.js", "scripts": { "test": "echo "No tests yet"", "validate": "bash validate.sh" }, "keywords": [ "claude-code", "plugin", "development-tools", "keyword1", "keyword2" ], "author": "Your Name <you@example.com>", "license": "MIT", "repository": { "type": "git", "url": "https://github.com/username/my-plugin" }, "homepage": "https://github.com/username/my-plugin#readme", "bugs": { "url": "https://github.com/username/my-plugin/issues" }, "files": [ ".claude-plugin//*", "commands//", "skills/**/", "agents/**/*", "README.md", "LICENSE" ] }

Publishing Workflow

GitHub Release:

1. Update version

npm version patch

2. Commit changes

git add . git commit -m "Release v1.0.1"

3. Create tag

git tag v1.0.1

4. Push

git push && git push --tags

5. Create GitHub release

gh release create v1.0.1
--title "v1.0.1"
--notes "Bug fixes and improvements"

npm Publish:

1. Login

npm login

2. Validate package

npm pack --dry-run

3. Publish

npm publish

4. Verify

npm view claude-plugin-my-plugin

Documentation Requirements

README.md:

Plugin Name

One-line tagline

Brief description.

Features

• Feature 1
• Feature 2

Installation

```bash claude plugin add github:user/plugin ```

Commands

/plugin:command

Description.

Examples

[Working examples]

License

MIT

CHANGELOG.md:

Changelog

[1.0.1] - 2025-01-15

Fixed

• Bug fix 1
• Bug fix 2

[1.0.0] - 2025-01-01

Added

• Initial release

Quality Checklist

Pre-publish:

• ✅ All commands working

• ✅ Skills activate correctly

• ✅ No hardcoded secrets

• ✅ README with examples

• ✅ LICENSE file

• ✅ Semantic versioning

• ✅ CHANGELOG updated

• ✅ Git tag created

Post-publish:

• ✅ Test installation

• ✅ Verify on npm (if published)

• ✅ Check GitHub release

• ✅ Update marketplace (if applicable)

Publish professional Claude Code plugins!