personal-projects/leo-claude-mktplace
Template
0
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
817cc3d7bfc11c81f02d4b875a2ab56b8cfe7014
leo-claude-mktplace/.claude/skills/claude-plugin-developer/references/marketplace-guide.md

8.8 KiB
Raw Blame History

Marketplace Publication Guide

Complete guide for distributing Claude plugins through marketplaces.

Marketplace Types

GitHub Marketplace

Best for: Open source, team collaboration, public distribution

# Add marketplace
claude plugin marketplace add owner/repo

# Structure required
repo/
├── .claude-plugin/
│   └── marketplace.json
└── plugins/
    ├── plugin-one/
    ├── plugin-two/
    └── plugin-three/

GitLab Marketplace

Best for: Private teams, enterprise environments

# Add GitLab marketplace
claude plugin marketplace add gitlab:group/project

# Requires access token
export GITLAB_TOKEN="your-token"

Local Marketplace

Best for: Development, testing, private plugins

# Add local marketplace
claude plugin marketplace add file:///path/to/marketplace

# Structure
/path/to/marketplace/
├── .claude-plugin/
│   └── marketplace.json
└── plugins/

Remote URL Marketplace

Best for: Custom hosting, CDN distribution

# Add remote marketplace
claude plugin marketplace add https://plugins.example.com

Marketplace Configuration

marketplace.json Structure

{
  "name": "Hyper Hive Labs Plugins",
  "description": "Restaurant automation and AI tools",
  "version": "1.0.0",
  "plugins": [
    {
      "name": "restaurant-analytics",
      "version": "2.1.0",
      "description": "Analytics dashboard for restaurant data",
      "author": "Hyper Hive Labs",
      "path": "plugins/restaurant-analytics",
      "tags": ["analytics", "restaurant", "reporting"],
      "requirements": {
        "claude-version": ">=1.0.0",
        "dependencies": ["python>=3.9", "pandas"]
      }
    },
    {
      "name": "order-automation",
      "version": "1.5.2",
      "description": "Automated order processing system",
      "author": "Hyper Hive Labs",
      "path": "plugins/order-automation",
      "featured": true,
      "beta": false
    }
  ],
  "categories": [
    {
      "name": "Analytics",
      "description": "Data analysis and reporting tools",
      "plugins": ["restaurant-analytics", "sales-insights"]
    },
    {
      "name": "Automation",
      "description": "Workflow automation tools",
      "plugins": ["order-automation", "inventory-manager"]
    }
  ]
}

Publishing Workflow

1. Prepare Plugin

# Validate plugin structure
cd my-plugin/
claude plugin validate .

# Test locally
claude plugin install file://$(pwd)

# Version bump
npm version patch  # or minor/major

2. Create Release Branch

# GitHub flow
git checkout -b release/v1.2.0
git add .
git commit -m "Release v1.2.0"
git push origin release/v1.2.0

3. Update Marketplace

// Add to marketplace.json
{
  "name": "my-new-plugin",
  "version": "1.2.0",
  "path": "plugins/my-new-plugin",
  "description": "My awesome plugin",
  "changelog": {
    "1.2.0": "Added new features",
    "1.1.0": "Bug fixes",
    "1.0.0": "Initial release"
  }
}

4. Tag and Release

# Create signed tag
git tag -s v1.2.0 -m "Release version 1.2.0"
git push origin v1.2.0

# GitHub release
gh release create v1.2.0 \
  --title "Release v1.2.0" \
  --notes "Release notes here"

Team Marketplace Setup

Organization Structure

github.com/myorg/claude-plugins/
├── .claude-plugin/
│   └── marketplace.json
├── plugins/
│   ├── shared-utils/
│   ├── deploy-tools/
│   └── code-review/
├── docs/
│   ├── CONTRIBUTING.md
│   └── STANDARDS.md
└── .github/
    └── workflows/
        └── validate-plugins.yml

Team Configuration

// .claude/settings.json in user's machine
{
  "extraKnownMarketplaces": {
    "team-tools": {
      "source": {
        "source": "github",
        "repo": "myorg/claude-plugins"
      },
      "autoUpdate": true,
      "updateInterval": 3600
    }
  }
}

Access Control

# .github/CODEOWNERS
/plugins/deploy-tools/ @devops-team
/plugins/code-review/ @engineering-leads
/.claude-plugin/ @plugin-admins

Security Requirements

Code Signing

# Generate GPG key
gpg --gen-key

# Sign commits
git config commit.gpgsign true
git config user.signingkey YOUR_KEY_ID

# Sign tags
git tag -s v1.0.0 -m "Signed release"

Dependency Verification

{
  "dependencies": {
    "axios": {
      "version": "1.6.0",
      "integrity": "sha512-...",
      "source": "npm"
    }
  }
}

Security Manifest

// security.json
{
  "permissions": {
    "file_access": ["read", "write"],
    "network_access": {
      "allowed_domains": ["api.mycompany.com"],
      "protocols": ["https"]
    }
  },
  "audit": {
    "last_review": "2024-01-15",
    "reviewer": "security-team",
    "findings": "none"
  }
}

Version Management

Semantic Versioning

MAJOR.MINOR.PATCH

1.0.0 -> 1.0.1 (patch: bug fixes)
1.0.0 -> 1.1.0 (minor: new features, backward compatible)
1.0.0 -> 2.0.0 (major: breaking changes)

Version Constraints

{
  "requirements": {
    "claude-version": ">=1.0.0 <2.0.0",
    "dependencies": {
      "python": "~3.9.0",  // 3.9.x
      "node": "^18.0.0"    // >=18.0.0 <19.0.0
    }
  }
}

Deprecation Policy

{
  "deprecated": true,
  "deprecation_notice": "Use 'advanced-deploy' instead",
  "sunset_date": "2024-06-01",
  "migration_guide": "https://docs.example.com/migrate"
}

Distribution Strategies

Public Distribution

  1. Open Source

    • Host on GitHub/GitLab
    • Include LICENSE file
    • Accept contributions
    • Maintain changelog

  2. Discovery

    • Submit to official registry
    • Add topics/tags
    • Write good descriptions
    • Include screenshots

Private Distribution

  1. Internal Teams

    • Private Git repositories
    • VPN-only marketplaces
    • Access tokens
    • audit logs

  2. Enterprise

    • Self-hosted marketplaces
    • Air-gapped environments
    • Signed packages
    • Compliance tracking

Hybrid Approach

{
  "public_plugins": ["docs-generator", "linter"],
  "private_plugins": ["deploy-prod", "customer-data"],
  "visibility": {
    "docs-generator": "public",
    "deploy-prod": "internal-only"
  }
}

Marketplace Features

Plugin Search

{
  "search": {
    "enabled": true,
    "fields": ["name", "description", "tags"],
    "filters": ["category", "author", "version"]
  }
}

Auto-updates

{
  "auto_update": {
    "enabled": true,
    "channels": {
      "stable": "*/releases/latest",
      "beta": "*/releases/beta",
      "nightly": "*/commits/main"
    },
    "strategy": "minor-only"
  }
}

Plugin Analytics

{
  "analytics": {
    "track_installs": true,
    "track_usage": false,
    "anonymize": true,
    "retention_days": 90
  }
}

CI/CD Integration

GitHub Actions

name: Validate and Publish Plugin

on:
  push:
    tags:
      - 'v*'

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Validate Plugin Structure
        run: |
          # Validate JSON files
          jq . .claude-plugin/plugin.json
          jq . .claude-plugin/marketplace.json
          
      - name: Run Tests
        run: |
          npm test
          
      - name: Update Marketplace
        run: |
          # Update marketplace.json with new version
          jq '.plugins[0].version = "${{ github.ref_name }}"' \
            marketplace.json > tmp.json
          mv tmp.json marketplace.json
          
      - name: Commit Changes
        run: |
          git config user.name "GitHub Actions"
          git commit -am "Update marketplace for ${{ github.ref_name }}"
          git push

GitLab CI

stages:
  - validate
  - test
  - publish

validate:plugin:
  stage: validate
  script:
    - jq . .claude-plugin/plugin.json
    - jq . .claude-plugin/marketplace.json

publish:marketplace:
  stage: publish
  only:
    - tags
  script:
    - update-marketplace-version.sh
    - git push origin main

Troubleshooting

Common Issues

  1. Marketplace not found

    # Check marketplace list
claude plugin marketplace list

# Verify URL/path
curl https://marketplace.url/.claude-plugin/marketplace.json

  2. Plugin installation fails

    # Debug mode
claude --debug plugin install my-plugin

# Check permissions
ls -la ~/.claude/plugins/

  3. Version conflicts

    # Force specific version
claude plugin install my-plugin@1.2.0

# Clear cache
claude plugin cache clear

Validation Checklist

  • Valid marketplace.json structure
  • All plugin paths exist
  • Plugin versions match tags
  • Dependencies are specified
  • Security manifest included
  • Changelog updated
  • Documentation current
  • Tests passing
  • Code signed
  • Access permissions set
Reference in New Issue View Git Blame Copy Permalink