Claude Marketplace Setup

Claude Plugin Marketplace Setup

Creates and manages plugin marketplaces for Claude Code, making plugins discoverable and installable across teams and projects.

Quick Start

What is a Marketplace?

A marketplace is a catalog of Claude Code plugins defined in a .claude-plugin/marketplace.json file. It enables:

• Plugin discovery
• One-command installation
• Version management
• Team distribution

Basic Marketplace Structure

{
  "name": "my-marketplace",
  "owner": {
    "name": "Team Name",
    "email": "team@example.com"
  },
  "plugins": [
    {
      "name": "plugin-name",
      "source": "./plugins/plugin-name",
      "description": "Plugin description",
      "version": "1.0.0"
    }
  ]
}

Creating Your First Marketplace

Step 1: Create marketplace directory

mkdir -p .claude-plugin

Step 2: Create marketplace.json

cat > .claude-plugin/marketplace.json << 'EOF'
{
  "name": "team-tools",
  "owner": {
    "name": "Development Team",
    "email": "dev@company.com"
  },
  "plugins": []
}
EOF

Step 3: Add plugins Add plugin entries to the plugins array (see Plugin Entry Schema below)

Step 4: Test locally

/plugin marketplace add .
/plugin

Marketplace Schema

Required Fields

Optional Metadata

Complete Example

{
  "name": "company-tools",
  "owner": {
    "name": "Engineering Team",
    "email": "eng@company.com"
  },
  "metadata": {
    "description": "Internal development tools and workflows",
    "version": "2.0.0",
    "pluginRoot": "./plugins"
  },
  "plugins": [
    {
      "name": "code-formatter",
      "source": "./code-formatter",
      "description": "Automatic code formatting on save",
      "version": "2.1.0",
      "author": {
        "name": "Tools Team"
      },
      "keywords": ["formatting", "code-quality"]
    }
  ]
}

Plugin Entry Schema

Minimal Plugin Entry

{
  "name": "plugin-name",
  "source": "./path/to/plugin"
}

Complete Plugin Entry

{
  "name": "enterprise-tools",
  "source": {
    "source": "github",
    "repo": "company/enterprise-plugin"
  },
  "description": "Enterprise workflow automation tools",
  "version": "2.1.0",
  "author": {
    "name": "Enterprise Team",
    "email": "enterprise@company.com"
  },
  "homepage": "https://docs.company.com/plugins",
  "repository": "https://github.com/company/enterprise-plugin",
  "license": "MIT",
  "keywords": ["enterprise", "workflow", "automation"],
  "category": "productivity",
  "strict": false
}

Plugin Entry Fields

Required:

• name: Plugin identifier (kebab-case)
• source: Where to fetch plugin from

Optional Standard Fields:

• description: Brief plugin description
• version: Plugin version
• author: Author information
• homepage: Documentation URL
• repository: Source code URL
• license: SPDX identifier (e.g., MIT)
• keywords: Tags for discovery
• category: Plugin category
• tags: Searchability tags
• strict: Require plugin.json (default: true)

Optional Component Configuration:

• commands: Custom paths to command files
• agents: Custom paths to agent files
• hooks: Custom hooks configuration
• mcpServers: MCP server configurations

Plugin Source Types

1. Relative Path

For plugins in the same repository:

{
  "name": "my-plugin",
  "source": "./plugins/my-plugin"
}

With pluginRoot:

{
  "metadata": {
    "pluginRoot": "./plugins"
  },
  "plugins": [
    {
      "name": "my-plugin",
      "source": "./my-plugin"
    }
  ]
}

2. GitHub Repository

For plugins in GitHub repos:

{
  "name": "github-plugin",
  "source": {
    "source": "github",
    "repo": "owner/plugin-repo"
  }
}

With specific branch:

{
  "source": {
    "source": "github",
    "repo": "owner/plugin-repo",
    "ref": "develop"
  }
}

3. Git Repository

For plugins in other Git hosting:

{
  "name": "git-plugin",
  "source": {
    "source": "url",
    "url": "https://gitlab.com/team/plugin.git"
  }
}

With specific branch:

{
  "source": {
    "source": "url",
    "url": "https://gitlab.com/team/plugin.git",
    "ref": "main"
  }
}

Marketplace Types

1. Team/Organization Marketplace

For internal team tools:

{
  "name": "company-internal",
  "owner": {
    "name": "Engineering",
    "email": "eng@company.com"
  },
  "metadata": {
    "description": "Internal development tools"
  },
  "plugins": [
    {
      "name": "deploy-tools",
      "source": "./plugins/deploy-tools",
      "description": "Deployment automation"
    },
    {
      "name": "compliance-check",
      "source": "./plugins/compliance-check",
      "description": "Security and compliance validation"
    }
  ]
}

Hosting: Private GitHub repo or internal Git server

2. Project-Specific Marketplace

For project-specific plugins:

{
  "name": "project-tools",
  "owner": {
    "name": "Project Team",
    "email": "project@company.com"
  },
  "plugins": [
    {
      "name": "project-workflow",
      "source": "./plugins/workflow",
      "description": "Project-specific workflow automation"
    }
  ]
}

Hosting: In project repository at .claude-plugin/marketplace.json

3. Public Marketplace

For public/open-source plugins:

{
  "name": "awesome-claude-plugins",
  "owner": {
    "name": "Community",
    "email": "community@example.com"
  },
  "metadata": {
    "description": "Curated collection of Claude Code plugins",
    "homepage": "https://github.com/awesome-claude-plugins"
  },
  "plugins": [
    {
      "name": "markdown-tools",
      "source": {
        "source": "github",
        "repo": "user/markdown-tools"
      },
      "description": "Markdown editing and preview tools",
      "license": "MIT"
    }
  ]
}

Hosting: Public GitHub repository

Team Configuration

Automatic Marketplace Installation

Configure team marketplaces in .claude/settings.json:

{
  "extraKnownMarketplaces": {
    "team-tools": {
      "source": {
        "source": "github",
        "repo": "company/claude-plugins"
      }
    },
    "project-specific": {
      "source": {
        "source": "git",
        "url": "https://git.company.com/project-plugins.git"
      }
    }
  }
}

When team members trust the folder, Claude Code automatically installs these marketplaces.

Multi-Environment Setup

Different marketplaces for different environments:

{
  "extraKnownMarketplaces": {
    "production-tools": {
      "source": {
        "source": "github",
        "repo": "company/prod-plugins"
      }
    },
    "development-tools": {
      "source": {
        "source": "github",
        "repo": "company/dev-plugins"
      }
    }
  }
}

Marketplace Management

Adding a Marketplace

# GitHub repository
/plugin marketplace add owner/repo

# Git repository
/plugin marketplace add https://gitlab.com/company/plugins.git

# Local directory
/plugin marketplace add ./path/to/marketplace

# Direct URL
/plugin marketplace add https://url.of/marketplace.json

Listing Marketplaces

/plugin marketplace list

Updating a Marketplace

/plugin marketplace update marketplace-name

Removing a Marketplace

/plugin marketplace remove marketplace-name

Note: Removing a marketplace also uninstalls all plugins from that marketplace.

Workflow

Creating a New Marketplace

1. Initialize structure

   mkdir -p .claude-plugin
   

2. Create marketplace.json

   • Define name, owner, metadata
   • Start with empty plugins array

3. Add plugins

   • Add plugin entries with sources
   • Include descriptions and versions

4. Test locally

   /plugin marketplace add .
   /plugin
   

5. Commit to version control

   git add .claude-plugin/marketplace.json
   git commit -m "feat: add plugin marketplace"
   

Adding a Plugin to Marketplace

1. Create plugin entry

   {
     "name": "new-plugin",
     "source": "./plugins/new-plugin",
     "description": "Plugin description",
     "version": "1.0.0"
   }
   

2. Add to plugins array Edit marketplace.json and add entry

3. Validate JSON

   jq empty .claude-plugin/marketplace.json
   

4. Update marketplace

   /plugin marketplace update marketplace-name
   

5. Install plugin

   /plugin install new-plugin@marketplace-name
   

Hosting Strategies

GitHub (Recommended)

Advantages:

• Version control
• Issue tracking
• Collaboration tools
• Free for public/private repos
• Easy sharing

Setup:

1. Create repository
2. Add .claude-plugin/marketplace.json
3. Commit and push
4. Share: /plugin marketplace add owner/repo

GitLab/Bitbucket

Works with any Git hosting:

/plugin marketplace add https://gitlab.com/company/plugins.git

Advantages:

• Self-hosted options
• Enterprise integration
• Custom workflows

Local Development

For testing and development:

/plugin marketplace add ./my-local-marketplace
/plugin install test-plugin@my-local-marketplace

Advantages:

• Fast iteration
• No network required
• Easy testing

Validation

Validate Marketplace Structure

# Validate JSON syntax
jq empty .claude-plugin/marketplace.json

# Validate required fields
jq -e '.name, .owner, .plugins' .claude-plugin/marketplace.json

# Check plugin entries
jq -e '.plugins[] | .name, .source' .claude-plugin/marketplace.json

Validate Plugin Sources

# Check relative paths exist
for plugin in $(jq -r '.plugins[] | select(.source | type == "string") | .source' .claude-plugin/marketplace.json); do
  if [[ ! -d "$plugin" ]]; then
    echo "Missing: $plugin"
  fi
done

# Validate GitHub repos (requires gh CLI)
for repo in $(jq -r '.plugins[] | select(.source.source == "github") | .source.repo' .claude-plugin/marketplace.json); do
  gh repo view "$repo" > /dev/null || echo "Invalid repo: $repo"
done

Best Practices

Organization

• Group related plugins together
• Use categories for better discovery
• Maintain consistent naming
• Document plugin purposes clearly

Versioning

• Use semantic versioning for marketplace
• Track plugin versions
• Maintain CHANGELOG.md
• Tag releases in Git

Documentation

• Include README.md in marketplace repo
• Document installation process
• Provide usage examples
• Link to plugin documentation

Security

• Review plugins before adding
• Verify plugin sources
• Document security requirements
• Use private repos for sensitive tools

Maintenance

• Keep plugin versions updated
• Remove deprecated plugins
• Test plugins after updates
• Monitor user feedback

Troubleshooting

Marketplace not loading:

• Verify URL is accessible
• Check .claude-plugin/marketplace.json exists
• Validate JSON syntax
• Confirm access permissions for private repos

Plugin installation failures:

• Verify plugin source URLs are accessible
• Check plugin directories contain required files
• Test sources manually (clone/download)
• Review error messages in logs

Team configuration not working:

• Verify .claude/settings.json syntax
• Check marketplace sources are accessible
• Ensure team members trusted the folder
• Restart Claude Code after config changes

Next Steps

• See REFERENCE.md for complete schema documentation
• See EXAMPLES.md for real-world marketplace examples
• Use scripts in scripts/ for marketplace validation and management