feat: add marketplace-dev skill for converting skills repos to plugin marketplaces

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>

.claude-plugin/marketplace.json

@@ -5,9 +5,8 @@
     "email": "daymadev89@gmail.com"
   },
   "metadata": {
-    "description": "Professional Claude Code skills for GitHub operations, document conversion, diagram generation, statusline customization, Teams communication, repomix utilities, skill creation, CLI demo generation, LLM icon access, Cloudflare troubleshooting, UI design system extraction, professional presentation creation, YouTube video downloading, secure repomix packaging, ASR transcription correction, video comparison quality analysis, comprehensive QA testing infrastructure, prompt optimization with EARS methodology, session history recovery, local Claude session continuation from `.claude` artifacts, documentation cleanup, format-controlled deep research report generation with evidence tracking, PDF generation with Chinese font support, CLAUDE.md progressive disclosure optimization, CCPM skill registry search and management, Promptfoo LLM evaluation framework, iOS app development with XcodeGen and SwiftUI, fact-checking with automated corrections, Twitter/X content fetching, intelligent macOS disk space recovery, skill quality review and improvement, GitHub contribution strategy, complete internationalization/localization setup, plugin/skill troubleshooting with diagnostic tools, evidence-based competitor analysis with source citations, Windows Remote Desktop (AVD/W365) connection quality diagnosis with transport protocol analysis and log parsing, Tailscale+proxy conflict diagnosis with SSH tunnel SOP for remote development, multi-path parallel product analysis with cross-model test-time compute scaling, real financial data collection for US equities with validation and yfinance pitfall handling, advanced Excel automation for formatted workbook generation and complex xlsm parsing, macOS programmatic window screenshot capture workflows, and verified Scrapling CLI installation and web extraction workflows",
+    "description": "Professional Claude Code skills for GitHub operations, document conversion, diagram generation, statusline customization, Teams communication, repomix utilities, skill creation, CLI demo generation, LLM icon access, Cloudflare troubleshooting, UI design system extraction, professional presentation creation, YouTube video downloading, secure repomix packaging, ASR transcription correction, video comparison quality analysis, comprehensive QA testing infrastructure, prompt optimization with EARS methodology, session history recovery, local Claude session continuation from `.claude` artifacts, documentation cleanup, format-controlled deep research report generation with evidence tracking, PDF generation with Chinese font support, CLAUDE.md progressive disclosure optimization, CCPM skill registry search and management, Promptfoo LLM evaluation framework, iOS app development with XcodeGen and SwiftUI, fact-checking with automated corrections, Twitter/X content fetching, intelligent macOS disk space recovery, skill quality review and improvement, GitHub contribution strategy, complete internationalization/localization setup, plugin/skill troubleshooting with diagnostic tools, evidence-based competitor analysis with source citations, Windows Remote Desktop (AVD/W365) connection quality diagnosis with transport protocol analysis and log parsing, Tailscale+proxy conflict diagnosis with SSH tunnel SOP for remote development, multi-path parallel product analysis with cross-model test-time compute scaling, real financial data collection for US equities with validation and yfinance pitfall handling, advanced Excel automation for formatted workbook generation and complex xlsm parsing, macOS programmatic window screenshot capture workflows, and verified Scrapling CLI installation and web extraction workflows, and plugin marketplace development for converting skills repos into official Claude Code marketplaces",
-    "version": "1.40.0",
+    "version": "1.40.1"
-    "homepage": "https://github.com/daymade/claude-code-skills"
   },
   "plugins": [
     {
@@ -945,6 +944,23 @@
       "skills": [
         "./asr-transcribe-to-text"
       ]
+    },
+    {
+      "name": "marketplace-dev",
+      "description": "Convert any Claude Code skills repository into an official plugin marketplace. Creates .claude-plugin/marketplace.json conforming to the Anthropic spec, validates it, tests installation, and creates a PR. Includes anti-patterns from real development experience.",
+      "source": "./",
+      "strict": false,
+      "version": "1.0.0",
+      "category": "developer-tools",
+      "keywords": [
+        "marketplace",
+        "plugin",
+        "distribution",
+        "packaging"
+      ],
+      "skills": [
+        "./marketplace-dev"
+      ]
     }
   ]
-}
+}

marketplace-dev/SKILL.md

@@ -1,13 +1,15 @@
 ---
 name: marketplace-dev
 description: |
-  Convert any Claude Code skills repository into an official plugin marketplace.
+  Converts any Claude Code skills repository into an official plugin marketplace.
-  Creates .claude-plugin/marketplace.json conforming to the Anthropic spec, validates
+  Analyzes existing skills, generates .claude-plugin/marketplace.json conforming to
-  it, tests installation, and creates a PR to the upstream repo.
+  the Anthropic spec, validates with `claude plugin validate`, tests real installation,
-  Use this skill when the user says: "make this a marketplace", "add plugin support",
+  and creates a PR to the upstream repo. Encodes hard-won anti-patterns from real
-  "convert to plugin", "one-click install", "marketplace.json", or wants their skills
+  marketplace development (schema traps, version semantics, description pitfalls).
-  repo installable via `claude plugin install`. Also trigger when the user has a
+  Use when the user mentions: marketplace, plugin support, one-click install,
-  skills repo and mentions distribution, installation, or auto-update.
+  marketplace.json, plugin distribution, auto-update, or wants a skills repo
+  installable via `claude plugin install`. Also trigger when the user has a skills
+  repo and asks about packaging, distribution, or making it installable.
 argument-hint: [repo-path]
 ---
 
@@ -120,6 +122,19 @@ Choose a name that is:
 - 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
+
+When adding a new plugin to an existing marketplace.json:
+
+1. **Bump `metadata.version`** — this is the marketplace catalog version.
+   Follow semver: new plugin = minor bump, breaking change = major bump.
+2. **Update `metadata.description`** — append the new skill's summary.
+3. **Set new plugin `version` to `"1.0.0"`** — it's new to the marketplace.
+4. **Bump existing plugin `version`** when its SKILL.md content changes.
+   Claude Code uses version to detect updates — same version = skip update.
+5. **Audit `metadata` for invalid fields** — `metadata.homepage` is a common
+   mistake (not in spec, silently ignored). Remove if found.
+
 ## Phase 3: Validate
 
 ### Step 1: CLI validation

marketplace-dev/references/anti_patterns.md

@@ -0,0 +1,100 @@
+# 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"]`.

marketplace-dev/references/marketplace_schema.md

@@ -0,0 +1,92 @@
+# marketplace.json Complete Schema Reference
+
+Source: https://code.claude.com/docs/en/plugin-marketplaces + https://code.claude.com/docs/en/plugins-reference
+Verified against Claude Code source code and `claude plugin validate`.
+
+## Root Level
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `name` | string | **Yes** | Marketplace identifier, kebab-case. Users see this: `plugin install X@<name>` |
+| `owner` | object | **Yes** | `name` (required string), `email` (optional string) |
+| `plugins` | array | **Yes** | Array of plugin entries |
+| `metadata` | object | No | See metadata fields below |
+
+### metadata fields (ONLY these 3 are valid)
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `metadata.description` | string | Brief marketplace description |
+| `metadata.version` | string | Marketplace catalog version (NOT plugin version) |
+| `metadata.pluginRoot` | string | Base directory prepended to relative plugin source paths |
+
+**Invalid metadata fields** (silently ignored or rejected):
+- `metadata.homepage` — does NOT exist in spec
+- `metadata.repository` — does NOT exist in spec
+- `$schema` — REJECTED by `claude plugin validate`
+
+## Plugin Entry Fields
+
+Each entry in the `plugins` array. Can include any field from the plugin.json
+manifest schema, plus marketplace-specific fields.
+
+### Required
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | string | Plugin identifier, kebab-case |
+| `source` | string or object | Where to fetch the plugin |
+
+### Standard metadata (from plugin.json schema)
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `description` | string | Brief plugin description |
+| `version` | string | Plugin version (independent of metadata.version) |
+| `author` | object | `name` (required), `email` (optional), `url` (optional) |
+| `homepage` | string | Plugin homepage URL |
+| `repository` | string | Source code URL |
+| `license` | string | SPDX identifier (MIT, Apache-2.0, etc.) |
+| `keywords` | array | Tags for discovery (currently unused in search) |
+
+### Marketplace-specific
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `category` | string | Freeform category for organization |
+| `tags` | array | Tags for searchability (only `community-managed` has UI effect) |
+| `strict` | boolean | Default: true. Set false when no plugin.json exists |
+
+### Component paths (from plugin.json schema)
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `commands` | string or array | Custom command file/directory paths |
+| `agents` | string or array | Custom agent file paths |
+| `skills` | string or array | Custom skill directory paths |
+| `hooks` | string or object | Hook configuration or path |
+| `mcpServers` | string or object | MCP server config or path |
+| `lspServers` | string or object | LSP server config or path |
+| `outputStyles` | string or array | Output style paths |
+| `userConfig` | object | User-configurable values prompted at enable time |
+| `channels` | array | Channel declarations for message injection |
+
+## Source Types
+
+| Source | Format | Example |
+|--------|--------|---------|
+| Relative path | string `"./"` | `"source": "./"` |
+| GitHub | object | `{"source": "github", "repo": "owner/repo"}` |
+| Git URL | object | `{"source": "url", "url": "https://..."}` |
+| Git subdirectory | object | `{"source": "git-subdir", "url": "...", "path": "..."}` |
+| npm | object | `{"source": "npm", "package": "@scope/pkg"}` |
+
+All object sources support optional `ref` (branch/tag) and `sha` (40-char commit).
+
+## Reserved Marketplace Names
+
+Cannot be used: `claude-code-marketplace`, `claude-code-plugins`,
+`claude-plugins-official`, `anthropic-marketplace`, `anthropic-plugins`,
+`agent-skills`, `knowledge-work-plugins`, `life-sciences`.
+
+Names impersonating official marketplaces are also blocked.