2097ffb527
Encodes proven methodology from real marketplace development: - 4-phase workflow: Analyze → Create → Validate → PR - 8 schema hard-rules (verified against Claude Code source) - 13 anti-patterns from production debugging - Complete marketplace.json schema reference - Marketplace maintenance rules (version bumping, description updates) Also fixes: remove invalid metadata.homepage from our own marketplace.json Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
101 lines
4.8 KiB
Markdown
101 lines
4.8 KiB
Markdown
# 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:
|
|
```bash
|
|
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:
|
|
```bash
|
|
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"]`.
|