zhongwei/gh-bbrowning-bbrowning-claude-marketplace-bbrowning-claude
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-29 18:00:42 +08:00
commit cc49e355bc
37 changed files with 10917 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

427
skills/marketplace-builder/SKILL.md Normal file
View File

@@ -0,0 +1,427 @@
---
name: Creating and Managing Plugin Marketplaces
description: Use before creating or editing marketplace.json files, setting up marketplace repositories, or when user asks about plugin distribution. Provides expert guidance on marketplace structure, manifest configuration, plugin organization, semantic versioning, and git-based distribution workflows. Invoke when working with marketplace files or discussing how to share multiple plugins to ensure correct manifest structure and installation compatibility.
---
# Claude Code Marketplace Builder
## What is a Marketplace?
A marketplace is a collection of Claude Code plugins that can be shared as a cohesive unit. Marketplaces enable:
- Centralized distribution of multiple related plugins
- Version control and sharing via git repositories
- Team-wide or community-wide plugin discovery
- Organized collections of plugins by theme, team, or purpose
## Marketplace Directory Structure
A marketplace follows this structure:
```
my-marketplace/
├── .claude-plugin/
│ └── marketplace.json # Marketplace manifest (REQUIRED)
├── plugin-one/
│ └── .claude-plugin/
│ └── plugin.json # Individual plugin manifest
├── plugin-two/
│ └── .claude-plugin/
│ └── plugin.json
└── README.md # Documentation (recommended)
```
### Key Points
- Marketplace manifest must be at `.claude-plugin/marketplace.json` in the marketplace root
- Each plugin within the marketplace has its own `plugin.json` manifest
- Plugins can be in any subdirectory structure you prefer
- Git version control is recommended for sharing and collaboration
## Marketplace Manifest (marketplace.json)
### Location and Requirements
The marketplace manifest MUST be located at:
```
.claude-plugin/marketplace.json
```
This file defines the marketplace metadata and lists all available plugins.
### Required Fields
```json
{
"name": "my-marketplace",
"owner": {
"name": "Your Name"
},
"plugins": []
}
```
**Field Descriptions:**
- `name`: Marketplace identifier in kebab-case (e.g., "team-tools", "data-science-plugins")
- `owner.name`: Maintainer's name (REQUIRED)
- `owner.email`: Maintainer's email (OPTIONAL)
- `plugins`: Array of plugin entries (can be empty initially)
### Optional Metadata Fields
```json
{
"name": "my-marketplace",
"description": "Marketplace description",
"version": "1.0.0",
"owner": {
"name": "Your Name",
"email": "you@example.com"
},
"homepage": "https://github.com/username/marketplace",
"plugins": []
}
```
**Additional Fields:**
- `description`: Brief overview of the marketplace's purpose
- `version`: Marketplace version (semantic versioning)
- `homepage`: URL to marketplace documentation or repository
## Adding Plugins to Marketplace
### Plugin Entry Structure
Each plugin in the `plugins` array requires:
```json
{
"plugins": [
{
"name": "plugin-name",
"source": "./plugin-directory",
"description": "Brief description"
}
]
}
```
**Plugin Entry Fields:**
- `name`: Plugin identifier (MUST match the plugin's `plugin.json` name)
- `source`: Path or URL to plugin (see Plugin Sources section)
- `description`: Brief description (optional but recommended for discoverability)
### Example with Multiple Plugins
```json
{
"name": "team-productivity",
"owner": {
"name": "Engineering Team"
},
"description": "Productivity tools for our engineering team",
"plugins": [
{
"name": "code-review-helper",
"source": "./code-review-helper",
"description": "Automated code review assistance"
},
{
"name": "pr-templates",
"source": "./pr-templates",
"description": "Standardized PR templates and workflows"
},
{
"name": "testing-utils",
"source": "./testing-utils",
"description": "Test generation and coverage tools"
}
]
}
```
## Plugin Sources
Plugin sources in marketplace.json support multiple formats:
### Local Path (Relative)
```json
{
"name": "local-plugin",
"source": "./local-plugin"
}
```
Use for plugins stored within the marketplace directory. Paths must be relative to the marketplace root.
### GitHub Repository
```json
{
"name": "github-plugin",
"source": "github:username/repo"
}
```
Use for plugins hosted on GitHub. Claude Code will clone the repository.
### Git URL
```json
{
"name": "git-plugin",
"source": "https://github.com/username/repo.git"
}
```
Use for plugins hosted on any Git provider. Full git URLs are supported.
### Mixed Sources Example
```json
{
"plugins": [
{
"name": "internal-tool",
"source": "./internal-tool",
"description": "Internal team tool"
},
{
"name": "community-plugin",
"source": "github:community/awesome-plugin",
"description": "Community-maintained plugin"
},
{
"name": "external-tool",
"source": "https://gitlab.com/team/tool.git",
"description": "External Git repository"
}
]
}
```
## Creating a Marketplace: Step-by-Step
### Step 1: Create Marketplace Directory
```bash
mkdir my-marketplace
cd my-marketplace
```
### Step 2: Create Marketplace Manifest
```bash
mkdir .claude-plugin
```
Create `.claude-plugin/marketplace.json`:
```json
{
"name": "my-marketplace",
"owner": {
"name": "Your Name"
},
"plugins": []
}
```
### Step 3: Initialize Git (Recommended)
```bash
git init
```
Version control enables:
- Easy sharing via repository URL
- Version history tracking
- Collaboration workflows
- Distribution to users
### Step 4: Add Plugins
For each plugin you want to include:
1. Create plugin directory:
```bash
mkdir my-plugin
mkdir my-plugin/.claude-plugin
```
2. Create plugin manifest (my-plugin/.claude-plugin/plugin.json):
```json
{
"name": "my-plugin",
"version": "1.0.0",
"description": "Plugin description"
}
```
3. Add plugin components (skills, commands, agents, etc.)
4. Update marketplace.json:
```json
{
"plugins": [
{
"name": "my-plugin",
"source": "./my-plugin",
"description": "Plugin description"
}
]
}
```
### Step 5: Test Locally
Add marketplace to Claude Code:
```bash
/plugin marketplace add /path/to/my-marketplace
```
Install and test plugins:
```bash
/plugin install my-plugin@my-marketplace
```
Verify installation:
- Run `/plugin` to see installed plugins
- Check `/help` for new commands
- Test plugin functionality
## Local Development Workflow
### Testing Changes
When modifying plugins in your marketplace:
1. **Uninstall old version:**
```bash
/plugin uninstall plugin-name@marketplace-name
```
2. **Reinstall updated version:**
```bash
/plugin install plugin-name@marketplace-name
```
Alternatively, restart Claude Code to reload all plugins.
### Development Iteration
Recommended workflow:
1. Make changes to plugin files
2. Uninstall → Reinstall plugin
3. Test functionality
4. Commit changes to git
5. Repeat as needed
### Debugging
Use debug mode to troubleshoot:
```bash
claude --debug
```
This shows:
- Marketplace loading status
- Plugin loading status
- Manifest validation errors
- Component registration
- Any warnings or errors
## Distribution and Sharing
### Sharing Your Marketplace
1. **Commit to git:**
```bash
git add .
git commit -m "Add marketplace with plugins"
```
2. **Push to remote repository:**
```bash
git remote add origin <repository-url>
git push -u origin main
```
3. **Share with users:**
Users add your marketplace:
```bash
/plugin marketplace add <repository-url>
```
Or for local paths:
```bash
/plugin marketplace add /path/to/marketplace
```
4. **Install plugins:**
```bash
/plugin install plugin-name@marketplace-name
```
### Managing Plugin Lifecycle
Users can manage installed plugins:
```bash
# Enable plugin
/plugin enable plugin-name@marketplace-name
# Disable plugin
/plugin disable plugin-name@marketplace-name
# Uninstall plugin
/plugin uninstall plugin-name@marketplace-name
```
## Testing Checklist
Before distributing your marketplace:
- [ ] marketplace.json has required fields (name, owner, plugins)
- [ ] All plugin entries have name and source
- [ ] Plugin names match their plugin.json names
- [ ] Local plugin paths are relative and start with `./`
- [ ] All plugins install without errors
- [ ] Tested with `claude --debug` for warnings
- [ ] README.md documents marketplace purpose and plugins
- [ ] Repository is properly initialized with git
- [ ] All changes are committed
## Best Practices
For comprehensive best practices on organization, versioning, distribution, and collaboration, see `reference/best-practices.md`.
## Key Takeaways
### Marketplace Essentials
1. Marketplace manifest MUST be at `.claude-plugin/marketplace.json` (not root)
2. Each plugin entry needs `name`, `source`, and optionally `description`
3. Plugin sources can be local paths (`./plugin`), GitHub repos (`github:user/repo`), or Git URLs
4. Add marketplace once: `/plugin marketplace add <path-or-url>`
5. Install plugins: `/plugin install plugin-name@marketplace-name`
### Development Workflow
1. Create marketplace directory with `.claude-plugin/marketplace.json`
2. Add plugins with their own `plugin.json` manifests
3. Test locally before sharing: `/plugin marketplace add /local/path`
4. Use git for version control and distribution
5. Update workflow: uninstall → reinstall or restart Claude Code
### Distribution
1. Share via git repository URL or local path
2. Users add marketplace, then browse/install plugins
3. Marketplace can mix local and remote plugin sources
4. Use semantic versioning for both marketplace and plugins
5. Document installation and usage in README
## Common Patterns
For detailed examples of personal, team, community, and hybrid marketplace patterns, see `reference/best-practices.md`.

410
skills/marketplace-builder/reference/best-practices.md Normal file
View File

@@ -0,0 +1,410 @@
# 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.
```json
{
"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.
```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.
```bash
git tag -a v1.2.0 -m "Release version 1.2.0"
git push origin v1.2.0
```
Users can then install specific versions:
```bash
/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**:
```markdown
# 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:
```markdown
## Installation
1. Add the marketplace:
```bash
/plugin marketplace add https://github.com/team/marketplace.git
```
2. Browse available plugins:
```bash
/plugin
```
3. Install a plugin:
```bash
/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**:
```markdown
## 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:
```bash
# 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:
```json
{
"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