marketplace-update

name	marketplace-update
description	Updates the .claude-plugin/marketplace.json file when plugins are added, modified, or removed. Use when creating or updating plugin entries in the marketplace catalog.

Marketplace Update Skill

This skill provides functionality to update the .claude-plugin/marketplace.json file when plugins are added, modified, or removed from the marketplace.

Purpose

Maintain the marketplace catalog by:

• Adding new plugin entries
• Updating existing plugin metadata
• Removing obsolete plugins
• Validating marketplace structure
• Ensuring consistency across the catalog

When to Use

Use this skill when:

• A new plugin is created and needs to be registered
• An existing plugin's components change (agents, commands, skills added/removed)
• Plugin metadata needs updating (version, description, keywords, etc.)
• A plugin is being removed from the marketplace
• Validating marketplace.json structure

Marketplace Structure

The marketplace.json file follows this schema:

{
  "name": "marketplace-name",
  "owner": {
    "name": "Owner Name",
    "email": "[e-mail]",
    "url": "https://github.com/username"
  },
  "metadata": {
    "description": "Marketplace description",
    "version": "1.0.0"
  },
  "plugins": [
    {
      "name": "plugin-name",
      "source": "./plugins/plugin-name",
      "description": "Plugin description",
      "version": "1.0.0",
      "author": {
        "name": "Author Name",
        "url": "https://github.com/username"
      },
      "homepage": "https://github.com/username/repo",
      "repository": "https://github.com/username/repo",
      "license": "MIT",
      "keywords": ["keyword1", "keyword2"],
      "category": "category-name",
      "strict": false,
      "commands": ["./commands/command-name.md"],
      "agents": ["./agents/agent-name.md"],
      "skills": ["./skills/skill-name"]
    }
  ]
}

Operations

Add Plugin

Add a new plugin entry to the marketplace:

# Use the provided Python script
python marketplace_update.py add \
  --name "plugin-name" \
  --description "Plugin description" \
  --version "1.0.0" \
  --category "category-name" \
  --agents "agent1.md,agent2.md" \
  --commands "command1.md,command2.md" \
  --skills "skill1,skill2"

Required Fields:

• name - Plugin name (hyphen-case)
• description - Brief plugin description
• version - Semantic version (e.g., "1.0.0")

Optional Fields:

• category - Plugin category (default: "general")
• agents - Comma-separated list of agent files
• commands - Comma-separated list of command files
• skills - Comma-separated list of skill directories
• keywords - Comma-separated list of keywords
• license - License type (default: "MIT")
• strict - Strict mode flag (default: false)

Update Plugin

Update an existing plugin entry:

python marketplace_update.py update \
  --name "plugin-name" \
  --description "Updated description" \
  --version "1.1.0" \
  --add-agent "new-agent.md" \
  --remove-command "old-command.md"

Update Operations:

• --description - Update description
• --version - Update version
• --category - Update category
• --keywords - Update keywords (replaces all)
• --add-agent - Add agent file
• --remove-agent - Remove agent file
• --add-command - Add command file
• --remove-command - Remove command file
• --add-skill - Add skill directory
• --remove-skill - Remove skill directory

Remove Plugin

Remove a plugin from the marketplace:

python marketplace_update.py remove --name "plugin-name"

Validate Marketplace

Validate the marketplace.json structure:

python marketplace_update.py validate

This checks:

• JSON syntax validity
• Required fields presence
• File path existence
• Component reference validity
• Duplicate plugin names

Python Script

The skill includes a Python script at marketplace_update.py that provides command-line interface for all operations.

Usage from Claude Code

When invoked as a skill:

1. Read Plugin Structure

   • Scan plugin directory for components
   • Extract metadata from frontmatter
   • Build component lists

2. Execute Python Script

   • Call marketplace_update.py with appropriate arguments
   • Pass plugin details
   • Handle success/error responses

3. Validate Result

   • Verify marketplace.json is valid
   • Confirm plugin entry is correct
   • Report success or errors

Examples

Example 1: Add New Plugin

# Plugin: golang-development
# Components: 3 agents, 1 command, 4 skills

python marketplace_update.py add \
  --name "golang-development" \
  --description "Go language development tools" \
  --version "1.0.0" \
  --category "languages" \
  --keywords "golang,go,development" \
  --agents "golang-pro.md,gin-pro.md,charm-pro.md" \
  --commands "golang-scaffold.md" \
  --skills "async-golang-patterns,golang-testing-patterns,golang-packaging,golang-performance-optimization"

Example 2: Update Plugin Version

# Update version and add new agent

python marketplace_update.py update \
  --name "golang-development" \
  --version "1.1.0" \
  --add-agent "gorm-pro.md"

Example 3: Remove Plugin

python marketplace_update.py remove --name "obsolete-plugin"

Integration with Commands

The /claude-plugin:create and /claude-plugin:update commands should invoke this skill automatically:

From /claude-plugin:create Command

After creating a new plugin:

1. Scan plugin directory for components
2. Extract metadata from agent/command frontmatter
3. Invoke marketplace-update skill:
   - Operation: add
   - Plugin name: [from user input]
   - Components: [scanned from directory]
   - Metadata: [extracted from frontmatter]

From /claude-plugin:update Command

After updating a plugin:

1. Determine what changed (added/removed/modified)
2. Invoke marketplace-update skill:
   - Operation: update
   - Plugin name: [from user input]
   - Changes: [specific updates]

Error Handling

Plugin Already Exists (Add)

Error: Plugin 'plugin-name' already exists in marketplace.
Suggestion: Use 'update' operation instead.

Plugin Not Found (Update/Remove)

Error: Plugin 'plugin-name' not found in marketplace.
Suggestion: Use 'add' operation to create it.

Invalid JSON

Error: marketplace.json contains invalid JSON.
Suggestion: Fix JSON syntax before proceeding.

Component File Missing

Warning: Component file './agents/agent-name.md' not found.
Suggestion: Create the file or remove from plugin entry.

Validation Failure

Error: Marketplace validation failed:
  - Plugin 'plugin-a' missing required field 'description'
  - Plugin 'plugin-b' references non-existent agent 'missing.md'
Suggestion: Fix errors and validate again.

Best Practices

1. Always Validate After Changes

   • Run validate after add/update/remove
   • Fix any warnings or errors
   • Ensure all referenced files exist

2. Scan Plugin Directory

   • Don't manually list components
   • Scan directory to detect agents/commands/skills
   • Extract metadata from frontmatter

3. Semantic Versioning

   • Patch: Bug fixes, documentation updates (1.0.0 → 1.0.1)
   • Minor: New components, enhancements (1.0.0 → 1.1.0)
   • Major: Breaking changes, removals (1.0.0 → 2.0.0)

4. Consistent Metadata

   • Keep descriptions concise (< 100 chars)
   • Use relevant keywords
   • Maintain consistent author information
   • Use appropriate categories

5. Backup Before Changes

   • Create backup of marketplace.json
   • Test changes in development first
   • Validate before committing

Categories

Common plugin categories:

• languages - Language-specific tools (Python, Go, Rust, etc.)
• development - General development tools
• security - Security scanning and analysis
• testing - Test generation and automation
• operations - DevOps and operations tools
• infrastructure - Cloud and infrastructure tools
• documentation - Documentation generation
• architecture - Architecture and design tools
• workflow - Workflow orchestration
• general - General purpose tools

File Structure

plugins/claude-plugin/skills/marketplace-update/
├── SKILL.md                    # This file
├── marketplace_update.py       # Python implementation
└── references/                 # Optional examples
    └── examples.md

Requirements

• Python 3.8+
• No external dependencies (uses standard library only)
• Access to .claude-plugin/marketplace.json
• Read/write permissions on marketplace file

Success Criteria

After running this skill:

• ✓ marketplace.json is valid JSON
• ✓ Plugin entry is correct and complete
• ✓ All referenced files exist
• ✓ No duplicate plugin names
• ✓ Required fields are present
• ✓ Validation passes without errors