claude-code-skills-reference/marketplace-dev/references/anti_patterns.md

Anti-Patterns: Marketplace Development Pitfalls

Every item below was encountered during real marketplace development. Not theoretical — each cost debugging time.

Schema Errors

Adding $schema field

• Symptom: claude plugin validate fails with Unrecognized key: "$schema"
• Fix: Do not include $schema. Unlike many JSON schemas, Claude Code rejects it.
• Why it's tempting: Other marketplace examples (like daymade/claude-code-skills) include it, and it works for JSON Schema-aware editors. But the validator is strict.

Using metadata.homepage

• Symptom: Silently ignored — no error, no effect.
• Fix: metadata only supports description, version, pluginRoot. Put homepage on individual plugin entries if needed.
• Why it's tricky: homepage IS valid on plugin entries (from plugin.json schema), so it looks correct but is wrong at the metadata level.

Conflicting strict: false with plugin.json

• Symptom: Plugin fails to load with "conflicting manifests" error.
• Fix: Choose one authority. strict: false means marketplace.json is the SOLE definition. Remove plugin.json or set strict: true and let plugin.json define components.

Version Confusion

Using marketplace version as plugin version

• Symptom: All plugins show the same version (e.g., "2.3.0") even though each was introduced at different times.
• Fix: metadata.version = marketplace catalog version (matches repo VERSION file). Each plugin entry version is independent. First time in marketplace = "1.0.0".

Not bumping version after changes

• Symptom: Users don't receive updates after you push changes.
• Fix: Claude Code uses version to detect updates. Same version = skip. Bump the plugin version in marketplace.json when you change skill content.

Description Errors

Rewriting or translating SKILL.md descriptions

• Symptom: Descriptions don't match the actual skill behavior. English descriptions for a Chinese-audience repo feel foreign.
• Fix: Copy the EXACT description field from each SKILL.md frontmatter. The author wrote it for their audience — preserve it.

Inventing features in descriptions

• Symptom: Description promises "8,000+ consultations" or "auto-backup and rollback" when the SKILL.md doesn't mention these specifics.
• Fix: Only state what the SKILL.md frontmatter says. If you want to add context, use the marketplace-level metadata.description, not individual plugin descriptions.

Installation Testing

Not testing after GitHub push

• Symptom: Local validation passes, but claude plugin marketplace add <user>/<repo> fails because it clones the default branch which doesn't have the marketplace.json.
• Fix: Push marketplace.json to the repo's default branch before testing GitHub install. Feature branches only work if the user specifies the ref.

Forgetting to clean up test installations

• Symptom: Next test run finds stale marketplace/plugins and produces confusing results.
• Fix: Always uninstall plugins and remove marketplace after testing:

  claude plugin uninstall <plugin>@<marketplace> 2>/dev/null
  claude plugin marketplace remove <marketplace> 2>/dev/null
  

PR Best Practices

Modifying existing files unnecessarily

• Symptom: PR diff includes unrelated changes (empty lines in .gitignore, whitespace changes in README), making it harder to review and merge.
• Fix: Only add new files. If modifying README, be surgical — only add the install section. Verify with git diff upstream/main that no unrelated files are touched.

Not squashing commits

• Symptom: Git history has 15+ commits with iterative demo.gif changes, bloating the repo by megabytes. Users cloning the marketplace download all this history.
• Fix: Squash all commits into one before creating the PR:

  git reset --soft upstream/main
  git commit -m "feat: add Claude Code plugin marketplace"
  

Discovery Misconceptions

Over-investing in keywords/tags

• Symptom: Spending time crafting perfect keyword lists.
• Reality: In the current Claude Code source (verified by reading DiscoverPlugins.tsx), the Discover tab searches ONLY name + description + marketplaceName. keywords is defined in the schema but never consumed. tags only affects UI for the specific value "community-managed". Include keywords for future-proofing but don't obsess over them.

Using tags for search optimization

• Symptom: Adding tags: ["business", "diagnosis"] expecting search improvements.
• Reality: Only tags: ["community-managed"] has any effect (shows a UI label). The official Anthropic marketplace (123 plugins) uses tags on only 3 plugins, all with the value ["community-managed"].