Update all concept README files with comprehensive documentation

Extract and consolidate information from claude_concepts_guide.md into individual concept folders: - 01-slash-commands: Add architecture diagrams, features table, lifecycle diagram, best practices, and comprehensive examples - 02-subagents: Add architecture, configuration, tool access hierarchy, context management, and practical delegation examples - 03-memory: Add memory hierarchy, locations table, lifecycle diagram, 4 practical examples, and features comparison - 04-mcp: Add MCP architecture, ecosystem, setup process, 4 examples (GitHub, Database, Multi-MCP, Filesystem), and security best practices - 05-skills: Add skill architecture, loading process, 3 complete examples with Python scripts (Code Review, Brand Voice, Documentation Generator) - 06-plugins: Add plugin architecture, marketplace, lifecycle, 3 examples, features comparison, and publishing guide - 07-hooks: Add hook types table, common examples, variables, 5 practical examples with code, and best practices - 08-checkpoints: Add key concepts, all commands, use cases table, configuration, 4 practical examples, and troubleshooting - 09-advanced-features: Add Planning Mode, Extended Thinking, Background Tasks, Permission Modes, Headless Mode, Session Management, interactive features, and complete configuration examples All READMEs now include: - Overview sections with clear explanations - Mermaid diagrams for visual understanding - Comprehensive tables and feature comparisons - Practical code examples and templates - Installation instructions - Best practices and troubleshooting - Cross-references to related concepts Total changes: +3706 lines of comprehensive documentation 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-08 01:51:06 +01:00
parent d17564a9f2
commit 41527aed26
9 changed files with 3776 additions and 657 deletions
--- a/06-plugins/README.md
+++ b/06-plugins/README.md
@@ -1,120 +1,87 @@
-# Claude Code Plugins Examples
+# Claude Code Plugins

 This folder contains complete plugin examples that bundle multiple Claude Code features into cohesive, installable packages.

-## What Are Plugins?
+## Overview

-Plugins are bundled collections of:
- Slash commands
- Subagents
- MCP servers
- Hooks
- Scripts and templates
+Claude Code Plugins are bundled collections of customizations (slash commands, subagents, MCP servers, and hooks) that install with a single command. They represent the highest-level extension mechanism—combining multiple features into cohesive, shareable packages.

-All installable with a single command.
+## Plugin Architecture

-## Available Plugins
+```mermaid
+graph TB
+    A["Plugin"]
+    B["Slash Commands"]
+    C["Subagents"]
+    D["MCP Servers"]
+    E["Hooks"]
+    F["Configuration"]

-### 1. PR Review Plugin
-**Location**: [pr-review/](pr-review/)
-
-**Purpose**: Complete PR review workflow with security, testing, and documentation checks
-
-**Features**:
- 3 slash commands (`/review-pr`, `/check-security`, `/check-tests`)
- 3 specialized subagents
- GitHub MCP integration
- Pre-review validation hook
-
-**Installation**:
-```bash
-/plugin install pr-review
+    A -->|bundles| B
+    A -->|bundles| C
+    A -->|bundles| D
+    A -->|bundles| E
+    A -->|bundles| F
 ```

-**Use Case**: Automated code reviews for pull requests
+## Plugin Loading Process

---
+```mermaid
+sequenceDiagram
+    participant User
+    participant Claude as Claude Code
+    participant Plugin as Plugin Marketplace
+    participant Install as Installation
+    participant SlashCmds as Slash Commands
+    participant Subagents
+    participant MCPServers as MCP Servers
+    participant Hooks
+    participant Tools as Configured Tools

-### 2. DevOps Automation Plugin
-**Location**: [devops-automation/](devops-automation/)
-
-**Purpose**: Complete DevOps automation for deployment, monitoring, and incident response
-
-**Features**:
- 4 slash commands (`/deploy`, `/rollback`, `/status`, `/incident`)
- 3 specialized subagents
- Kubernetes MCP integration
- Pre/post-deployment hooks
- Deployment scripts
-
-**Installation**:
-```bash
-/plugin install devops-automation
+    User->>Claude: /plugin install pr-review
+    Claude->>Plugin: Download plugin manifest
+    Plugin-->>Claude: Return plugin definition
+    Claude->>Install: Extract components
+    Install->>SlashCmds: Configure
+    Install->>Subagents: Configure
+    Install->>MCPServers: Configure
+    Install->>Hooks: Configure
+    SlashCmds-->>Tools: Ready to use
+    Subagents-->>Tools: Ready to use
+    MCPServers-->>Tools: Ready to use
+    Hooks-->>Tools: Ready to use
+    Tools-->>Claude: Plugin installed ✅
 ```

-**Use Case**: Kubernetes deployment automation and incident management
+## Plugin Types & Distribution

---
+| Type | Scope | Shared | Authority | Examples |
+|------|-------|--------|-----------|----------|
+| Official | Global | All users | Anthropic | PR Review, Security Guidance |
+| Community | Public | All users | Community | DevOps, Data Science |
+| Organization | Internal | Team members | Company | Internal standards, tools |
+| Personal | Individual | Single user | Developer | Custom workflows |

-### 3. Documentation Plugin
-**Location**: [documentation/](documentation/)
-
-**Purpose**: Comprehensive documentation generation and maintenance
-
-**Features**:
- 4 slash commands
- 3 documentation subagents
- GitHub MCP integration
- Documentation templates (API, function, ADR)
-
-**Installation**:
-```bash
-/plugin install documentation
-```
-
-**Use Case**: Automated documentation generation and maintenance
-
---
-
-## Plugin Structure
-
-```
-plugin-name/
-├── plugin.yaml           # Plugin manifest
-├── commands/             # Slash commands
-│   ├── command-1.md
-│   └── command-2.md
-├── agents/               # Subagents
-│   ├── agent-1.md
-│   └── agent-2.md
-├── mcp/                  # MCP configurations
-│   └── config.json
-├── hooks/                # Event hooks
-│   ├── pre-hook.js
-│   └── post-hook.js
-├── scripts/              # Helper scripts
-│   └── script.sh
-├── templates/            # Document templates
-│   └── template.md
-└── README.md             # Plugin documentation
-```
-
-## Plugin Manifest (plugin.yaml)
+## Plugin Definition Structure

 ```yaml
 ---
 name: plugin-name
 version: "1.0.0"
-description: What this plugin does
-author: Your Name
+description: "What this plugin does"
+author: "Your Name"
 license: MIT
+
+# Plugin metadata
 tags:
  - category
  - use-case

+# Requirements
 requires:
  - claude-code: ">=1.0.0"

+# Components bundled
 components:
  - type: commands
    path: commands/
@@ -125,12 +92,233 @@ components:
  - type: hooks
    path: hooks/

+# Configuration
 config:
  auto_load: true
  enabled_by_default: true
 ---
 ```

+## Plugin Structure Example
+
+```
+my-plugin/
+├── plugin.yaml
+├── commands/
+│   ├── task-1.md
+│   ├── task-2.md
+│   └── workflows/
+├── agents/
+│   ├── specialist-1.md
+│   ├── specialist-2.md
+│   └── configs/
+├── mcp/
+│   ├── mcp-config.json
+│   └── servers/
+├── hooks/
+│   ├── pre-deploy.js
+│   └── post-merge.js
+├── templates/
+│   └── issue-template.md
+├── scripts/
+│   ├── helper-1.sh
+│   └── helper-2.py
+├── docs/
+│   ├── README.md
+│   └── USAGE.md
+└── tests/
+    └── plugin.test.js
+```
+
+## Practical Examples
+
+### Example 1: PR Review Plugin
+
+**File:** `plugin.yaml`
+
+```yaml
+---
+name: pr-review
+version: "1.0.0"
+description: Complete PR review workflow with security, testing, and docs
+author: Anthropic
+tags:
+  - code-review
+  - quality
+  - security
+
+components:
+  - type: commands
+    path: commands/
+  - type: agents
+    path: agents/
+  - type: mcp
+    path: mcp/
+  - type: hooks
+    path: hooks/
+---
+```
+
+**File:** `commands/review-pr.md`
+
+```markdown
+---
+name: Review PR
+description: Start comprehensive PR review with security and testing checks
+---
+
+# PR Review
+
+This command initiates a complete pull request review including:
+
+1. Security analysis
+2. Test coverage verification
+3. Documentation updates
+4. Code quality checks
+5. Performance impact assessment
+```
+
+**File:** `agents/security-reviewer.md`
+
+```yaml
+---
+name: security-reviewer
+description: Security-focused code review
+tools: read, grep, diff
+---
+
+# Security Reviewer
+
+Specializes in finding security vulnerabilities:
+- Authentication/authorization issues
+- Data exposure
+- Injection attacks
+- Secure configuration
+```
+
+**Installation:**
+
+```bash
+/plugin install pr-review
+
+# Result:
+# ✅ 3 slash commands installed
+# ✅ 3 subagents configured
+# ✅ 2 MCP servers connected
+# ✅ 4 hooks registered
+# ✅ Ready to use!
+```
+
+### Example 2: DevOps Plugin
+
+**Components:**
+
+```
+devops-automation/
+├── commands/
+│   ├── deploy.md
+│   ├── rollback.md
+│   ├── status.md
+│   └── incident.md
+├── agents/
+│   ├── deployment-specialist.md
+│   ├── incident-commander.md
+│   └── alert-analyzer.md
+├── mcp/
+│   ├── github-config.json
+│   ├── kubernetes-config.json
+│   └── prometheus-config.json
+├── hooks/
+│   ├── pre-deploy.js
+│   ├── post-deploy.js
+│   └── on-error.js
+└── scripts/
+    ├── deploy.sh
+    ├── rollback.sh
+    └── health-check.sh
+```
+
+### Example 3: Documentation Plugin
+
+**Bundled Components:**
+
+```
+documentation/
+├── commands/
+│   ├── generate-api-docs.md
+│   ├── generate-readme.md
+│   ├── sync-docs.md
+│   └── validate-docs.md
+├── agents/
+│   ├── api-documenter.md
+│   ├── code-commentator.md
+│   └── example-generator.md
+├── mcp/
+│   ├── github-docs-config.json
+│   └── slack-announce-config.json
+└── templates/
+    ├── api-endpoint.md
+    ├── function-docs.md
+    └── adr-template.md
+```
+
+## Plugin Marketplace
+
+```mermaid
+graph TB
+    A["Plugin Marketplace"]
+    B["Official<br/>Anthropic"]
+    C["Community<br/>Marketplace"]
+    D["Enterprise<br/>Registry"]
+
+    A --> B
+    A --> C
+    A --> D
+
+    B -->|Categories| B1["Development"]
+    B -->|Categories| B2["DevOps"]
+    B -->|Categories| B3["Documentation"]
+
+    C -->|Search| C1["DevOps Automation"]
+    C -->|Search| C2["Mobile Dev"]
+    C -->|Search| C3["Data Science"]
+
+    D -->|Internal| D1["Company Standards"]
+    D -->|Internal| D2["Legacy Systems"]
+    D -->|Internal| D3["Compliance"]
+```
+
+## Plugin Installation & Lifecycle
+
+```mermaid
+graph LR
+    A["Discover"] -->|Browse| B["Marketplace"]
+    B -->|Select| C["Plugin Page"]
+    C -->|View| D["Components"]
+    D -->|Install| E["/plugin install"]
+    E -->|Extract| F["Configure"]
+    F -->|Activate| G["Use"]
+    G -->|Check| H["Update"]
+    H -->|Available| G
+    G -->|Done| I["Disable"]
+    I -->|Later| J["Enable"]
+    J -->|Back| G
+```
+
+## Plugin Features Comparison
+
+| Feature | Slash Command | Skill | Subagent | Plugin |
+|---------|---------------|-------|----------|--------|
+| **Installation** | Manual copy | Manual copy | Manual config | One command |
+| **Setup Time** | 5 minutes | 10 minutes | 15 minutes | 2 minutes |
+| **Bundling** | Single file | Single file | Single file | Multiple |
+| **Versioning** | Manual | Manual | Manual | Automatic |
+| **Team Sharing** | Copy file | Copy file | Copy file | Install ID |
+| **Updates** | Manual | Manual | Manual | Auto-available |
+| **Dependencies** | None | None | None | May include |
+| **Marketplace** | No | No | No | Yes |
+| **Distribution** | Repository | Repository | Repository | Marketplace |
+
 ## Installation Methods

 ### Official Plugin
@@ -150,79 +338,117 @@ config:

 ## When to Create a Plugin

-Create a plugin when:
+```mermaid
+graph TD
+    A["Should I create a plugin?"]
+    A -->|Need multiple components| B{"Multiple commands<br/>or subagents<br/>or MCPs?"}
+    B -->|Yes| C["✅ Create Plugin"]
+    B -->|No| D["Use Individual Feature"]
+    A -->|Team workflow| E{"Share with<br/>team?"}
+    E -->|Yes| C
+    E -->|No| F["Keep as Local Setup"]
+    A -->|Complex setup| G{"Needs auto<br/>configuration?"}
+    G -->|Yes| C
+    G -->|No| D
+```

-✅ You have multiple related commands/agents
-✅ You want one-command installation
-✅ You're sharing with a team
-✅ You need version control
-✅ You want marketplace distribution
-✅ Complex setup requires automation
+### Plugin Use Cases

-Don't create a plugin when:
+| Use Case | Recommendation | Why |
+|----------|-----------------|-----|
+| **Team Onboarding** | ✅ Use Plugin | Instant setup, all configurations |
+| **Framework Setup** | ✅ Use Plugin | Bundles framework-specific commands |
+| **Enterprise Standards** | ✅ Use Plugin | Central distribution, version control |
+| **Quick Task Automation** | ❌ Use Command | Overkill complexity |
+| **Single Domain Expertise** | ❌ Use Skill | Too heavy, use skill instead |
+| **Specialized Analysis** | ❌ Use Subagent | Create manually or use skill |
+| **Live Data Access** | ❌ Use MCP | Standalone, don't bundle |

-❌ Single slash command is sufficient
-❌ One-time use case
-❌ Personal preference (use individual features)
-❌ Very simple functionality
+## Publishing a Plugin

-## Plugin vs Individual Features
+**Steps to publish:**

-| Aspect | Plugin | Individual Features |
-|--------|--------|-------------------|
-| **Installation** | One command | Manual copy per feature |
-| **Setup Time** | 2 minutes | 15-30 minutes |
-| **Components** | Multiple bundled | One at a time |
-| **Versioning** | Automatic | Manual |
-| **Team Sharing** | Plugin ID | Copy files |
-| **Updates** | Auto-available | Manual |
-| **Marketplace** | Yes | No |
+1. Create plugin structure with all components
+2. Write `plugin.yaml` manifest
+3. Create `README.md` with documentation
+4. Test locally with `/plugin install ./my-plugin`
+5. Submit to plugin marketplace
+6. Get reviewed and approved
+7. Published on marketplace
+8. Users can install with one command

-## Creating Your Own Plugin
+**Example submission:**

-### Step 1: Create Structure
+```markdown
+# PR Review Plugin
+
+## Description
+Complete PR review workflow with security, testing, and documentation checks.
+
+## What's Included
+- 3 slash commands for different review types
+- 3 specialized subagents
+- GitHub and CodeQL MCP integration
+- Automated security scanning hooks
+
+## Installation
 ```bash
-mkdir my-plugin
-cd my-plugin
-mkdir commands agents mcp hooks scripts templates
+/plugin install pr-review
 ```

-### Step 2: Create plugin.yaml
-```yaml
---
-name: my-plugin
-version: "1.0.0"
-description: My custom plugin
-author: Your Name
---
-```
+## Features
+✅ Security analysis
+✅ Test coverage checking
+✅ Documentation verification
+✅ Code quality assessment
+✅ Performance impact analysis

-### Step 3: Add Components
- Add slash commands to `commands/`
- Add subagents to `agents/`
- Add MCP configs to `mcp/`
- Add hooks to `hooks/`
- Add helper scripts to `scripts/`
-
-### Step 4: Test Locally
+## Usage
 ```bash
-/plugin install ./my-plugin
+/review-pr
+/check-security
+/check-tests
 ```

-### Step 5: Publish
-Submit to plugin marketplace or share via git repository.
+## Requirements
+- Claude Code 1.0+
+- GitHub access
+- CodeQL (optional)
+```
+
+## Plugin vs Manual Configuration
+
+**Manual Setup (2+ hours):**
+- Install slash commands one by one
+- Create subagents individually
+- Configure MCPs separately
+- Set up hooks manually
+- Document everything
+- Share with team (hope they configure correctly)
+
+**With Plugin (2 minutes):**
+```bash
+/plugin install pr-review
+# ✅ Everything installed and configured
+# ✅ Ready to use immediately
+# ✅ Team can reproduce exact setup
+```

 ## Best Practices

 ### Do's ✅
 - Use clear, descriptive plugin names
 - Include comprehensive README
- Version your plugin properly
+- Version your plugin properly (semver)
 - Test all components together
 - Document requirements clearly
 - Provide usage examples
 - Include error handling
 - Tag appropriately for discovery
+- Maintain backward compatibility
+- Keep plugins focused and cohesive
+- Include comprehensive tests
+- Document all dependencies

 ### Don'ts ❌
 - Don't bundle unrelated features
@@ -231,45 +457,82 @@ Submit to plugin marketplace or share via git repository.
 - Don't forget documentation
 - Don't create redundant plugins
 - Don't ignore versioning
+- Don't overcomplicate component dependencies
+- Don't forget to handle errors gracefully

-## Plugin Lifecycle
+## Installation Instructions

-```
-Discover → Install → Configure → Use → Update → Disable/Remove
-```
+### Installing from Marketplace

-### Discovery
-Browse plugin marketplace or search by tags
+1. **Browse available plugins:**
+   ```bash
+   /plugin list
+   ```
+
+2. **View plugin details:**
+   ```bash
+   /plugin info plugin-name
+   ```
+
+3. **Install a plugin:**
+   ```bash
+   /plugin install plugin-name
+   ```
+
+### Installing from Local Path

-### Installation
 ```bash
-/plugin install plugin-name
+/plugin install ./path/to/plugin-directory
 ```

-### Configuration
-Set up required environment variables and credentials
+### Installing from GitHub

-### Usage
-Use slash commands, subagents work automatically
+```bash
+/plugin install github:username/repo
+```
+
+### Listing Installed Plugins
+
+```bash
+/plugin list --installed
+```
+
+### Updating a Plugin

-### Updates
 ```bash
 /plugin update plugin-name
 ```

-### Disable
+### Disabling/Enabling a Plugin
+
 ```bash
+# Temporarily disable
 /plugin disable plugin-name
+
+# Re-enable
+/plugin enable plugin-name
 ```

-### Remove
+### Uninstalling a Plugin
+
 ```bash
 /plugin uninstall plugin-name
 ```

-## Example: Complete Workflow
+## Related Concepts

-### PR Review Plugin Workflow
+The following Claude Code features work together with plugins:
+
+- **[Slash Commands](../01-slash-commands/)** - Individual commands bundled in plugins
+- **[Subagents](../03-subagents/)** - Specialized agents included as plugin components
+- **[MCP Servers](../04-mcp-servers/)** - Model Context Protocol integrations bundled in plugins
+- **[Hooks](../05-hooks/)** - Event handlers that trigger plugin workflows
+- **[Skills](../02-skills/)** - Domain expertise that can be wrapped into plugins
+- **[Environments](../07-environments/)** - Configuration and secrets management for plugins
+
+## Complete Example Workflow
+
+### PR Review Plugin Full Workflow

 ```
 1. User: /review-pr
@@ -291,23 +554,41 @@ Use slash commands, subagents work automatically
 ## Troubleshooting

 ### Plugin Won't Install
- Check Claude Code version compatibility
- Verify plugin.yaml syntax
+- Check Claude Code version compatibility: `/version`
+- Verify `plugin.yaml` syntax with `yaml` validator
 - Check internet connection (for remote plugins)
+- Review permissions: `ls -la plugin/`

 ### Components Not Loading
- Verify paths in plugin.yaml
- Check file permissions
+- Verify paths in `plugin.yaml` match actual directory structure
+- Check file permissions: `chmod +x scripts/`
 - Review component file syntax
+- Check logs: `/plugin debug plugin-name`

 ### MCP Connection Failed
- Verify environment variables are set
- Check MCP server installation
- Test MCP connection independently
+- Verify environment variables are set correctly
+- Check MCP server installation and health
+- Test MCP connection independently with `/mcp test`
+- Review MCP configuration in `mcp/` directory
+
+### Commands Not Available After Install
+- Ensure plugin was installed successfully: `/plugin list --installed`
+- Check if plugin is enabled: `/plugin status plugin-name`
+- Restart Claude Code: `exit` and reopen
+- Check for naming conflicts with existing commands
+
+### Hook Execution Issues
+- Verify hook files have correct permissions
+- Check hook syntax and event names
+- Review hook logs for error details
+- Test hooks manually if possible

 ## Additional Resources

- [Plugin Development Guide](https://docs.claude.com/plugins)
+- [Claude Code Documentation](https://docs.claude.com/claude-code)
 - [Plugin Marketplace](https://plugins.claude.com)
- [Example Plugins Repository](https://github.com/anthropic/claude-plugins)
- [Plugin API Reference](https://docs.claude.com/api/plugins)
+- [Official Plugin Examples](https://github.com/anthropic/claude-plugins)
+- [Plugin Development Guide](https://docs.claude.com/plugins/development)
+- [MCP Server Reference](https://spec.modelcontextprotocol.io/)
+- [Subagent Configuration Guide](../03-subagents/README.md)
+- [Hook System Reference](../05-hooks/README.md)