Marketplace Dev

marketplace-dev

Convert a Claude Code skills repository into an official plugin marketplace so users can install skills via claude plugin marketplace add and get auto-updates.

Input: a repo with skills/ directories containing SKILL.md files. Output: .claude-plugin/marketplace.json + validated + installation-tested + PR-ready.

Route the task before editing

Phase 0: Evidence Intake

Before editing an existing marketplace, collect evidence instead of relying on the default template:

1. Read the current .claude-plugin/marketplace.json.
2. Read this repo's marketplace rules (CLAUDE.md, README install section, changelog).
3. Read official docs for marketplace/plugin path semantics.
4. Use the current conversation as evidence. Mine earlier local Claude Code sessions only when the user explicitly asks for or approves that private source.

When that history source is approved, each project's sessions live under ~/.claude/projects/<escaped-cwd>/:

• Top-level files: <session-id>.jsonl
• Subagent transcripts: <session-id>/subagents/agent-*.jsonl

Useful search patterns (adjust keywords to the failure you are debugging):

grep -lc "marketplace.json\|claude plugin validate\|claude plugin install" \
  ~/.claude/projects/<escaped-cwd>/*.jsonl
grep -lc "Unrecognized key\|Plugin not found\|No manifest found\|Duplicate plugin" \
  ~/.claude/projects/<escaped-cwd>/*.jsonl \
  ~/.claude/projects/<escaped-cwd>/*/subagents/*.jsonl

Extract lessons as evidence-backed rules: command attempted, observed output, root cause, final working command/config. Do not encode guesses from memory.

Phase 1: Analyze the Target Repo

Step 1: Discover all skills

# Find every SKILL.md
find <repo-path>/skills -name "SKILL.md" -type f 2>/dev/null

For each skill, extract from SKILL.md frontmatter:

• name — the skill identifier
• description — the ORIGINAL text, do NOT rewrite or translate

Step 2: Read the repo metadata

• VERSION file (if exists) — this becomes metadata.version
• README.md — understand the project, author info, categories
• LICENSE — note the license type
• Git remotes — identify upstream vs fork (git remote -v)

Step 3: Determine categories

Group skills by function. Categories are freeform strings. Good patterns:

• business-diagnostics, content-creation, thinking-tools, utilities
• developer-tools, productivity, documentation, security

Ask the user to confirm categories if grouping is ambiguous.

Step 4: Choose plugin boundaries

Claude Code has three separate levels:

marketplace -> plugin -> skill

• Marketplace name is used for install identity: plugin@marketplace.
• Plugin name is the slash namespace: /plugin-name:skill-name.
• Skill name comes from SKILL.md frontmatter when the skill path points to a directory containing SKILL.md directly.

Choose each plugin boundary by installation/update/cache intent:

• Single-skill plugin: use when the skill should install, update, and roll back independently with a narrow cache.
• Suite plugin: use when related skills should share one namespace and one install command, for example /daymade-docs:mermaid-tools.

For detailed source/cache patterns and pitfalls, read references/cache_and_source_patterns.md before changing source or skills.

Phase 2: Create marketplace.json

The official schema (memorize this)

Read references/marketplace_schema.md for the complete field reference. Key rules that are NOT obvious from the docs:

1. `$schema` field is REJECTED by claude plugin validate. Do not include it.
2. `metadata` only has 3 valid fields: description, version, pluginRoot. Nothing else. metadata.homepage does NOT exist — the validator accepts it silently but it's not in the spec.
3. `metadata.version` is the marketplace catalog version, NOT individual plugin versions. It should match the repo's VERSION file (e.g., "2.3.0").
4. Plugin entry `version` is independent. For first-time marketplace registration, use "1.0.0".
5. `strict: false` is required when there's no plugin.json in the repo. With strict: false, the marketplace entry IS the entire plugin definition. Having BOTH strict: false AND a plugin.json with components causes a load failure.
6. `source` defines the installed plugin root. For single-skill plugins, point source directly at the skill directory (e.g., "./tunnel-doctor") and omit skills entirely — this is the official pattern used by 167/168 plugins in anthropics/claude-plugins-official. For suite plugins, use source: "./<suite>" with explicit skills array listing subdirectories. Avoid source: "./" (installs full repo as cache) and skills: ["./"] (rejected by Claude Code 2.1.x path-escape validator).
7. Reserved marketplace names that CANNOT be used: claude-code-marketplace, claude-code-plugins, claude-plugins-official, anthropic-marketplace, anthropic-plugins, agent-skills, knowledge-work-plugins, life-sciences.
8. `tags` vs `keywords`: Both are optional. In the current Claude Code source, keywords is defined but never consumed in search. tags only has a UI effect for the value "community-managed" (shows a label). Neither affects discovery. The Discover tab searches only name + description + marketplaceName. Include keywords for future-proofing but don't over-invest.

Generate the marketplace.json

Use this template, filling in from the analysis:

{
  "name": "<marketplace-name>",
  "owner": {
    "name": "<github-org-or-username>"
  },
  "metadata": {
    "description": "<one-line description of the marketplace>",
    "version": "<from-VERSION-file-or-1.0.0>"
  },
  "plugins": [
    {
      "name": "<skill-name>",
      "description": "<EXACT text from SKILL.md frontmatter, do NOT rewrite>",
      "source": "./<skill-name>",
      "strict": false,
      "version": "1.0.0",
      "category": "<category>",
      "keywords": ["<relevant>", "<keywords>"]
    }
  ]
}

Naming the marketplace

The name field is what users type after @ in install commands: claude plugin install dbs@<marketplace-name>

Choose a name that is:

• Short and memorable
• kebab-case (lowercase, hyphens only)
• Related to the project identity, not generic

Description rules

• Use the ORIGINAL description from each SKILL.md frontmatter
• Do NOT translate, embellish, or "improve" descriptions
• If the repo's audience is Chinese, keep descriptions in Chinese
• If bilingual, use the first language in the SKILL.md description field
• The metadata.description at marketplace level can be a new summary

Maintaining an existing marketplace

Use this section for ordinary entry additions or metadata updates. For a suite consolidation, source relocation, suite membership transfer, or standalone-to-suite