feat: add marketplace-structure skill for plugin marketplace creation (#89)

## Summary

Add comprehensive marketplace development support to plugin-dev,
addressing the gap where users asking to create or manage plugin
marketplaces had no dedicated guidance. This repository itself is a
marketplace, serving as a reference implementation.

- New `marketplace-structure` skill with complete schema reference,
distribution patterns, and 3 example templates
- New `/plugin-dev:create-marketplace` command with 8-phase guided
workflow
- Extended `plugin-validator` agent to validate marketplace.json
structure
- Enhanced `/plugin-dev:create-plugin` Phase 8 with marketplace
publishing integration

## Problem

Fixes #86

Users asking to "create a marketplace", "organize multiple plugins", or
"distribute plugins" had no dedicated skill guidance. The
`plugin-structure` skill only mentioned marketplaces incidentally and
didn't cover:
- `marketplace.json` schema and required fields
- Multi-plugin organization within a marketplace
- Plugin source types (GitHub, git URLs, relative paths)
- Distribution strategies (GitHub hosting, team settings)
- The `strict` vs. non-strict mode distinction

## Solution

### New Skill: `marketplace-structure`

```
skills/marketplace-structure/
├── SKILL.md (~1,800 words)
├── references/
│   ├── schema-reference.md      # Complete marketplace.json field reference
│   └── distribution-patterns.md  # Hosting strategies, team setup
└── examples/
    ├── minimal-marketplace.md    # Single plugin marketplace
    ├── team-marketplace.md       # Internal company marketplace
    └── community-marketplace.md  # Public multi-plugin marketplace
```

### New Command: `/plugin-dev:create-marketplace`

8-phase guided workflow:
1. Discovery - Understand marketplace purpose
2. Plugin Planning - Determine plugins to include
3. Metadata Design - Configure marketplace metadata
4. Structure Creation - Create directory and manifest
5. Plugin Entry Configuration - Configure each plugin entry
6. Distribution Setup - Configure team settings or community guidelines
7. Validation - Run marketplace validators
8. Testing & Finalization - Test installation and finalize

### Enhanced Components

- **plugin-validator agent**: Added marketplace validation (schema,
entries, duplicates, source paths)
- **/plugin-dev:create-plugin Phase 8**: Now loads marketplace-structure
skill and guides through marketplace entry creation when publishing

### Alternatives Considered

1. **Add to plugin-structure skill** - Rejected: Different abstraction
level (marketplace contains plugins), would bloat skill beyond 2,000
words
2. **Add to plugin-settings skill** - Rejected: plugin-settings is about
.local.md configuration, not marketplace setup
3. **Document only in README** - Rejected: Actionable guidance should be
model-invoked

## Changes

- `plugins/plugin-dev/skills/marketplace-structure/` - New skill
directory with 6 files
- `plugins/plugin-dev/commands/create-marketplace.md` - New 8-phase
workflow command
- `plugins/plugin-dev/agents/plugin-validator.md` - Extended with
marketplace validation
- `plugins/plugin-dev/commands/create-plugin.md` - Enhanced Phase 8 for
marketplace publishing
- `CLAUDE.md` - Updated to reflect 8 skills, 2 commands
- `.claude-plugin/marketplace.json` - Description updated
- `plugins/plugin-dev/.claude-plugin/plugin.json` - Description updated

## Testing

- [x] All markdown files pass `markdownlint`
- [x] New skill follows established patterns (frontmatter, progressive
disclosure)
- [x] New command follows create-plugin structure
- [x] plugin-validator agent has valid frontmatter and examples

### Manual Testing Checklist

- [ ] Skill triggers on "create a marketplace" queries
- [ ] `/plugin-dev:create-marketplace` command appears and executes
- [ ] plugin-validator validates marketplace.json correctly

---
🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: sjnims

.claude-plugin/marketplace.json

@@ -11,7 +11,7 @@
   "plugins": [
     {
       "name": "plugin-dev",
-      "description": "Comprehensive toolkit for developing Claude Code plugins. Includes 7 expert skills covering hooks, MCP integration, commands, agents, and best practices. AI-assisted plugin creation and validation.",
+      "description": "Comprehensive toolkit for developing Claude Code plugins. Includes 8 expert skills covering hooks, MCP integration, commands, agents, marketplaces, and best practices. AI-assisted plugin creation and validation.",
       "version": "0.1.0",
       "author": {
         "name": "Daisy Hollman",

CLAUDE.md

@@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Overview
 
-This repository is a **plugin marketplace** containing the **plugin-dev** plugin - a comprehensive toolkit for developing Claude Code plugins. It provides 7 specialized skills, 3 agents, and 1 guided workflow command for building high-quality plugins.
+This repository is a **plugin marketplace** containing the **plugin-dev** plugin - a comprehensive toolkit for developing Claude Code plugins. It provides 8 specialized skills, 3 agents, and 2 guided workflow commands for building high-quality plugins and marketplaces.
 
 ## Quick Reference
 
@@ -22,7 +22,7 @@ plugin-dev/                      # Marketplace root
 │       │   └── plugin.json      # Plugin manifest
 │       ├── commands/            # Slash commands
 │       ├── agents/              # Autonomous agents
-│       └── skills/              # 7 specialized skills
+│       └── skills/              # 8 specialized skills
 └── .github/workflows/           # CI/CD workflows
 ```
 
@@ -46,7 +46,7 @@ Each skill follows progressive disclosure:
 - `examples/` - Complete working examples and templates for copy-paste
 - `scripts/` - Utility scripts (executable without loading into context)
 
-**The 7 Skills:**
+**The 8 Skills:**
 
 1. `hook-development` - Event-driven automation with prompt-based hooks
 2. `mcp-integration` - Model Context Protocol server configuration
@@ -55,8 +55,9 @@ Each skill follows progressive disclosure:
 5. `command-development` - Slash commands with frontmatter
 6. `agent-development` - Autonomous agents with AI-assisted generation
 7. `skill-development` - Creating skills with progressive disclosure
+8. `marketplace-structure` - Plugin marketplace creation and distribution
 
-**Note:** `mcp-integration`, `plugin-structure`, and `skill-development` have no utility scripts—they provide documentation and examples only.
+**Note:** `mcp-integration`, `plugin-structure`, `skill-development`, and `marketplace-structure` have no utility scripts—they provide documentation and examples only.
 
 ### Writing Style
 
@@ -174,7 +175,9 @@ Hooks defined in `hooks/hooks.json`:
 
 ## Workflow
 
-The `/plugin-dev:create-plugin` command provides an 8-phase guided workflow:
+### `/plugin-dev:create-plugin`
+
+An 8-phase guided workflow for plugin creation:
 
 1. Discovery - Understand requirements
 2. Component Planning - Determine needed components
@@ -183,13 +186,26 @@ The `/plugin-dev:create-plugin` command provides an 8-phase guided workflow:
 5. Component Implementation - Build each component
 6. Validation - Run validators
 7. Testing - Verify in Claude Code
-8. Documentation - Finalize README
+8. Documentation - Finalize README and marketplace publishing
+
+### `/plugin-dev:create-marketplace`
+
+An 8-phase guided workflow for marketplace creation:
+
+1. Discovery - Understand marketplace purpose
+2. Plugin Planning - Determine plugins to include
+3. Metadata Design - Configure marketplace metadata
+4. Structure Creation - Create directory and manifest
+5. Plugin Entry Configuration - Configure each plugin entry
+6. Distribution Setup - Configure team settings or community guidelines
+7. Validation - Run marketplace validators
+8. Testing & Finalization - Test installation and finalize
 
 ## Validation Agents
 
 Use these agents proactively after creating components:
 
-- **plugin-validator**: Validates entire plugin structure
+- **plugin-validator**: Validates entire plugin structure and marketplace.json
 - **skill-reviewer**: Reviews skill quality and triggering
 - **agent-creator**: Generates new agents from descriptions
 

plugins/plugin-dev/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "plugin-dev",
   "version": "0.1.0",
-  "description": "Comprehensive toolkit for developing Claude Code plugins. Includes 7 expert skills covering hooks, MCP integration, commands, agents, and best practices. AI-assisted plugin creation and validation.",
+  "description": "Comprehensive toolkit for developing Claude Code plugins. Includes 8 expert skills covering hooks, MCP integration, commands, agents, marketplaces, and best practices. AI-assisted plugin creation and validation.",
   "author": {
     "name": "Daisy Hollman",
     "email": "daisy@anthropic.com"

plugins/plugin-dev/agents/plugin-validator.md

@@ -1,6 +1,6 @@
 ---
 name: plugin-validator
-description: Use this agent when the user asks to "validate my plugin", "check plugin structure", "verify plugin is correct", "validate plugin.json", "check plugin files", or mentions plugin validation. Also trigger proactively after user creates or modifies plugin components. Examples:
+description: Use this agent when the user asks to "validate my plugin", "check plugin structure", "verify plugin is correct", "validate plugin.json", "check plugin files", "validate marketplace", "check marketplace.json", "verify marketplace structure", or mentions plugin or marketplace validation. Also trigger proactively after user creates or modifies plugin or marketplace components. Examples:
 
 <example>
 Context: User finished creating a new plugin
@@ -31,22 +31,42 @@ Manifest modified, validate to ensure correctness.
 assistant: "I'll use the plugin-validator agent to check the manifest."
 </example>
 
+<example>
+Context: User created or modified a marketplace
+user: "I've set up a marketplace.json for my plugins"
+assistant: "Let me validate the marketplace structure."
+<commentary>
+Marketplace created, validate schema and plugin entries.
+</commentary>
+assistant: "I'll use the plugin-validator agent to check the marketplace."
+</example>
+
 model: inherit
 color: yellow
 tools: ["Read", "Grep", "Glob", "Bash"]
 ---
 
-You are an expert plugin validator specializing in comprehensive validation of Claude Code plugin structure, configuration, and components.
+You are an expert plugin and marketplace validator specializing in comprehensive validation of Claude Code plugin structure, configuration, components, and plugin marketplaces.
 
 **Your Core Responsibilities:**
+
 1. Validate plugin structure and organization
 2. Check plugin.json manifest for correctness
 3. Validate all component files (commands, agents, skills, hooks)
 4. Verify naming conventions and file organization
-5. Check for common issues and anti-patterns
-6. Provide specific, actionable recommendations
+5. Validate marketplace.json schema and plugin entries
+6. Check for common issues and anti-patterns
+7. Provide specific, actionable recommendations
+
+## Detection: Plugin vs. Marketplace
 
-**Validation Process:**
+First, determine what type of validation is needed:
+
+- **Marketplace**: `.claude-plugin/marketplace.json` exists at repository root
+- **Plugin**: `.claude-plugin/plugin.json` exists (may be inside a marketplace's `plugins/` directory)
+- **Both**: Repository is a marketplace containing plugins (validate both)
+
+**Plugin Validation Process:**
 
 1. **Locate Plugin Root**:
    - Check for `.claude-plugin/plugin.json`
@@ -133,15 +153,66 @@ You are an expert plugin validator specializing in comprehensive validation of C
     - Hooks don't have obvious security issues
     - No secrets in example files
 
+**Marketplace Validation Process:**
+
+When `.claude-plugin/marketplace.json` is detected, perform marketplace-specific validation:
+
+1. **Validate Marketplace Schema**:
+   - Check JSON syntax
+   - Verify required fields:
+     - `name`: kebab-case string, 3-50 characters
+     - `owner`: object with at least `name` field
+     - `plugins`: non-empty array
+   - Validate optional `metadata` object:
+     - `description`: string
+     - `version`: semver format
+     - `pluginRoot`: valid relative path
+
+2. **Validate Plugin Entries**:
+   - For each entry in `plugins` array:
+     - `name` is required, kebab-case, unique within marketplace
+     - `source` is required (string or object)
+   - Check source types:
+     - String: relative path starting with `./` or `../`
+     - Object with `source: "github"`: has `repo` field
+     - Object with `source: "url"`: has `url` field
+   - Validate optional fields:
+     - `version`: semver format if present
+     - `license`: valid SPDX identifier if present
+
+3. **Check for Duplicate Names**:
+   - No duplicate plugin names in `plugins` array
+   - Report all duplicates if found
+
+4. **Validate Relative Source Paths**:
+   - For plugins with relative path sources:
+     - Check that the path exists
+     - If `strict: true` (default), verify `.claude-plugin/plugin.json` exists
+     - If `strict: false`, verify plugin directory exists
+   - Consider `metadata.pluginRoot` as base path
+
+5. **Cross-Validate Local Plugins**:
+   - For each relative path plugin:
+     - Run plugin validation on the referenced directory
+     - Report issues found in local plugins
+
+6. **Marketplace Best Practices**:
+   - Check all entries have `version` specified
+   - Check all entries have `description` specified
+   - Verify README.md documents the marketplace
+   - Suggest CHANGELOG.md for version tracking
+
 **Quality Standards:**
+
 - All validation errors include file path and specific issue
 - Warnings distinguished from errors
 - Provide fix suggestions for each issue
 - Include positive findings for well-structured components
 - Categorize by severity (critical/major/minor)
 
-**Output Format:**
+**Output Format for Plugin Validation:**
 
+```markdown
 ## Plugin Validation Report
 
 ### Plugin: [name]
@@ -180,14 +251,61 @@ Location: [path]
 ### Overall Assessment
 
 [PASS/FAIL] - [Reasoning]
+```
+
+**Output Format for Marketplace Validation:**
+
+```markdown
+## Marketplace Validation Report
+
+### Marketplace: [name]
+
+Location: [path]
+
+### Summary
+
+[Overall assessment - pass/fail with key stats]
+
+### Critical Issues ([count])
+
+- `file/path` - [Issue] - [Fix]
+
+### Warnings ([count])
+
+- `file/path` - [Issue] - [Recommendation]
+
+### Plugin Entries ([count])
+
+| Name | Source Type | Version | Status |
+|------|-------------|---------|--------|
+| [name] | [relative/github/url] | [version] | [valid/issues] |
+
+### Local Plugin Validation
+
+[For each relative path plugin, include summary of plugin validation]
+
+### Positive Findings
+
+- [What's done well]
+
+### Recommendations
+
+1. [Priority recommendation]
+2. [Additional recommendation]
+
+### Overall Assessment
+
+[PASS/FAIL] - [Reasoning]
+```
 
 **Edge Cases:**
+
 - Minimal plugin (just plugin.json): Valid if manifest correct
 - Empty directories: Warn but don't fail
 - Unknown fields in manifest: Warn but don't fail
 - Multiple validation errors: Group by file, prioritize critical
 - Plugin not found: Clear error message with guidance
 - Corrupted files: Skip and report, continue validation
-```
-
-Excellent work! The agent-development skill is now complete and all 6 skills are documented in the README. Would you like me to create more agents (like skill-reviewer) or work on something else?
+- Marketplace with only external plugins: Valid if schema correct
+- Marketplace with strict:false entries: Don't require plugin.json in those directories
+- Circular marketplace references: Detect and report