gh-bbrowning-bbrowning-claude-marketplace-bbrowning-claude/skills/marketplace-builder/reference/best-practices.md

Marketplace Best Practices

Comprehensive guide to organizing, versioning, distributing, and collaborating on Claude Code plugin marketplaces.

Organization

Group Related Plugins

Keep plugins with related functionality together in your marketplace. This improves discoverability and makes the marketplace purpose clear.

Good organization:

team-productivity/
├── code-review-helper/
├── pr-templates/
└── testing-utils/

Poor organization:

random-stuff/
├── unrelated-plugin-1/
├── totally-different-plugin-2/
└── another-random-thing/

Clear Naming

Use descriptive, kebab-case names for both the marketplace and plugins.

Good names:

• data-science-tools
• web-dev-utilities
• team-workflows

Avoid:

• stuff
• utils
• my-plugins

Documentation

Include a README.md explaining the marketplace purpose, available plugins, and installation instructions.

Essential README sections:

• Marketplace description and purpose
• List of plugins with brief descriptions
• Installation instructions
• Usage examples
• Contribution guidelines (if accepting contributions)

Consistent Structure

Maintain similar directory structure across plugins in your marketplace.

Example consistent structure:

marketplace/
├── plugin-one/
│   ├── .claude-plugin/
│   │   └── plugin.json
│   ├── skills/
│   └── commands/
├── plugin-two/
│   ├── .claude-plugin/
│   │   └── plugin.json
│   ├── skills/
│   └── commands/

Versioning

Marketplace Versioning

Track the marketplace version in marketplace.json to help users understand when significant changes occur.

{
  "name": "my-marketplace",
  "version": "1.2.0",
  "owner": {
    "name": "Your Name"
  }
}

Version increments:

• MAJOR: Breaking changes (plugin removed, structure changed)
• MINOR: New plugins added, significant updates
• PATCH: Bug fixes, documentation updates

Plugin Versioning

Each plugin maintains its own semantic version in its plugin.json.

{
  "name": "my-plugin",
  "version": "2.1.0"
}

Plugins version independently from the marketplace version.

Git Tags

Use git tags to mark marketplace releases, making it easy to reference specific versions.

git tag -a v1.2.0 -m "Release version 1.2.0"
git push origin v1.2.0

Users can then install specific versions:

/plugin marketplace add https://github.com/user/marketplace.git#v1.2.0

Changelog

Document changes in CHANGELOG.md following the Keep a Changelog format.

Example CHANGELOG.md:

# Changelog

## [1.2.0] - 2024-01-15

### Added
- New testing-utils plugin
- Documentation for all plugins

### Changed
- Updated code-review-helper to v2.0.0

### Fixed
- Fixed plugin paths in marketplace.json

Distribution

Public vs Private Repositories

Choose repository visibility based on your needs:

Public repositories:

• Open-source plugins for community use
• Sharing tools across teams in different organizations
• Building a plugin ecosystem

Private repositories:

• Internal team tools with proprietary logic
• Company-specific workflows
• Sensitive configurations or integrations

Access Control

Use repository permissions to control marketplace access:

GitHub/GitLab permissions:

• Public repos: Anyone can clone and use
• Private repos: Only authorized users can access
• Organization repos: Team-based access control

Documentation

Provide clear installation instructions in README.md:

## Installation

1. Add the marketplace:
   ```bash
   /plugin marketplace add https://github.com/team/marketplace.git

2. Browse available plugins:

   /plugin
   

3. Install a plugin:

   /plugin install plugin-name@marketplace-name
   

### Examples

Include example usage in README or individual plugin docs:

```markdown
## Example Usage

After installing the code-review-helper plugin:

1. Open a pull request
2. Run `/review` to analyze changes
3. Review the generated feedback

Collaboration

Team Marketplaces

Create shared marketplaces for standardized team workflows:

Benefits:

• Consistent tooling across team members
• Shared best practices encoded in plugins
• Easy onboarding for new team members
• Centralized maintenance

Example team structure:

team-engineering/
├── .claude-plugin/
│   └── marketplace.json
├── code-standards/
├── deployment-tools/
└── review-helpers/

Pull Request Workflow

Use PRs for plugin additions and updates:

Workflow:

1. Create feature branch for new plugin or update
2. Add/modify plugin in the marketplace
3. Update marketplace.json
4. Test locally
5. Submit PR with description of changes
6. Review and merge

PR template:

## Change Description
[New plugin / Plugin update / Bug fix]

## Plugin Name
plugin-name

## Testing
- [ ] Installed locally and tested
- [ ] All commands/skills work as expected
- [ ] Documentation is complete

## Checklist
- [ ] marketplace.json updated
- [ ] Plugin version incremented (if update)
- [ ] CHANGELOG.md updated

Code Review

Review plugin changes before merging:

Review checklist:

• Plugin manifest is valid
• Plugin name matches marketplace.json entry
• Documentation is clear and complete
• Skills/commands work as intended
• No sensitive information in code
• Follows team conventions

Testing

Test plugin installations before publishing updates:

Testing steps:

1. Clean environment test:

   # Uninstall existing version
   /plugin uninstall plugin-name@marketplace-name
   
   # Pull latest changes
   git pull
   
   # Reinstall
   /plugin install plugin-name@marketplace-name
   

2. Verify functionality:

   • Test all commands
   • Verify all skills load
   • Check for errors with claude --debug

3. Test on multiple platforms (if applicable):

   • macOS
   • Linux
   • Windows

Common Patterns

Personal Marketplace

Organize personal tools and utilities:

my-tools/
├── .claude-plugin/
│   └── marketplace.json
├── productivity/
│   └── .claude-plugin/
│       └── plugin.json
├── development/
│   └── .claude-plugin/
│       └── plugin.json
└── utilities/
    └── .claude-plugin/
        └── plugin.json

Use cases:

• Personal productivity tools
• Custom development helpers
• Workflow automation
• Learning and experimentation

Team Marketplace

Shared tools for engineering teams:

team-marketplace/
├── .claude-plugin/
│   └── marketplace.json
├── code-standards/
│   └── .claude-plugin/
│       └── plugin.json
├── deployment-tools/
│   └── .claude-plugin/
│       └── plugin.json
└── review-helpers/
    └── .claude-plugin/
        └── plugin.json

Use cases:

• Standardized code review processes
• Deployment automation
• Code generation templates
• Team-specific workflows

Community Marketplace

Public collection of domain-specific plugins:

community-plugins/
├── .claude-plugin/
│   └── marketplace.json
├── data-science/
│   └── .claude-plugin/
│       └── plugin.json
├── web-dev/
│   └── .claude-plugin/
│       └── plugin.json
└── devops/
    └── .claude-plugin/
        └── plugin.json

Use cases:

• Domain-specific tool collections
• Community-contributed plugins
• Open-source plugin ecosystem
• Educational resources

Hybrid Marketplace

Mix local and remote plugins:

{
  "name": "hybrid-marketplace",
  "plugins": [
    {
      "name": "internal-tool",
      "source": "./internal-tool",
      "description": "Company-specific internal tool"
    },
    {
      "name": "community-plugin",
      "source": "github:community/awesome-plugin",
      "description": "Popular community plugin"
    },
    {
      "name": "team-plugin",
      "source": "https://gitlab.company.com/team/plugin.git",
      "description": "Team plugin from GitLab"
    }
  ]
}

Use cases:

• Combining internal and external tools
• Curating best-of-breed plugins
• Gradual migration from monolithic to distributed
• Mixed public/private plugin collections

Key Takeaways

1. Organization: Group related plugins, use clear naming, document well
2. Versioning: Use semantic versioning for both marketplace and plugins
3. Distribution: Choose appropriate visibility, provide clear docs
4. Collaboration: Use PR workflow, review changes, test thoroughly
5. Patterns: Choose structure that matches your use case