feat: add marketplace-structure skill for plugin marketplace creation

[sjnims]

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

• All markdown files pass markdownlint
• New skill follows established patterns (frontmatter, progressive disclosure)
• New command follows create-plugin structure
• 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

[claude]

Claude finished @sjnims's task —— View job

---

PR Review: feat: add marketplace-structure skill

Summary

✅ LOOKS EXCELLENT - This PR successfully addresses issue #86 with a comprehensive, well-structured marketplace skill that follows all plugin-dev conventions.

Todo List

• Get PR diff to understand changes
• Run markdownlint on changed .md files
• Review new marketplace-structure skill
• Review new create-marketplace command
• Review plugin-validator agent enhancements
• Review create-plugin command updates
• Check CLAUDE.md updates
• Verify manifest updates (marketplace.json, plugin.json)
• Post comprehensive review feedback

---

What's Good

Excellent Skill Structure ⭐

The new marketplace-structure skill (skills/marketplace-structure/SKILL.md:1) follows progressive disclosure perfectly:

• SKILL.md at 970 words - perfectly within the 1,500-2,000 word lean target
• Strong trigger phrases in frontmatter: "create a marketplace", "marketplace.json", "organize multiple plugins", "distribute plugins"
• Proper voice: Third-person in description ("This skill should be used when..."), imperative in body
• Progressive disclosure: Main content is concise, with detailed info in references/ (schema-reference.md, distribution-patterns.md)
• Excellent examples: Three complete templates (minimal, team, community) covering common use cases

Well-Designed Command ⭐

The /plugin-dev:create-marketplace command (commands/create-marketplace.md:1) mirrors the proven create-plugin workflow:

• 8-phase structure matches create-plugin pattern
• Clear frontmatter with description, argument-hint, and allowed-tools
• Strong guidance on when to ask questions vs. proceed
• Loads marketplace-structure skill explicitly in Phase 2
• Uses TodoWrite throughout
• User confirmation checkpoints at key decision points

Comprehensive Agent Enhancement ⭐

The plugin-validator agent updates (agents/plugin-validator.md:49) add thorough marketplace validation:

• Dual detection: Automatically determines plugin vs. marketplace vs. both
• Complete schema validation: Required fields, naming conventions, semver
• Source validation: Checks relative paths exist, validates source types
• Cross-validation: Validates local plugins within marketplaces
• Duplicate detection: Finds duplicate plugin names
• Clear output format: Separate report templates for plugins vs. marketplaces
• Strong trigger phrases: Added marketplace-specific triggers in description with examples

Integration with Existing Workflow ⭐

The create-plugin Phase 8 enhancement (commands/create-plugin.md:326) thoughtfully integrates marketplace publishing:

• Loads marketplace-structure skill when publishing
• Asks user about marketplace intent (doesn't assume)
• Handles three scenarios: existing marketplace, create new, skip
• Updates marketplace.json with proper entry format
• Validates after update using plugin-validator agent

Documentation Accuracy ⭐

• CLAUDE.md correctly updated to reflect "8 skills, 3 agents, and 2 guided workflow commands"
• marketplace.json description synced with plugin.json
• plugin.json description mentions "8 expert skills covering hooks, MCP integration, commands, agents, marketplaces"
• All references to skill count updated from 7 to 8

Schema Reference Quality ⭐

The references/schema-reference.md:1 provides complete field documentation:

• All required and optional fields documented
• Clear constraints (kebab-case, semver, character limits)
• Examples for each major concept
• Source types clearly explained (relative, GitHub, git URL)
• Strict vs. non-strict mode well explained

---

Markdown Linting

✅ All markdown files pass markdownlint - No style issues found.

---

Component Validation

Skill: marketplace-structure ✅

• YAML frontmatter with name and description present
• Name is kebab-case: marketplace-structure
• Description starts with "This skill should be used when..." ✓
• Strong trigger phrases included
• SKILL.md follows imperative form in body
• Progressive disclosure pattern (references/ and examples/ directories)
• Word count appropriate (970 words - lean and focused)

Command: create-marketplace ✅

• YAML frontmatter present with required description
• Optional argument-hint provided
• allowed-tools array properly formatted
• 8-phase structure matching create-plugin pattern
• Explicit Skill tool loading instructions
• TodoWrite usage mandated
• User confirmation checkpoints defined

Agent: plugin-validator ✅

• YAML frontmatter with all required fields (name, description, model, color)
• Name format valid: plugin-validator
• Description includes <example> blocks for triggering ✓
• New marketplace examples added
• Model is valid: inherit
• Color is valid: yellow
• Tools array valid: Read, Grep, Glob, Bash
• Comprehensive marketplace validation logic added

Command: create-plugin (Phase 8 updates) ✅

• Marketplace integration optional (asks user)
• Loads marketplace-structure skill when publishing
• Proper entry format documented
• Validates after marketplace update

---

Architecture & Patterns

Follows Plugin-Dev Conventions ✅

• No scripts/ directory in marketplace-structure (documentation-only skill, consistent with plugin-structure, mcp-integration)
• Progressive disclosure properly implemented
• ${CLAUDE_PLUGIN_ROOT} not needed (documentation skill, no executable components)
• Third-person/imperative voice correctly used
• Trigger phrases specific and actionable

Best Practices Applied ✅

• Version consistency: All version numbers match (0.1.0)
• kebab-case naming: marketplace-structure, create-marketplace
• Complete examples: Three templates cover minimal, team, and community cases
• Reference documentation: Separate schema and distribution pattern docs
• Real-world example: References this repo's own marketplace.json

---

Suggestions

Minor Enhancements (Not Blockers)

1. SKILL.md line 271: The "Working Example" section references this repository's marketplace.json as a real-world example. Consider adding a note that this marketplace has only one plugin currently, so for multi-plugin examples, see examples/community-marketplace.md.

2. plugin-validator.md line 310: The marketplace validation adds "Circular marketplace references: Detect and report" as an edge case. This is excellent forward-thinking, but there's no implementation guidance. Consider adding a brief note on how to detect this (e.g., tracking visited marketplace URLs during resolution).

3. create-marketplace.md Phase 5: For GitHub plugins (line 186), might be helpful to suggest running a quick check if the GitHub repo exists before adding the entry. This could prevent broken entries at creation time.

4. schema-reference.md: Consider adding a "Common Mistakes" section highlighting:

   • Forgetting the ./ prefix for relative paths
   • Using spaces in names instead of kebab-case
   • Missing repo field in GitHub source objects

---

Checklist Verification

From the PR description testing checklist:

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

Manual testing checklist (requires user testing):

• Skill triggers on "create a marketplace" queries - User to verify
• /plugin-dev:create-marketplace command appears and executes - User to verify
• plugin-validator validates marketplace.json correctly - User to verify

---

Overall Assessment

✅ APPROVED - This PR is ready to merge.

This is an exemplary addition that:

• Fills a real gap (marketplace creation had no dedicated guidance)
• Follows all plugin-dev architectural patterns
• Provides comprehensive documentation and examples
• Integrates seamlessly with existing workflows
• Maintains consistency with the codebase style
• Passes all linting and validation checks

The skill is well-scoped, the command provides clear step-by-step guidance, and the plugin-validator enhancements enable validation of the new component type. The four minor suggestions above are nice-to-haves that don't block this excellent work.

Recommendation: Merge this PR. The manual testing can be performed post-merge, and any issues found can be addressed in follow-up PRs.

---

[claude]

❌ CI Failure Analysis: Check Links

Run: #20083398431
Commit: f9cc672

Summary

The link checker (lychee) found a broken internal file reference in the marketplace-structure skill examples.

Failures Found

File	Line	Issue
plugins/plugin-dev/skills/marketplace-structure/examples/community-marketplace.md	129	Link to CONTRIBUTING.md file that doesn't exist

Details

The file community-marketplace.md contains this line:

See [CONTRIBUTING.md](CONTRIBUTING.md) for submission guidelines.

This is in a README template section (lines 105-134), but the link checker treats it as a real link to a file that should exist in the examples/ directory. The actual CONTRIBUTING.md template content is shown below on lines 136-166.

How to Fix

Option 1: Remove the link markup (recommended for templates)

See CONTRIBUTING.md for submission guidelines.

Option 2: Use a code block instead of a link

See `CONTRIBUTING.md` for submission guidelines.

Option 3: Add to .lycheeignore

examples/CONTRIBUTING.md

Option 1 or 2 is recommended since this is example/template content, not a real reference to a file in the repository.

---

🤖 Analyzed by Claude

[claude]

❌ CI Failure Analysis: Check Links

Run: #20083398431
Commit: f9cc672

Summary

The lychee link checker found a broken reference to CONTRIBUTING.md in the marketplace-structure skill examples. The link appears in an example README template (inside a markdown code block) but lychee still validates it.

Failures Found

File	Line	Issue
plugins/plugin-dev/skills/marketplace-structure/examples/community-marketplace.md	129	Reference to CONTRIBUTING.md that doesn't exist

How to Fix

Option 1: Create the example file (recommended for completeness)
Create plugins/plugin-dev/skills/marketplace-structure/examples/CONTRIBUTING.md with example content based on the template shown in the file (lines 138-166).

Option 2: Use a non-checked link format
Change line 129 from:

See [CONTRIBUTING.md](CONTRIBUTING.md) for submission guidelines.

To a plain text reference:

See CONTRIBUTING.md for submission guidelines.

Option 3: Add to .lycheeignore
Add this pattern to .lycheeignore:

file://.*marketplace-structure/examples/CONTRIBUTING.md

Recommendation: Option 1 is best as it provides a complete, working example that users can reference.

---

🤖 Analyzed by Claude

[claude]

Claude finished @sjnims's task —— View job

---

PR Review: feat: add marketplace-structure skill

Status: ✅ APPROVED - Ready to Merge

---

Todo List

• Get PR diff to understand current changes
• Check if CI failure (CONTRIBUTING.md link) was fixed
• Run markdownlint on changed .md files
• Review marketplace-structure skill structure
• Review plugin-validator agent enhancements
• Review create-marketplace command
• Review create-plugin command updates
• Verify CLAUDE.md and manifest updates
• Post comprehensive review findings

---

Summary

This PR successfully addresses issue #86 by adding comprehensive marketplace development support. The implementation is excellent - it follows all plugin-dev conventions, provides thorough documentation, and integrates seamlessly with existing workflows.

Key Achievement: The CI failure (broken CONTRIBUTING.md link) has been fixed in commit 12105e8 using the recommended backtick approach.

---

What's Good

1. Excellent Skill Structure ⭐

plugins/plugin-dev/skills/marketplace-structure/SKILL.md:1

• Perfect size: 970 words (well within the 1,500-2,000 word lean target)
• Strong trigger phrases: "create a marketplace", "marketplace.json", "organize multiple plugins", "distribute plugins"
• Proper voice: Third-person description ("This skill should be used when..."), imperative body content
• Progressive disclosure: Core content concise, detailed info in references/ (schema-reference.md, distribution-patterns.md)
• Comprehensive examples: Three complete templates covering minimal, team, and community use cases
• Consistent with conventions: No scripts/ directory (documentation-only skill like plugin-structure, mcp-integration)

2. Well-Designed Command ⭐

plugins/plugin-dev/commands/create-marketplace.md:1

• 8-phase structure mirrors proven create-plugin workflow
• Clear frontmatter with description, argument-hint, and allowed-tools
• Strong guidance on when to ask questions vs. proceed autonomously
• Explicit skill loading: Mandates loading marketplace-structure skill in Phase 2
• TodoWrite usage: Required throughout all phases
• User confirmation checkpoints at key decision points (Phases 1, 2, 3, 5, 7)
• Comprehensive coverage: Discovery → Planning → Design → Implementation → Validation → Testing

3. Comprehensive Agent Enhancement ⭐

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

• Dual detection: Automatically determines plugin vs. marketplace vs. both
• Complete marketplace validation:
  • Required fields (name, owner, plugins)
  • Schema validation (kebab-case, semver)
  • Source type validation (relative paths exist, proper formats)
  • Duplicate name detection
  • Cross-validation of local plugins within marketplaces
• Strong trigger phrases: Added marketplace-specific triggers with <example> blocks
• Clear output format: Separate report templates for plugins vs. marketplaces
• Smart handling: Respects strict: false mode when validating plugin entries

4. Thoughtful Integration ⭐

plugins/plugin-dev/commands/create-plugin.md:326

• Optional marketplace publishing in Phase 8
• Loads marketplace-structure skill when user opts to publish
• Handles three scenarios: existing marketplace, create new, or skip
• Proper entry format: Includes all recommended fields (name, source, description, version, category)
• Updates marketplace.json and bumps version
• Validates after update using plugin-validator agent
• Non-intrusive: Asks user instead of assuming they want marketplace publishing

5. Documentation Accuracy ⭐

• CLAUDE.md correctly updated:
  • "8 specialized skills" (line 25)
  • "8 skills, 3 agents, and 2 guided workflow commands" (Overview)
  • marketplace-structure listed as skill refactor: convert passive voice to imperative form in skill content #8 (line 58)
  • Noted as documentation-only (no scripts) (line 60)
• marketplace.json description synced with plugin.json
• plugin.json description mentions "8 expert skills covering hooks, MCP integration, commands, agents, marketplaces"

6. Schema Reference Quality ⭐

plugins/plugin-dev/skills/marketplace-structure/references/schema-reference.md:1

• Complete field documentation: All required and optional fields covered
• Clear constraints: kebab-case, semver, character limits documented
• Examples for each concept: Owner object, plugin entries, source types
• Source types well-explained: Relative paths, GitHub repos, git URLs
• Strict vs. non-strict mode: Clear distinction and use cases

7. CI Failure Fixed ✅

Commit 12105e8 correctly fixed the lychee link checker failure:

• Changed [CONTRIBUTING.md](CONTRIBUTING.md) to backticks: CONTRIBUTING.md
• Appropriate solution for template content (not an actual file reference)
• Follows Option 2 from the CI failure analysis

---

Markdown Linting

✅ All markdown files pass markdownlint with no errors

Files validated:

• plugins/plugin-dev/skills/marketplace-structure/SKILL.md
• plugins/plugin-dev/skills/marketplace-structure/examples/*.md
• plugins/plugin-dev/skills/marketplace-structure/references/*.md
• plugins/plugin-dev/commands/create-marketplace.md
• plugins/plugin-dev/agents/plugin-validator.md
• plugins/plugin-dev/commands/create-plugin.md
• CLAUDE.md

---

Component Validation

Skill: marketplace-structure ✅

• YAML frontmatter with name and description present
• Name is kebab-case: marketplace-structure
• Description starts with "This skill should be used when..."
• Strong trigger phrases included
• SKILL.md follows imperative form in body
• Progressive disclosure pattern (references/ and examples/ directories)
• Word count appropriate (970 words - lean and focused)
• No scripts/ directory (consistent with documentation-only skills)

Command: create-marketplace ✅

• YAML frontmatter with required description
• Optional argument-hint provided
• allowed-tools array properly formatted
• 8-phase structure matching create-plugin pattern
• Explicit Skill tool loading instructions (Phase 2)
• TodoWrite usage mandated throughout
• User confirmation checkpoints defined

Agent: plugin-validator ✅

• YAML frontmatter with all required fields (name, description, model, color)
• Name format valid: plugin-validator
• Description includes <example> blocks for marketplace triggering
• New marketplace examples added (lines 34-42)
• Model is valid: inherit
• Color is valid: yellow
• Tools array valid: Read, Grep, Glob, Bash
• Comprehensive marketplace validation logic added (lines 156-205)

Command: create-plugin (Phase 8 updates) ✅

• Marketplace integration optional (asks user)
• Loads marketplace-structure skill when publishing
• Proper entry format documented
• Validates after marketplace update
• Non-intrusive design

---

Architecture & Patterns

Follows Plugin-Dev Conventions ✅

• No scripts/ directory in marketplace-structure (consistent with plugin-structure, mcp-integration, skill-development)
• Progressive disclosure properly implemented
• ${CLAUDE_PLUGIN_ROOT} not needed (documentation skill, no executable components)
• Third-person/imperative voice correctly used
• Trigger phrases specific and actionable
• Version consistency: All version numbers synced (v0.1.0)

Best Practices Applied ✅

• kebab-case naming: marketplace-structure, create-marketplace
• Complete examples: Three templates cover minimal, team, and community cases
• Reference documentation: Separate schema and distribution pattern docs
• Real-world example: References this repo's own marketplace.json (line 271)
• Quality standards: Validation requirements clearly defined

---

Minor Suggestions (Optional Enhancements)

These are nice-to-haves that don't block merging:

1. SKILL.md line 271: The "Working Example" section references this repository's marketplace.json. Since this marketplace currently has only one plugin, consider adding a note directing users to examples/community-marketplace.md for multi-plugin examples.

2. plugin-validator.md line 311: Mentions "Circular marketplace references: Detect and report" as an edge case, but no implementation guidance provided. Consider adding a brief note on detection approach (e.g., tracking visited marketplace URLs).

3. create-marketplace.md Phase 5 (line 186): For GitHub plugins, could suggest running a quick check if the GitHub repo exists before adding the entry to prevent broken entries at creation time.

4. schema-reference.md: Consider adding a "Common Mistakes" section highlighting:

   • Forgetting the ./ prefix for relative paths
   • Using spaces in names instead of kebab-case
   • Missing repo field in GitHub source objects

---

Overall Assessment

✅ APPROVED - Ready to Merge

This PR represents exemplary work that:

• ✅ Fills a real gap in plugin-dev (marketplace creation had no dedicated guidance)
• ✅ Follows all architectural patterns and conventions
• ✅ Provides comprehensive documentation with excellent examples
• ✅ Integrates seamlessly with existing workflows
• ✅ Maintains consistency with codebase style
• ✅ Passes all linting and validation checks
• ✅ Fixes the CI failure (broken link)

The skill is well-scoped at 970 words, the command provides clear 8-phase guidance, the plugin-validator enhancements enable comprehensive marketplace validation, and the integration with create-plugin is thoughtful and non-intrusive.

Recommendation: Merge immediately. The four minor suggestions above are optional enhancements that can be addressed in follow-up PRs if desired.

---

Checklist Verification

From PR description:

• All markdown files pass markdownlint ✅
• New skill follows established patterns ✅
• New command follows create-plugin structure ✅
• plugin-validator agent has valid frontmatter and examples ✅
• CI failure fixed ✅

Manual testing (post-merge verification recommended):

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

---