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