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