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

Field	Type	Description
name	string	Marketplace identifier (kebab-case)
owner	object	Maintainer information
owner.name	string	Maintainer name
owner.email	string	Contact email
plugins	array	List of available plugins

Optional Metadata

Field	Type	Description
metadata.description	string	Brief marketplace description
metadata.version	string	Marketplace version
metadata.pluginRoot	string	Base path for relative sources

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