fix: comprehensive review of docs, ci, and plugin accuracy

- fix dead docs.claude.com urls in plugin-development readme
- remove phantom posttooluse hook reference removed in v1.3.0
- add missing submit command to commands table and count
- fix contributing.md validation (hook script -> /plugin-development:validate)
- add categories documentation to contributing guide
- expand readme with version/category table and submit workflow
- add structured scoring system to pr review workflow
- add source path and version cross-validation to ci pipeline
- simplify init scaffolding to only create essential directories
- fix hooks.json description to match actual behavior
- add skill-creator attribution note for anthropics/skills origin
- sync claude.md plugin descriptions and validation instructions

Author: kossakovsky

.claude-plugin/marketplace.json

@@ -46,7 +46,7 @@
     },
     {
       "name": "skill-creator",
-      "description": "Create new skills, modify and improve existing skills, and measure skill performance with evals and benchmarks",
+      "description": "Create new skills, modify and improve existing skills, and measure skill performance with evals and benchmarks. Originally from anthropics/skills, community-maintained",
       "version": "1.0.0",
       "author": {
         "name": "anthropics"

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,3 +1,5 @@
+> Tip: You can automate this entire process with `/plugin-development:submit`
+
 ## Plugin Submission
 
 **Plugin name:** `your-plugin-name`

.github/workflows/review-pr.yml

@@ -26,11 +26,36 @@ jobs:
         with:
           claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
           prompt: |
-            Review this PR as a plugin marketplace submission. Check:
-            1. Plugin structure: plugins/<name>/ with .claude-plugin/plugin.json and README.md
-            2. plugin.json: valid JSON with name (kebab-case, matches directory), version, description
-            3. marketplace.json: entry added with correct source path, no duplicates
-            4. Security: no data exfiltration, no dangerous operations, no obfuscated code
-            5. Usefulness: solves a real problem, not spam or empty shell
-
-            Respond with: APPROVE, NEEDS_CHANGES (list specifics), or BLOCK (critical security issues).
+            Review this PR as a plugin marketplace submission.
+
+            ## Evaluation Criteria (score each 1-5):
+
+            ### 1. Structure (blocking if < 3)
+            - plugins/<name>/ directory exists
+            - .claude-plugin/plugin.json with name (kebab-case, matches directory), version, description
+            - README.md present with installation and usage sections
+
+            ### 2. Marketplace Integration (blocking if < 3)
+            - Entry added to marketplace.json with correct source path
+            - No duplicate plugin names
+            - Category and tags present
+
+            ### 3. Security (blocking if < 4)
+            - No data exfiltration patterns (sending files, env vars, secrets to external services)
+            - No dangerous/destructive operations without user confirmation
+            - No obfuscated or minified code that hides functionality
+            - No hardcoded secrets or API keys
+
+            ### 4. Quality & Usefulness (blocking if < 2)
+            - Solves a real problem, not spam or empty shell
+            - Commands/skills have meaningful content
+            - Documentation is clear and accurate
+
+            ## Response Format:
+
+            **Score:** Structure X/5 | Integration X/5 | Security X/5 | Quality X/5
+            **Total:** XX/20
+
+            **Verdict:** APPROVE (16+) | NEEDS_CHANGES (10-15, list specifics) | BLOCK (<10 or any blocking criteria failed)
+
+            **Details:** [specific findings per category]

.github/workflows/validate-plugins.yml

@@ -105,6 +105,14 @@ jobs:
               exit 1
             fi
 
+            # Validate source path format
+            source=$(jq -r ".plugins[$i].source" .claude-plugin/marketplace.json)
+            if ! echo "$source" | grep -qE '^\./plugins/[a-z0-9-]+$'; then
+              echo "✗ Plugin entry $((i+1)): source '$source' must match pattern ./plugins/<kebab-case-name>"
+              exit 1
+            fi
+            echo "✓ Plugin entry $((i+1)): source path format is valid"
+
             # Check author format if present
             if jq -e ".plugins[$i].author" .claude-plugin/marketplace.json > /dev/null; then
               if ! jq -e ".plugins[$i].author | type == \"object\"" .claude-plugin/marketplace.json > /dev/null; then
@@ -201,6 +209,15 @@ jobs:
             fi
             echo "✓ Required field 'version' present"
 
+            # Cross-validate: marketplace.json version must match plugin.json version
+            plugin_version=$(jq -r ".version" "$plugin_json")
+            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'"
+              exit 1
+            fi
+            echo "✓ Marketplace version matches plugin.json version"
+
             # Check description field
             if ! jq -e ".description" "$plugin_json" > /dev/null; then
               echo "✗ Missing required field: description"

CLAUDE.md

@@ -20,10 +20,11 @@ CI runs on push to main/develop and on PRs to main (`.github/workflows/validate-
 
 Local validation for plugin development:
 ```bash
-# Validate plugin structure (used by plugin-development hook on Write/Edit)
-plugins/plugin-development/scripts/validate-plugin.sh
+/plugin-development:validate
 ```
 
+Note: `plugins/plugin-development/scripts/validate-plugin.sh` is a hook script invoked automatically on Write/Edit — it cannot be run standalone.
+
 PR review is automated via Claude Code Action (`.github/workflows/review-pr.yml`).
 
 ## Architecture
@@ -48,10 +49,10 @@ Optional component directories:
 
 | Plugin | Purpose |
 |--------|---------|
-| `switch-provider` | Switch between AI providers (Anthropic, Z.AI, Kimi, MiniMax) |
-| `plugin-development` | Scaffold, validate, and review plugins |
-| `commit` | Smart git commits with conventional commit messages |
-| `skill-creator` | Create skills with evals and benchmarks |
+| `switch-provider` | Switch Claude Code between AI providers (Anthropic, Z.AI, Kimi, MiniMax) with a single command |
+| `plugin-development` | Scaffold, validate, review, and submit Claude Code plugins |
+| `commit` | Smart git commits with conventional commit message generation |
+| `skill-creator` | Create, improve, and measure skills with evals and benchmarks |
 
 ## PR Review Instructions
 

CONTRIBUTING.md

@@ -67,16 +67,26 @@ Required fields: `name`, `source`, `description`, `version`. The `name` must mat
 4. Ensure your plugin has a `README.md`
 5. Open a Pull Request
 
+**Or automate everything:** Install the `plugin-development` plugin and run `/plugin-development:submit` — it handles forking, branching, copying files, updating marketplace.json, and creating the PR for you.
+
 ### Local Validation
 
-Before submitting, verify your plugin passes validation:
+Before submitting, validate your plugin using the `plugin-development` plugin:
 
 ```bash
-# Validate plugin structure
-plugins/plugin-development/scripts/validate-plugin.sh
+# Install the plugin-development plugin
+/plugin install plugin-development@claude-code-plugins
+
+# Validate your plugin structure
+/plugin-development:validate
 ```
 
-You can also use the `plugin-development` plugin to scaffold and validate your plugin interactively.
+Or check marketplace JSON validity manually:
+
+```bash
+# Requires jq
+jq empty .claude-plugin/marketplace.json && echo "Valid JSON"
+```
 
 ### PR Requirements
 
@@ -86,6 +96,18 @@ You can also use the `plugin-development` plugin to scaffold and validate your p
 - `README.md` exists and describes installation and usage
 - CI validation passes (`validate-plugins.yml`)
 
+### Categories
+
+Choose a category for your plugin when adding it to `marketplace.json`:
+
+| Category | Description |
+|----------|-------------|
+| `utilities` | General-purpose tools and helpers |
+| `developer-tools` | Plugin development, code generation, git workflows |
+| `productivity` | Workflow automation, task management |
+| `ai-tools` | AI-related features, model switching, prompt tools |
+| `integrations` | External service integrations |
+
 ### Security Restrictions
 
 Plugins must NOT:

README.md

@@ -3,7 +3,7 @@
 [![Validate Plugins](https://github.com/kossakovsky/claude-code-plugins/actions/workflows/validate-plugins.yml/badge.svg)](https://github.com/kossakovsky/claude-code-plugins/actions/workflows/validate-plugins.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
-Community marketplace of plugins for [Claude Code](https://docs.anthropic.com/en/docs/claude-code). Skills, commands, hooks, and agents — all installable with a single command.
+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.
 
 ## Installation
 
@@ -21,18 +21,37 @@ Install any plugin:
 
 ## Plugins
 
-| Plugin | Description |
-|--------|-------------|
-| [switch-provider](plugins/switch-provider/) | Switch Claude Code between AI providers (Anthropic, Z.AI, Kimi, MiniMax) with a single command |
-| [plugin-development](plugins/plugin-development/) | Toolkit for creating, validating, and distributing Claude Code plugins |
-| [commit](plugins/commit/) | Smart git commits with conventional commit message generation |
-| [skill-creator](plugins/skill-creator/) | Create, test, and improve Claude Code skills with evals and benchmarks |
+| Plugin | Version | Category | Description |
+|--------|---------|----------|-------------|
+| [switch-provider](plugins/switch-provider/) | 1.0.0 | utilities | 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 |
 
-## Create Your Own Plugin
+## Create & Submit Your Plugin
 
 Anyone can contribute a plugin to the marketplace via Pull Request. Every PR goes through automated CI validation and a Claude Code review before being merged.
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for the full guide, or use the `plugin-development` plugin to scaffold your plugin interactively.
+The fastest way to create and submit a plugin:
+
+```bash
+# Install the plugin-development toolkit
+/plugin install plugin-development@claude-code-plugins
+
+# Scaffold a new plugin
+/plugin-development:init my-plugin
+
+# Add commands, skills, agents, hooks
+/plugin-development:add-command my-command "What it does"
+
+# Validate before submitting
+/plugin-development:validate
+
+# Submit to the marketplace via PR
+/plugin-development:submit
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the full guide.
 
 ## License
 

plugins/plugin-development/README.md

@@ -7,7 +7,7 @@ A comprehensive Claude Code plugin that assists developers in creating, validati
 The `plugin-development` plugin provides a complete toolkit for plugin authorship using a hybrid architecture:
 
 - **Skill (plugin-authoring)**: Ambient, auto-discovered guidance with progressive disclosure
-- **7 Slash Commands**: Explicit actions for scaffolding, validation, and testing
+- **8 Slash Commands**: Explicit actions for scaffolding, validation, testing, and submission
 - **Reviewer Agent**: Deep, multi-file audits and readiness checks
 - **Hooks**: Automated validation and formatting guardrails
 
@@ -117,6 +117,7 @@ This creates a dev marketplace and provides installation instructions for iterat
 | `/plugin-development:add-hook [event] [matcher]` | Add a hook configuration |
 | `/plugin-development:validate` | Validate plugin structure and configuration |
 | `/plugin-development:test-local` | Create dev marketplace for local testing |
+| `/plugin-development:submit [plugin-path]` | Submit a plugin to the community marketplace via PR |
 
 ## Skill: plugin-authoring
 
@@ -161,9 +162,6 @@ Automated validation and formatting hooks are included:
 - Exit code 2 blocks unsafe operations
 - Provides actionable error messages
 
-### PostToolUse
-- Runs formatting/linting after Write/Edit (stub, extend as needed)
-
 ### SessionStart
 - Displays plugin load confirmation
 
@@ -246,9 +244,15 @@ After making changes:
 
 Fix any critical or high-priority issues identified.
 
-### 7. Distribute
+### 7. Submit
+
+Submit your plugin to the community marketplace:
+
+```bash
+/plugin-development:submit
+```
 
-Add to your team marketplace repository and push to GitHub.
+See [CONTRIBUTING.md](../../CONTRIBUTING.md) for manual submission instructions.
 
 ## Documentation
 
@@ -354,7 +358,7 @@ For enhanced security, configure in `.claude/settings.json`:
 ### Hooks not running?
 - Make scripts executable: `chmod +x scripts/*.sh`
 - Use `${CLAUDE_PLUGIN_ROOT}` in hook commands
-- Test script directly: `./scripts/validate-plugin.sh`
+- Verify hook config in `hooks/hooks.json` matches expected events
 - Use `claude --debug` to see hook execution
 
 ## Contributing
@@ -374,10 +378,10 @@ To extend:
 ## Resources
 
 ### Official Documentation
-- [Claude Code Plugins](https://docs.claude.com/en/docs/claude-code/plugins)
-- [Plugin Marketplaces](https://docs.claude.com/en/docs/claude-code/plugin-marketplaces)
-- [Plugins Reference](https://docs.claude.com/en/docs/claude-code/plugins-reference)
-- [Slash Commands](https://docs.claude.com/en/docs/claude-code/slash-commands)
+- [Claude Code Plugins](https://docs.anthropic.com/en/docs/claude-code/plugins)
+- [Plugin Marketplaces](https://docs.anthropic.com/en/docs/claude-code/plugin-marketplaces)
+- [Plugins Reference](https://docs.anthropic.com/en/docs/claude-code/plugins-reference)
+- [Slash Commands](https://docs.anthropic.com/en/docs/claude-code/slash-commands)
 
 ### Local Documentation
 See `skills/plugin-authoring/` for:

plugins/plugin-development/commands/init.md

@@ -37,17 +37,15 @@ If validation fails, explain the requirements and ask for a valid name.
 
 ### Create Directory Structure
 
-Create these directories:
+Create these directories by default:
 ```
 $1/
 ├── .claude-plugin/
-├── commands/
-├── agents/
-├── skills/
-├── hooks/
-└── scripts/
+└── commands/
 ```
 
+Only create additional directories (`skills/`, `agents/`, `hooks/`, `scripts/`) when the user adds corresponding components via `/plugin-development:add-skill`, `/plugin-development:add-agent`, or `/plugin-development:add-hook`. Do not create empty directories.
+
 ### Create plugin.json
 
 Create `.claude-plugin/plugin.json` with this template:
@@ -66,17 +64,6 @@ Create `.claude-plugin/plugin.json` with this template:
 }
 ```
 
-### Create hooks.json
-
-Create `hooks/hooks.json` with a basic structure:
-
-```json
-{
-  "description": "Plugin hooks",
-  "hooks": {}
-}
-```
-
 ### Create README.md
 
 Create `README.md` with this template:
@@ -101,21 +88,6 @@ Create `README.md` with this template:
 [Provide examples]
 ```
 
-### Create Validation Script
-
-Create `scripts/validate-plugin.sh` with executable permissions:
-
-```bash
-#!/usr/bin/env bash
-set -euo pipefail
-
-# Basic plugin structure validation
-[ -f ".claude-plugin/plugin.json" ] || { echo "Missing plugin.json" >&2; exit 2; }
-exit 0
-```
-
-Make it executable: `chmod +x scripts/validate-plugin.sh`
-
 ## Next Steps
 
 After scaffolding, provide these instructions to the user:

plugins/plugin-development/hooks/hooks.json

@@ -1,5 +1,5 @@
 {
-  "description": "Auto-validate basic plugin structure and format code after edits",
+  "description": "Auto-validate basic plugin structure before edits",
   "hooks": {
     "PreToolUse": [
       {