diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0b47b93..dd7eb4e 100644
--- 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
diff --git a/README.md b/README.md
index d0c2cb0..9f64d34 100644
--- a/README.md
+++ b/README.md
@@ -6,7 +6,7 @@
- 
+ 
@@ -15,7 +15,7 @@
-> 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/
-Examples Library (83 templates)
+Examples Library (82 templates)
**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 |
diff --git a/guide/ultimate-guide.md b/guide/ultimate-guide.md
index d7f4458..716f7ea 100644
--- 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
- 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
diff --git a/machine-readable/reference.yaml b/machine-readable/reference.yaml
index 4f99dd6..75499d3 100644
--- 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/"