docs: update plugin system with community marketplaces and official docs

Section 8.5 Plugin System: - CRITICAL FIX: Correct structure (.claude-plugin/plugin.json not root) - Add .mcp.json, .lsp.json, hooks/hooks.json to directory structure - Add skill namespacing documentation (/plugin-name:skill) - Add warning about common mistake (components outside .claude-plugin/) - Link to official Anthropic docs: code.claude.com/docs/en/plugins Community Marketplaces subsection (line 7246): - wshobson/agents: 67 plugins, 99 agents, 107 skills - claude-plugins.dev: 11,989 plugins, 63,065 skills indexed - Popular plugins: Context7 (~72k), Ralph Wiggum (~57k) - awesome-claude-code: 20k+ stars curated list Resource evaluation: Nick Jensen article rejected (outdated stats) - Primary sources integrated instead of blog post Co-Authored-By: Claude <noreply@anthropic.com>
2026-01-24 18:32:37 +01:00 · 2026-01-24 18:32:37 +01:00 · d2362401b1
commit d2362401b1
parent 873aade097
4 changed files with 127 additions and 15 deletions
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@ -8,6 +8,41 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).

 ### Added

+- **Plugin System Section 8.5 major update** (`guide/ultimate-guide.md:7092-7280`)
+  - **CRITICAL FIX**: Corrected plugin structure (`.claude-plugin/plugin.json` not root `plugin.json`)
+  - Added `.mcp.json`, `.lsp.json`, `hooks/hooks.json` to directory structure
+  - Added skill namespacing documentation (`/plugin-name:skill`)
+  - Added warning about common mistake (components outside `.claude-plugin/`)
+  - Added link to official Anthropic docs: code.claude.com/docs/en/plugins
+  - Source: [Anthropic Official Plugin Docs](https://code.claude.com/docs/en/plugins)
+
+- **Community Marketplaces subsection** (`guide/ultimate-guide.md:7246`)
+  - **wshobson/agents**: 67 plugins, 99 agents, 107 skills (verified Jan 2026)
+  - **claude-plugins.dev**: 11,989 plugins, 63,065 skills indexed
+  - **claudemarketplaces.com**: Auto-scan GitHub for marketplaces
+  - Popular plugins with install counts: Context7 (~72k), Ralph Wiggum (~57k), Figma MCP (~18k), Linear MCP (~9.5k)
+  - Curated lists: awesome-claude-code (20k+ stars)
+  - Installation examples for wshobson/agents
+  - Sources: [wshobson/agents](https://github.com/wshobson/agents), [claude-plugins.dev](https://claude-plugins.dev), [Firecrawl analysis](https://www.firecrawl.dev/blog/best-claude-code-plugins)
+
+- **Plugin ecosystem YAML index expansion** (`machine-readable/reference.yaml:137-164`)
+  - `plugins_official_docs`: Official Anthropic plugin documentation URL
+  - `plugins_official_reference`: Plugin reference docs URL
+  - `plugins_official_marketplaces`: Marketplace docs URL
+  - `plugins_wshobson_agents`: Stats and URL (67/99/107)
+  - `plugins_registry_claude_plugins_dev`: Registry stats (11,989/63,065)
+  - `plugins_registry_claudemarketplaces`: Auto-scan description
+  - `plugins_popular`: Top 4 plugins with install counts
+  - `plugins_awesome_list`: 20k+ stars curated list
+  - `plugins_community_marketplaces: 7246`: New section line number
+
+- **Resource evaluation: Nick Jensen plugins article** (`claudedocs/resource-evaluations/2026-01-24-nick-jensen-plugins.md`)
+  - Initial score 3/5 → Challenge 4/5 → Perplexity verification 2/5 (Marginal)
+  - Rejected as direct source: outdated stats (63/85/47 vs 67/99/107), unverified onboarding claim
+  - Perplexity research revealed better primary sources (Anthropic docs, wshobson README, claude-plugins.dev)
+  - Lesson: Blog posts often cite outdated data; verify against primary sources
+  - Decision: Integrate primary sources instead of article
+
 - **First plugin example: SE-CoVe (Chain-of-Verification)** (`examples/plugins/se-cove.md`)
  - Software Engineering adaptation of Meta's Chain-of-Verification methodology for Claude Code
  - Research foundation: Meta AI paper (arXiv:2309.11495), ACL 2024 Findings
--- a/README.md
+++ b/README.md
@ -6,7 +6,7 @@

 <p align="center">
  <a href="https://github.com/FlorianBruniaux/claude-code-ultimate-guide/stargazers"><img src="https://img.shields.io/github/stars/FlorianBruniaux/claude-code-ultimate-guide?style=for-the-badge" alt="Stars"/></a>
-  <a href="./examples/"><img src="https://img.shields.io/badge/Templates-83-green?style=for-the-badge" alt="Templates"/></a>
+  <a href="./examples/"><img src="https://img.shields.io/badge/Templates-82-green?style=for-the-badge" alt="Templates"/></a>
  <a href="./quiz/"><img src="https://img.shields.io/badge/Quiz-227_questions-orange?style=for-the-badge" alt="Quiz"/></a>
 </p>

@ -15,7 +15,7 @@
  <a href="https://zread.ai/FlorianBruniaux/claude-code-ultimate-guide"><img src="https://img.shields.io/badge/Ask_Zread-_.svg?style=flat&color=00b0aa&labelColor=000000&logo=data%3Aimage%2Fsvg%2Bxml%3Bbase64%2CPHN2ZyB3aWR0aD0iMTYiIGhlaWdodD0iMTYiIHZpZXdCb3g9IjAgMCAxNiAxNiIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KPHBhdGggZD0iTTQuOTYxNTYgMS42MDAxSDIuMjQxNTZDMS44ODgxIDEuNjAwMSAxLjYwMTU2IDEuODg2NjQgMS42MDE1NiAyLjI0MDFWNC45NjAxQzEuNjAxNTYgNS4zMTM1NiAxLjg4ODEgNS42MDAxIDIuMjQxNTYgNS42MDAxSDQuOTYxNTZDNS4zMTUwMiA1LjYwMDEgNS42MDE1NiA1LjMxMzU2IDUuNjAxNTYgNC45NjAxVjIuMjQwMUM1LjYwMTU2IDEuODg2NjQgNS4zMTUwMiAxLjYwMDEgNC45NjE1NiAxLjYwMDFaIiBmaWxsPSIjZmZmIi8%2BCjxwYXRoIGQ9Ik00Ljk2MTU2IDEwLjM5OTlIMi4yNDE1NkMxLjg4ODEgMTAuMzk5OSAxLjYwMTU2IDEwLjY4NjQgMS42MDE1NiAxMS4wMzk5VjEzLjc1OTlDMS42MDE1NiAxNC4xMTM0IDEuODg4MSAxNC4zOTk5IDIuMjQxNTYgMTQuMzk5OUg0Ljk2MTU2QzUuMzE1MDIgMTQuMzk5OSA1LjYwMTU2IDE0LjExMzQgNS42MDE1NiAxMy43NTk5VjExLjAzOTlDNS42MDE1NiAxMC42ODY0IDUuMzE1MDIgMTAuMzk5OSA0Ljk2MTU2IDEwLjM5OTlaIiBmaWxsPSIjZmZmIi8%2BCjxwYXRoIGQ9Ik0xMy43NTg0IDEuNjAwMUgxMS4wMzg0QzEwLjY4NSAxLjYwMDEgMTAuMzk4NCAxLjg4NjY0IDEwLjM5ODQgMi4yNDAxVjQuOTYwMUMxMC4zOTg0IDUuMzEzNTYgMTAuNjg1IDUuNjAwMSAxMS4wMzg0IDUuNjAwMUgxMy43NTg0QzE0LjExMTkgNS42MDAxIDE0LjM5ODQgNS4zMTM1NiAxNC4zOTg0IDQuOTYwMVYyLjI0MDFDMTQuMzk4NCAxLjg4NjY0IDE0LjExMTkgMS42MDAxIDEzLjc1ODQgMS42MDAxWiIgZmlsbD0iI2ZmZiIvPgo8cGF0aCBkPSJNNCAxMkwxMiA0TDQgMTJaIiBmaWxsPSIjZmZmIi8%2BCjxwYXRoIGQ9Ik00IDEyTDEyIDQiIHN0cm9rZT0iI2ZmZiIgc3Ryb2tlLXdpZHRoPSIxLjUiIHN0cm9rZS1saW5lY2FwPSJyb3VuZCIvPgo8L3N2Zz4K&logoColor=ffffff" alt="Ask Zread"/></a>
 </p>

-> Complete guide to Claude Code with 60+ production-ready templates
+> Complete guide to Claude Code with 82 production-ready templates

 ---

@ -64,7 +64,7 @@ Save as `CLAUDE.md` in your project root. Claude reads it automatically.

 **The problem**: Awesome-lists give links, not learning paths. Official docs are dense. Tutorials get outdated in weeks.

-**This guide**: Structured learning path with 83 copy-paste templates, from first install to advanced workflows.
+**This guide**: Structured learning path with 82 copy-paste templates, from first install to advanced workflows.

 **Reading time**: Quick Start ~15 min. Full guide ~3 hours (most read by section).

@ -225,7 +225,7 @@ claude-code-ultimate-guide/
 </details>

 <details>
-<summary><strong>Examples Library</strong> (83 templates)</summary>
+<summary><strong>Examples Library</strong> (82 templates)</summary>

 **Agents** (6): [code-reviewer](./examples/agents/code-reviewer.md), [test-writer](./examples/agents/test-writer.md), [security-auditor](./examples/agents/security-auditor.md), [refactoring-specialist](./examples/agents/refactoring-specialist.md), [output-evaluator](./examples/agents/output-evaluator.md), [devops-sre](./examples/agents/devops-sre.md) ⭐

@ -374,7 +374,7 @@ Claude Code sends your prompts, file contents, and MCP results to Anthropic serv

 | Repository | Purpose | Audience |
 |------------|---------|----------|
-| **[Claude Code Guide](https://github.com/FlorianBruniaux/claude-code-ultimate-guide)** *(this repo)* | Comprehensive documentation (13K lines, 83 templates) | Developers |
+| **[Claude Code Guide](https://github.com/FlorianBruniaux/claude-code-ultimate-guide)** *(this repo)* | Comprehensive documentation (13K lines, 82 templates) | Developers |
 | **[Claude Cowork Guide](https://github.com/FlorianBruniaux/claude-cowork-guide)** | Non-technical usage (67 prompts, 5 workflows) | Knowledge workers |
 | **Code Landing** *(to be deployed)* | Marketing site for Claude Code guide | Discovery |
 | **Cowork Landing** *(to be deployed)* | Marketing site for Cowork guide | Discovery |
--- a/guide/ultimate-guide.md
+++ b/guide/ultimate-guide.md
@ -7091,40 +7091,54 @@ This is useful for testing plugins before permanent installation.

 ### Creating Custom Plugins

-Plugins are structured directories with a manifest:
+Plugins are structured directories with a manifest inside `.claude-plugin/`:

 ```
 my-plugin/
-├── plugin.json           # Plugin manifest
+├── .claude-plugin/
+│   └── plugin.json       # Plugin manifest (ONLY file in this dir)
 ├── agents/
 │   └── my-agent.md       # Custom agents
 ├── skills/
-│   └── my-skill.md       # Custom skills
+│   └── code-review/
+│       └── SKILL.md      # Agent Skills (folder + SKILL.md)
 ├── commands/
-│   └── my-cmd.sh         # Custom commands
+│   └── my-cmd.md         # Slash commands
+├── hooks/
+│   └── hooks.json        # Event handlers
+├── .mcp.json             # MCP server configurations (optional)
+├── .lsp.json             # LSP server configurations (optional)
 └── README.md             # Documentation
 ```

-**Example `plugin.json`:**
+> ⚠️ **Common mistake**: Don't put `commands/`, `agents/`, `skills/`, or `hooks/` inside `.claude-plugin/`. Only `plugin.json` goes there.
+
+**Example `.claude-plugin/plugin.json`:**

 ```json
 {
  "name": "security-audit",
  "version": "1.0.0",
  "description": "Security audit tools for Claude Code",
-  "author": "Your Name",
-  "agents": ["agents/security-scanner.md"],
-  "skills": ["skills/owasp-check.md"],
-  "commands": ["commands/scan.sh"]
+  "author": {
+    "name": "Your Name"
+  }
 }
 ```

+> The manifest only defines metadata. Claude Code auto-discovers components from the directory structure.
+
+**Skill namespacing**: Plugin skills are prefixed with the plugin name to prevent conflicts:
+- Plugin `security-audit` with skill `scan` → `/security-audit:scan`
+
 **Validate before distribution:**

 ```bash
 claude plugin validate ./my-plugin
 ```

+**Official documentation**: [code.claude.com/docs/en/plugins](https://code.claude.com/docs/en/plugins)
+
 ### Plugin vs. MCP Server

 Understanding when to use which:
@ -7229,6 +7243,47 @@ claude plugin uninstall <conflicting-plugin>
 - Restart Claude Code after enabling/disabling
 - Check `~/.claude/plugins/` for installation

+v### Community Marketplaces
+
+The Claude Code plugin ecosystem has grown significantly. Here are verified community resources:
+
+**Major marketplaces:**
+
+| Marketplace | Stats | Focus |
+|-------------|-------|-------|
+| [wshobson/agents](https://github.com/wshobson/agents) | 67 plugins, 99 agents, 107 skills | Production-ready dev workflows, DevOps, security |
+| [claude-plugins.dev](https://claude-plugins.dev) | 11,989 plugins, 63,065 skills indexed | Registry + CLI for plugin discovery |
+| [claudemarketplaces.com](https://claudemarketplaces.com) | Auto-scans GitHub | Marketplace directory |
+
+**Installation example (wshobson/agents):**
+
+```bash
+# Add the marketplace
+/plugin marketplace add wshobson/agents
+
+# Browse available plugins
+/plugin
+
+# Install specific plugin
+/plugin install react-development
+```
+
+**Popular plugins by install count** (Jan 2026):
+
+| Plugin | Installs | Use case |
+|--------|----------|----------|
+| Context7 | ~72k | Library documentation lookup |
+| Ralph Wiggum | ~57k | Code review automation |
+| Figma MCP | ~18k | Design-to-code workflow |
+| Linear MCP | ~9.5k | Issue tracking integration |
+
+**Curated lists:**
+
+- [awesome-claude-code](https://github.com/hesreallyhim/awesome-claude-code) (20k+ stars) - Commands, templates, plugins
+- [awesome-claude-code-plugins](https://github.com/ccplugins/awesome-claude-code-plugins) - Plugin-focused curation
+
+> **Source**: Stats from [claude-plugins.dev](https://claude-plugins.dev), [Firecrawl analysis](https://www.firecrawl.dev/blog/best-claude-code-plugins) (Jan 2026). Counts evolve rapidly.
+
 ---

 ## 8.6 MCP Security
--- a/machine-readable/reference.yaml
+++ b/machine-readable/reference.yaml
@ -134,12 +134,34 @@ deep_dive:
    - "test-driven-development: 721 installs"
  skills_marketplace_status: "Community (Vercel Labs), launched Jan 21, 2026"
  skills_marketplace_changelog: "https://vercel.com/changelog/introducing-skills-the-open-agent-skills-ecosystem"
-  # Plugin System & Recommended Plugins (added 2026-01-24)
+  # Plugin System & Community Marketplaces (updated 2026-01-24)
  plugins_system: 6863
  plugins_commands: 6876
  plugins_marketplace: 6890
+  plugins_community_marketplaces: 7246  # New section with ecosystem stats
  plugins_recommended: "examples/plugins/"
  plugins_se_cove: "examples/plugins/se-cove.md"
+  plugins_official_docs: "https://code.claude.com/docs/en/plugins"
+  plugins_official_reference: "https://code.claude.com/docs/en/plugins-reference"
+  plugins_official_marketplaces: "https://code.claude.com/docs/en/plugin-marketplaces"
+  # Community plugin resources
+  plugins_wshobson_agents:
+    url: "https://github.com/wshobson/agents"
+    stats: "67 plugins, 99 agents, 107 skills"
+    updated: "2026-01-24"
+  plugins_registry_claude_plugins_dev:
+    url: "https://claude-plugins.dev"
+    stats: "11,989 plugins, 63,065 skills indexed"
+  plugins_registry_claudemarketplaces:
+    url: "https://claudemarketplaces.com"
+    purpose: "Auto-scan GitHub for .claude-plugin/marketplace.json"
+  plugins_popular:
+    - "Context7: ~72k installs (library docs lookup)"
+    - "Ralph Wiggum: ~57k installs (code review)"
+    - "Figma MCP: ~18k installs (design-to-code)"
+    - "Linear MCP: ~9.5k installs (issue tracking)"
+  plugins_awesome_list: "https://github.com/hesreallyhim/awesome-claude-code"
+  plugins_awesome_list_stars: "20k+"
  chain_of_verification: "guide/methodologies.md:165"
  chain_of_verification_paper: "https://arxiv.org/abs/2309.11495"
  chain_of_verification_acl: "https://aclanthology.org/2024.findings-acl.212/"