Reviewing Plugin Marketplace Configurations

Comprehensive review of Claude Code plugin marketplace and plugin configurations against official best practices and common pitfalls.

Quick Start

Automated Review (Recommended)

Run the verification script:

bash scripts/verify-marketplace.sh [marketplace-directory]

This automatically checks:

• •marketplace.json structure
• •Skills paths validation
• •Git remote URL
• •README.md repository references
• •plugin.json presence (warns if exists)

Manual Review

1. •Ask user for marketplace directory (e.g., .claude-plugin/)
2. •Read marketplace.json and plugin.json (if exists)
3. •Check against official format and common errors
4. •Provide detailed feedback with priorities

Example review output:

## Critical Issues
- ❌ Repository URL mismatch: README.md uses "owner-a/repo" but marketplace.json uses "owner-b/repo"
- ❌ Source path "./.claude-plugin" does not exist

## Important Issues
- ⚠ plugin.json exists but Anthropic's official format uses marketplace.json only
- ⚠ Skills path "./skills/missing-skill" not found

## Compliance Score
- Structure: ✓ Valid JSON
- Required fields: ✓ Present
- Path validation: ✗ 2 invalid paths

Review Process

Step 1: Read Configuration Files

Read and analyze:

• •.claude-plugin/marketplace.json (required for marketplaces)
• •.claude-plugin/plugin.json (optional, check if present)
• •README.md (for repository URL consistency)
• •Git remote URL (if in git repository)

Step 2: Validate marketplace.json Structure

Required fields:

• • name - Marketplace identifier
• • owner.name - Owner name
• • plugins - Array of plugin definitions

Each plugin must have:

• • name - Plugin identifier
• • source - Source path (must start with ./, e.g., "./plugins/plugin-name")
• • description - What the plugin does

Recommended fields:

• • metadata.description - Marketplace description
• • metadata.version - Version number

Note: skills field specifies skills directory path (root-relative, e.g., "./plugins/plugin-name/skills/")

Optional fields (context-dependent):

• • strict: false - Only needed if plugins lack plugin.json files (see references/common-errors.md)

Step 3: Check Common Errors

Repository URL consistency:

• •Compare URLs in marketplace.json, plugin.json, README.md, git remote
• •All should point to the same repository
• •Common issue: Using organization name instead of personal username

Source path validation:

• •Verify source path exists
• •Must start with ./ (e.g., "./plugins/plugin-name")
• •Check that source directory contains skills/ subdirectory with SKILL.md files

Skills path validation:

• •Verify skills path exists (root-relative, e.g., "./plugins/plugin-name/skills/")
• •Directory should contain subdirectories with SKILL.md files

plugin.json conflicts:

• •Anthropic's official format uses marketplace.json only
• •Having both may cause confusion
• •If both exist, ensure names match

README.md consistency checks:

• •Skills documentation: Verify all skills in marketplace.json are documented in README.md
  • •Check "Skills Included" section lists each skill from the skills array
  • •Each skill should have description and "Use when" guidance
• •Project Structure accuracy:
  • •If plugin.json mentioned in README but doesn't exist, suggest using marketplace.json
  • •Verify structure diagram matches actual files in .claude-plugin/
• •Permissions section completeness:
  • •Check if README.md settings.json examples include all skills from marketplace.json
  • •Example: "Skill(skill-name)" for each skill should be in permissions array
• •Repository references: Ensure consistent GitHub URLs across README installation examples

Step 4: Compare with Anthropic Format

See references/anthropic-format.md for official structure.

Key patterns from Anthropic:

• •marketplace.json at .claude-plugin/marketplace.json
• •No plugin.json (marketplace.json only)
• •source: "./plugins/plugin-name" pointing to plugin directory (must start with ./)
• •strict: false (optional - only needed when plugin.json is missing)
• •skills field specifies skills directory (root-relative path)

Step 5: Generate Feedback

Organize findings by priority:

Critical Issues (breaks functionality):

• •enabledPlugins format error (array instead of object)
• •Repository URL mismatch with git remote
• •Invalid source path (doesn't exist)
• •Missing required fields
• •Invalid JSON syntax

Important Issues (causes confusion):

• •Repository URL inconsistency across files
• •Invalid skills paths
• •Conflicting plugin.json and marketplace.json
• •Missing recommended fields

Suggestions (best practices):

• •Add metadata section (improves discoverability)
• •Add strict: false only if plugins lack plugin.json (otherwise no effect)
• •Follow Anthropic's single-file pattern
• •Explicit skills array

Common Issues Reference

See references/common-errors.md for detailed error patterns and solutions.

Top 3 issues from real experience (by actual impact):

1. •

   enabledPlugins format error ⚠️ BREAKS FUNCTIONALITY

   • •Error: Plugins don't load, no activation
   • •Cause: Using array ["plugin@marketplace"] instead of object {"plugin@marketplace": true}
   • •Fix: Change to object format in settings.json
   • •This is the #1 cause of "plugin not working" issues
2. •

   Repository URL mismatch

   • •Error: Plugin 'name' not found in marketplace
   • •Cause: README/settings use different owner than actual git remote
   • •Fix: Ensure all URLs match git remote -v
3. •

   Wrong source path

   • •Error: Plugin 'name' not found
   • •Cause: Source points to non-existent directory
   • •Fix: Use "./" for root, verify path exists

Output Format

Structure review with these sections:

• •Summary: Overall assessment
• •Critical Issues: Must fix (with file:line references)
• •Important Issues: Should fix (with explanations)
• •Suggestions: Best practices alignment
• •Compliance Score: Quick visual assessment

Tips for Effective Reviews

Be Specific: Don't say "URL is wrong" - say "marketplace.json line 7 uses 'owner-a/repo' but git remote shows 'owner-b/repo'"

Verify Paths: Actually check if files/directories exist, don't just validate format

Check Consistency: Cross-reference all files that mention repository URLs

Use Official Examples: Compare against Anthropic's format at https://github.com/anthropics/skills

References

Anthropic Format: See references/anthropic-format.md for official marketplace.json structure

Common Errors: See references/common-errors.md for detailed error patterns and solutions