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": "email@example.com",
    "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