fix: add ci validation gaps and improve docs after full review

add semver format validation for versions in both marketplace and plugin
entries, cross-validate marketplace name against plugin.json name, expand
skill-creator readme with usage examples, add "what are plugins" section
to main readme, enhance pr template with testing checklist, fix
switch-provider category to ai-tools, clean up add-command template

Author: kossakovsky

.claude-plugin/marketplace.json

@@ -16,13 +16,13 @@
         "name": "kossakovsky"
       },
       "source": "./plugins/switch-provider",
-      "category": "utilities",
+      "category": "ai-tools",
       "tags": ["provider", "api", "configuration"],
       "keywords": ["provider", "switch", "api", "zai", "kimi", "minimax"]
     },
     {
       "name": "plugin-development",
-      "description": "Assist with Claude Code plugin development: scaffold, validate, review, and team-ready distribution",
+      "description": "A comprehensive toolkit for creating, validating, and distributing Claude Code plugins",
       "version": "1.3.0",
       "author": {
         "name": "kossakovsky"

.github/PULL_REQUEST_TEMPLATE.md

@@ -4,6 +4,7 @@
 
 **Plugin name:** `your-plugin-name`
 **Description:** Brief description of what your plugin does
+**What problem does it solve?** Explain the use case
 
 ### Checklist
 
@@ -13,3 +14,9 @@
 - [ ] Entry added to `.claude-plugin/marketplace.json`
 - [ ] Plugin name is kebab-case and matches directory name
 - [ ] No security issues (no data exfiltration, no dangerous operations)
+
+### Testing
+
+- [ ] Validated with `/plugin-development:validate`
+- [ ] Tested locally with `/plugin-development:test-local`
+- [ ] All commands work as documented

.github/workflows/validate-plugins.yml

@@ -105,6 +105,14 @@ jobs:
               exit 1
             fi
 
+            # Validate SemVer format in marketplace entry
+            mp_version=$(jq -r ".plugins[$i].version" .claude-plugin/marketplace.json)
+            if ! echo "$mp_version" | grep -qE '^[0-9]+\.[0-9]+\.[0-9]+$'; then
+              echo "✗ Plugin entry $((i+1)): version '$mp_version' is not valid SemVer (expected X.Y.Z)"
+              exit 1
+            fi
+            echo "✓ Plugin entry $((i+1)): version '$mp_version' is valid SemVer"
+
             # Validate source path format
             source=$(jq -r ".plugins[$i].source" .claude-plugin/marketplace.json)
             if ! echo "$source" | grep -qE '^\./plugins/[a-z0-9-]+$'; then
@@ -202,15 +210,30 @@ jobs:
             fi
             echo "✓ Plugin name matches directory name"
 
+            # Cross-validate: marketplace.json name must match plugin.json name
+            marketplace_name=$(jq -r --arg src "$plugin_path" '.plugins[] | select(.source == $src) | .name' .claude-plugin/marketplace.json)
+            if [ -n "$marketplace_name" ] && [ "$marketplace_name" != "$plugin_name_val" ]; then
+              echo "✗ Marketplace name '$marketplace_name' does not match plugin.json name '$plugin_name_val'"
+              exit 1
+            fi
+            echo "✓ Marketplace name matches plugin.json name"
+
             # Check version field
             if ! jq -e ".version" "$plugin_json" > /dev/null; then
               echo "✗ Missing required field: version"
               exit 1
             fi
             echo "✓ Required field 'version' present"
 
-            # Cross-validate: marketplace.json version must match plugin.json version
+            # Validate SemVer format
             plugin_version=$(jq -r ".version" "$plugin_json")
+            if ! echo "$plugin_version" | grep -qE '^[0-9]+\.[0-9]+\.[0-9]+$'; then
+              echo "✗ Version '$plugin_version' is not valid SemVer (expected X.Y.Z)"
+              exit 1
+            fi
+            echo "✓ Version '$plugin_version' is valid SemVer"
+
+            # Cross-validate: marketplace.json version must match plugin.json version
             marketplace_version=$(jq -r --arg src "$plugin_path" '.plugins[] | select(.source == $src) | .version' .claude-plugin/marketplace.json)
             if [ -n "$marketplace_version" ] && [ "$marketplace_version" != "$plugin_version" ]; then
               echo "✗ Marketplace version '$marketplace_version' does not match plugin.json version '$plugin_version'"

.gitignore

@@ -1,3 +1,6 @@
+# Dev marketplace (created by /plugin-development:test-local)
+dev-marketplace/
+
 # Claude Code
 .claude/settings.local.json
 .claude/cache/

README.md

@@ -5,6 +5,17 @@
 
 Community marketplace of plugins for [Claude Code](https://docs.anthropic.com/en/docs/claude-code). Claude Code plugins extend your CLI with new skills, slash commands, hooks, and agents. This marketplace is a single place where the community shares and discovers plugins — all installable with one command.
 
+## What Are Plugins?
+
+Claude Code plugins let you add new capabilities without modifying Claude Code itself:
+
+- **Slash commands** — custom actions triggered by `/<plugin>:<command>` (e.g., `/commit:commit`)
+- **Skills** — ambient knowledge that activates automatically based on context
+- **Agents** — specialized sub-agents for deep, multi-file analysis
+- **Hooks** — automated scripts that run at lifecycle events (before/after tool use, session start, etc.)
+
+Each plugin is a folder with a manifest and one or more of these components. No programming required — skills and commands are written in Markdown.
+
 ## Installation
 
 Add the marketplace:
@@ -23,7 +34,7 @@ Install any plugin:
 
 | Plugin | Version | Category | Description |
 |--------|---------|----------|-------------|
-| [switch-provider](plugins/switch-provider/) | 1.0.0 | utilities | Switch Claude Code between AI providers (Anthropic, Z.AI, Kimi, MiniMax) |
+| [switch-provider](plugins/switch-provider/) | 1.0.0 | ai-tools | Switch Claude Code between AI providers (Anthropic, Z.AI, Kimi, MiniMax) |
 | [plugin-development](plugins/plugin-development/) | 1.3.0 | developer-tools | Scaffold, validate, and submit Claude Code plugins |
 | [commit](plugins/commit/) | 1.0.0 | developer-tools | Smart git commits with conventional commit messages |
 | [skill-creator](plugins/skill-creator/) | 1.0.0 | developer-tools | Create and improve skills with evals and benchmarks |

plugins/plugin-development/README.md

@@ -60,12 +60,10 @@ Once installed, you can scaffold a new plugin:
 This scaffolds:
 - `.claude-plugin/plugin.json` - Plugin manifest
 - `commands/` - Slash commands directory
-- `agents/` - Sub-agents directory
-- `skills/` - Skills directory
-- `hooks/hooks.json` - Hook configuration
-- `scripts/` - Validation scripts
 - `README.md` - Documentation template
 
+Additional directories (`skills/`, `agents/`, `hooks/`, `scripts/`) are created on demand when you add components via `/plugin-development:add-skill`, `/plugin-development:add-agent`, or `/plugin-development:add-hook`.
+
 ### Add Components
 
 ```bash

plugins/plugin-development/commands/add-command.md

@@ -111,9 +111,6 @@ If validation fails, provide clear feedback.
 ---
 description: $2
 argument-hint: [arg1] [arg2]
-allowed-tools: Write, Edit
-model: claude-3-5-haiku-20241022
-disable-model-invocation: false
 ---
 
 # $1 Command
@@ -380,5 +377,5 @@ After creating a command:
 □ Command name is kebab-case
 □ Instructions are clear and specific
 □ Examples provided
-□ plugin.json has commands field
+□ plugin.json has commands field (only if using custom paths)
 ```

plugins/skill-creator/README.md

@@ -9,15 +9,27 @@ Create, modify, and improve Claude Code skills. Originally from [anthropics/skil
 /plugin install skill-creator@claude-code-plugins
 ```
 
-## What It Does
+## Usage
 
-The skill-creator activates automatically when you want to create or improve a Claude Code skill. It guides you through:
+The skill-creator is a **skill resource** (not a slash command). It activates automatically when you ask Claude Code to create or improve a skill:
 
-1. **Capturing intent** -- understanding what the skill should do and when it should trigger
-2. **Writing the SKILL.md** -- structured guidance on frontmatter, progressive disclosure, and writing patterns
-3. **Testing** -- running eval test cases with and without the skill
-4. **Iterating** -- improving based on feedback until the skill works well
-5. **Description optimization** -- tuning triggering accuracy
+```
+"Create a skill that generates unit tests for Python code"
+"Improve my debugging skill to handle async errors better"
+"I want to make a skill for code review"
+```
+
+Once activated, the skill guides you through an interactive workflow -- you describe your idea in plain text, and Claude Code handles the structure.
+
+## Workflow
+
+1. **Capture intent** -- Claude interviews you to understand what the skill should do and when it should trigger
+2. **Write SKILL.md** -- generates the skill file with proper frontmatter, progressive disclosure, and writing patterns
+3. **Test** -- runs eval test cases with and without the skill to measure effectiveness
+4. **Iterate** -- improves the skill based on test results until it performs well
+5. **Optimize description** -- tunes the trigger description for accurate activation
+
+Advanced features include blind A/B comparison between skill versions and benchmark tracking across iterations.
 
 ## Included
 

plugins/switch-provider/.claude-plugin/plugin.json

@@ -1,8 +1,10 @@
 {
   "name": "switch-provider",
   "version": "1.0.0",
-  "description": "Switch Claude Code between AI providers with a single command",
+  "description": "Switch Claude Code between AI providers (Anthropic, Z.AI, Kimi, MiniMax) with a single command",
   "author": { "name": "kossakovsky" },
+  "homepage": "https://github.com/kossakovsky/claude-code-plugins",
+  "repository": "https://github.com/kossakovsky/claude-code-plugins",
   "license": "MIT",
   "keywords": ["provider", "switch", "api", "zai", "kimi", "minimax"]
 }