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": "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:

Read Plugin Structure
- Scan plugin directory for components
- Extract metadata from frontmatter
- Build component lists
Execute Python Script
- Call marketplace_update.py with appropriate arguments
- Pass plugin details
- Handle success/error responses
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

Always Validate After Changes
- Run validate after add/update/remove
- Fix any warnings or errors
- Ensure all referenced files exist
Scan Plugin Directory
- Don't manually list components
- Scan directory to detect agents/commands/skills
- Extract metadata from frontmatter
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)
Consistent Metadata
- Keep descriptions concise (< 100 chars)
- Use relevant keywords
- Maintain consistent author information
- Use appropriate categories
Backup Before Changes
- Create backup of marketplace.json
- Test changes in development first
- Validate before committing

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

marketplace-update

Install Skill

SKILL.md