feat(docs): add comprehensive Plugin System documentation (v2.6.0)
Add Section 8.5 Plugin System with complete coverage of Claude Code's plugin marketplace and extensibility features. Resolve keyboard shortcut documentation inconsistency. **Added:** - Section 8.5 Plugin System (~245 lines) - Plugin commands: install, enable, disable, uninstall, update - Marketplace management (add, list, update, remove) - Custom plugin creation guide with manifest structure - Plugin vs MCP Server comparison - Security considerations and best practices - Real-world use cases (team standards, security audit, a11y) - Troubleshooting guide - Esc×2 double-tap shortcut in keyboard shortcuts table - /plugin command in commands reference - --plugin-dir flag in CLI flags reference **Changed:** - Updated Table of Contents with Plugin System entry - Enhanced Section 8 navigation with plugin link - Added Plugins to Power Features in TL;DR - Version bumped: 2.5 → 2.6 (README + guide) **Stats:** - Guide: 8,545 → 8,787 lines (+242 lines, +2.8%) - Focus: Extensibility and community-driven functionality Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
Florian BRUNIAUX
parent
76845f8226
commit
c7184ea5da
4 changed files with 310 additions and 577 deletions
62
CHANGELOG.md
62
CHANGELOG.md
|
|
@ -6,6 +6,68 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
|
|||
|
||||
## [Unreleased]
|
||||
|
||||
## [2.6.0] - 2026-01-11
|
||||
|
||||
### Added
|
||||
- **Section 8.5: Plugin System** (~245 lines, comprehensive documentation)
|
||||
- **Plugin System fundamentals** (lines 4836-5073)
|
||||
- What are plugins: packaged agents, skills, commands, domain-specific tooling
|
||||
- Plugin commands table: install, enable, disable, uninstall, update, validate
|
||||
- Marketplace management: add, list, update, remove marketplaces
|
||||
- Using plugins workflow from marketplace to session usage
|
||||
- Plugin session loading with `--plugin-dir` flag for testing
|
||||
- **When to Use Plugins** decision matrix
|
||||
- Team workflows: Share standardized agents/skills via private marketplace
|
||||
- Domain expertise: Pre-built security, accessibility, performance plugins
|
||||
- Repeating patterns: Package custom workflows for reuse
|
||||
- Community solutions: Leverage community expertise
|
||||
- **Creating Custom Plugins** guide
|
||||
- Directory structure with manifest (plugin.json)
|
||||
- Example security-audit plugin manifest
|
||||
- Validation command: `claude plugin validate ./my-plugin`
|
||||
- **Plugin vs. MCP Server** comparison table
|
||||
- Plugin = "How Claude thinks" (workflows, specialized agents)
|
||||
- MCP Server = "What Claude can do" (tools, external systems)
|
||||
- Clear guidance on when to use which
|
||||
- **Security Considerations** section
|
||||
- Before installing: trust source, review manifest, test in isolation
|
||||
- Red flags: network access without reason, obfuscated code, no documentation
|
||||
- **Example Use Cases** with real workflows
|
||||
- Team Code Standards Plugin (private marketplace)
|
||||
- Security Audit Suite (community plugin)
|
||||
- Accessibility Testing (a11y plugin with WCAG compliance)
|
||||
- **Troubleshooting** guide
|
||||
- Plugin not found after install
|
||||
- Plugin conflicts resolution
|
||||
- Plugin not loading in session
|
||||
- **Keyboard Shortcut: `Esc×2` double-tap** (line 7487)
|
||||
- Added to Section 10.2 Keyboard Shortcuts table
|
||||
- Clarifies double-tap pattern: Rewind to previous checkpoint (same as `/rewind`)
|
||||
- Resolves inconsistency between TL;DR mention and shortcuts table
|
||||
- **Plugin command** in Section 10.1 Commands Table (line 7696)
|
||||
- `/plugin` command: Manage Claude Code plugins (Config category)
|
||||
- **Plugin flag** in Section 10.3 CLI Flags Reference (line 7782)
|
||||
- `--plugin-dir`: Load plugins from directory (repeatable flag)
|
||||
|
||||
### Changed
|
||||
- **Table of Contents updated** (line 147)
|
||||
- Added [8.5 Plugin System](#85-plugin-system) entry
|
||||
- **Section 8 Quick Jump navigation enhanced** (line 4530)
|
||||
- Added Plugin System link to quick navigation bar
|
||||
- **TL;DR Power Features table** (line 80)
|
||||
- Added "Plugins: Community-created extension packages" row
|
||||
- **Version alignment** across documentation
|
||||
- english-ultimate-claude-code-guide.md: Version 2.5 → 2.6
|
||||
- README.md: Version 2.5 → 2.6
|
||||
|
||||
### Stats
|
||||
- Guide expanded from 8,545 to 8,787 lines (+242 lines, +2.8%)
|
||||
- Plugin System section: ~245 lines of comprehensive documentation
|
||||
- 1 keyboard shortcut clarified (Esc×2)
|
||||
- 2 command/flag additions (/plugin, --plugin-dir)
|
||||
- Focus on extensibility and community-driven functionality
|
||||
- Zero loss of existing functionality
|
||||
|
||||
## [2.5.0] - 2026-01-11
|
||||
|
||||
### Removed
|
||||
|
|
|
|||
|
|
@ -1,572 +0,0 @@
|
|||
# Guide Improvement Recommendations
|
||||
|
||||
Based on comprehensive analysis of zebbern/claude-code-guide, here are prioritized recommendations to enhance our Claude Code Ultimate Guide.
|
||||
|
||||
## Priority 1: High-Impact Quick Wins ⚡
|
||||
|
||||
### 1.1 Add Status Overview Table (5 min)
|
||||
|
||||
**What:** Add a visual status table at the top showing section completeness.
|
||||
|
||||
**Where:** Right after the main title, before TOC.
|
||||
|
||||
**Implementation:**
|
||||
```markdown
|
||||
<div align="center">
|
||||
|
||||
| Section | Status | Coverage |
|
||||
|---------|--------|----------|
|
||||
| Installation & Setup | ✅ Complete | 100% |
|
||||
| Core Concepts | ✅ Complete | 100% |
|
||||
| Agents & Skills | ✅ Complete | 100% |
|
||||
| MCP Integration | 🔄 Updating | 95% |
|
||||
| Advanced Patterns | ✅ Complete | 100% |
|
||||
| Troubleshooting | ✅ Complete | 100% |
|
||||
|
||||
</div>
|
||||
```
|
||||
|
||||
**Benefit:** Users immediately see what's covered and maturity level.
|
||||
|
||||
---
|
||||
|
||||
### 1.2 Create One-Page Cheat Sheet (30 min)
|
||||
|
||||
**What:** Ultra-condensed reference for daily use.
|
||||
|
||||
**File:** `cheatsheet-en.md` (already exists but could be enhanced)
|
||||
|
||||
**Format:** Single page with these sections:
|
||||
```markdown
|
||||
## Quick Reference Card
|
||||
|
||||
### Essential Commands
|
||||
claude # Start REPL
|
||||
claude -p "query" # Print mode
|
||||
claude --model sonnet # Model selection
|
||||
claude --think # Extended reasoning
|
||||
|
||||
### Config Management
|
||||
claude config get <key>
|
||||
claude config set <key> <val>
|
||||
claude config add <key> <vals> # For arrays
|
||||
|
||||
### MCP Quick Setup
|
||||
claude mcp add filesystem -s user -- npx -y @modelcontextprotocol/server-filesystem ~/Documents
|
||||
|
||||
### Debugging
|
||||
claude doctor
|
||||
claude --debug
|
||||
claude --verbose
|
||||
|
||||
### Permission Control
|
||||
--allowedTools "Edit,Read,Bash(git:*)"
|
||||
--disallowedTools "WebFetch"
|
||||
```
|
||||
|
||||
**Benefit:** Printable, scannable, perfect for new team members.
|
||||
|
||||
---
|
||||
|
||||
### 1.3 Complete Command Line Flags Table (20 min)
|
||||
|
||||
**What:** Comprehensive reference for all CLI flags.
|
||||
|
||||
**Where:** Section 6 or new appendix.
|
||||
|
||||
**Content:** Based on zebbern's table:
|
||||
| Flag | Description | Example |
|
||||
|------|-------------|---------|
|
||||
| `-p, --print` | Print response and exit | `claude -p "query"` |
|
||||
| `--output-format` | Output format (text/json/stream-json) | `--output-format json` |
|
||||
| `--input-format` | Input format (text/stream-json) | `--input-format stream-json` |
|
||||
| `--replay-user-messages` | Re-emit user messages in stream | `--replay-user-messages` |
|
||||
| `--allowedTools` | Whitelist tools | `--allowedTools "Edit,Read"` |
|
||||
| `--disallowedTools` | Blacklist tools | `--disallowedTools "WebFetch"` |
|
||||
| `--mcp-config` | Load MCP from JSON | `--mcp-config ./mcp.json` |
|
||||
| `--strict-mcp-config` | Only use specified MCP | `--strict-mcp-config` |
|
||||
| `--append-system-prompt` | Add to system prompt | `--append-system-prompt "..."` |
|
||||
| `--permission-mode` | Permission mode | `--permission-mode plan` |
|
||||
| `--model` | Model selection | `--model sonnet` |
|
||||
| `--add-dir` | Additional directories | `--add-dir ../apps ../lib` |
|
||||
| `--continue` | Continue last conversation | `--continue` |
|
||||
| `-r, --resume` | Resume session by ID | `--resume abc123` |
|
||||
| `--dangerously-skip-permissions` | Skip all permissions | `--dangerously-skip-permissions` |
|
||||
|
||||
**Benefit:** Complete reference for power users and automation.
|
||||
|
||||
---
|
||||
|
||||
## Priority 2: Enhanced Troubleshooting 🔧
|
||||
|
||||
### 2.1 MCP Troubleshooting Section Enhancement (45 min)
|
||||
|
||||
**What:** Add common MCP errors and solutions.
|
||||
|
||||
**Where:** Expand section 10.4 "MCP Issues"
|
||||
|
||||
**New subsections:**
|
||||
|
||||
#### Common MCP Errors
|
||||
|
||||
**Error 1: Tool Name Validation Failed**
|
||||
```
|
||||
API Error 400: "tools.11.custom.name: String should match pattern '^[a-zA-Z0-9_-]{1,64}'"
|
||||
```
|
||||
**Solution:**
|
||||
- Server name: only letters, numbers, underscores, hyphens
|
||||
- Max 64 characters
|
||||
- No special characters or spaces
|
||||
|
||||
**Error 2: MCP Server Not Found**
|
||||
```
|
||||
MCP server 'my-server' not found
|
||||
```
|
||||
**Solution:**
|
||||
1. Check scope settings (local/user/project)
|
||||
2. Run `claude mcp list` to verify
|
||||
3. Ensure correct directory for local scope
|
||||
4. Restart Claude Code
|
||||
|
||||
**Error 3: Windows Path Issues**
|
||||
```
|
||||
Error: Cannot find module 'C:UsersusernameDocuments'
|
||||
```
|
||||
**Solution:**
|
||||
```bash
|
||||
# Wrong
|
||||
claude mcp add fs -- npx -y @modelcontextprotocol/server-filesystem C:\Users\username\Documents
|
||||
|
||||
# Correct
|
||||
claude mcp add fs -- npx -y @modelcontextprotocol/server-filesystem C:/Users/username/Documents
|
||||
# or
|
||||
claude mcp add fs -- npx -y @modelcontextprotocol/server-filesystem "C:\\Users\\username\\Documents"
|
||||
```
|
||||
|
||||
#### MCP Debugging Techniques
|
||||
|
||||
**Enable Debug Mode:**
|
||||
```bash
|
||||
claude --mcp-debug
|
||||
```
|
||||
|
||||
**View MCP Status:**
|
||||
```bash
|
||||
/mcp # Inside Claude Code
|
||||
```
|
||||
|
||||
**View Log Files:**
|
||||
```bash
|
||||
# macOS/Linux
|
||||
tail -f ~/Library/Logs/Claude/mcp*.log
|
||||
|
||||
# Windows
|
||||
type "%APPDATA%\Claude\logs\mcp*.log"
|
||||
```
|
||||
|
||||
**Manual Server Test:**
|
||||
```bash
|
||||
# Test if server works standalone
|
||||
npx -y @modelcontextprotocol/server-filesystem ~/Documents
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 2.2 One-Shot Health Check Scripts (15 min)
|
||||
|
||||
**What:** Copy-paste diagnostic scripts.
|
||||
|
||||
**Where:** Section 10 "Help & Troubleshooting"
|
||||
|
||||
**Windows (PowerShell):**
|
||||
```powershell
|
||||
Write-Host "`n=== Node & npm ==="; node --version; npm --version
|
||||
Write-Host "`n=== Where is claude? ==="; where claude
|
||||
Write-Host "`n=== Try doctor ==="; try { claude doctor } catch { Write-Host "claude not on PATH" }
|
||||
Write-Host "`n=== API key set? ==="; if ($env:ANTHROPIC_API_KEY) { "Yes" } else { "No" }
|
||||
Write-Host "`n=== MCP Status ==="; claude mcp list
|
||||
```
|
||||
|
||||
**macOS/Linux (bash/zsh):**
|
||||
```bash
|
||||
echo "=== Node & npm ==="; node --version; npm --version
|
||||
echo "=== Where is claude? ==="; which claude || echo "claude not on PATH"
|
||||
echo "=== Try doctor ==="; claude doctor || true
|
||||
echo "=== API key set? ==="; [ -n "$ANTHROPIC_API_KEY" ] && echo Yes || echo No
|
||||
echo "=== MCP Status ==="; claude mcp list
|
||||
```
|
||||
|
||||
**Benefit:** Instant diagnosis for users reporting issues.
|
||||
|
||||
---
|
||||
|
||||
### 2.3 Full Clean Reinstall Procedures (20 min)
|
||||
|
||||
**What:** Nuclear option for corrupted installations.
|
||||
|
||||
**Where:** Section 10 troubleshooting
|
||||
|
||||
**Windows PowerShell Script:**
|
||||
```powershell
|
||||
# 1. Uninstall
|
||||
npm uninstall -g @anthropic-ai/claude-code
|
||||
|
||||
# 2. Remove shims
|
||||
Remove-Item -LiteralPath "$env:USERPROFILE\AppData\Roaming\npm\claude*" -Force -ErrorAction SilentlyContinue
|
||||
Remove-Item -LiteralPath "$env:USERPROFILE\AppData\Roaming\npm\node_modules\@anthropic-ai\claude-code" -Recurse -Force -ErrorAction SilentlyContinue
|
||||
|
||||
# 3. Delete cache
|
||||
Remove-Item -LiteralPath "$env:USERPROFILE\.claude\downloads\*" -Recurse -Force -ErrorAction SilentlyContinue
|
||||
Remove-Item -LiteralPath "$env:USERPROFILE\.claude\local" -Recurse -Force -ErrorAction SilentlyContinue
|
||||
|
||||
# 4. Remove config (optional - backs up first)
|
||||
Copy-Item "$env:USERPROFILE\.claude.json" "$env:USERPROFILE\.claude.json.backup" -ErrorAction SilentlyContinue
|
||||
Remove-Item -LiteralPath "$env:USERPROFILE\.claude.json" -Force -ErrorAction SilentlyContinue
|
||||
|
||||
# 5. Reinstall
|
||||
npm install -g @anthropic-ai/claude-code
|
||||
```
|
||||
|
||||
**macOS/Linux Script:**
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# 1. Uninstall
|
||||
npm uninstall -g @anthropic-ai/claude-code
|
||||
|
||||
# 2. Remove global bin files
|
||||
rm -f "$(npm config get prefix)/bin/claude"
|
||||
rm -rf "$(npm config get prefix)/lib/node_modules/@anthropic-ai/claude-code"
|
||||
|
||||
# 3. Delete cache
|
||||
rm -rf ~/.claude/downloads/*
|
||||
rm -rf ~/.claude/local
|
||||
|
||||
# 4. Backup and remove config (optional)
|
||||
cp ~/.claude.json ~/.claude.json.backup 2>/dev/null || true
|
||||
rm -f ~/.claude.json
|
||||
|
||||
# 5. Reinstall
|
||||
npm install -g @anthropic-ai/claude-code
|
||||
```
|
||||
|
||||
**Benefit:** Last resort fix for mysterious issues.
|
||||
|
||||
---
|
||||
|
||||
## Priority 3: Format Enhancements 📝
|
||||
|
||||
### 3.1 Add Visual Badges (10 min)
|
||||
|
||||
**What:** Status badges at top of README.
|
||||
|
||||
**Implementation:**
|
||||
```markdown
|
||||
|
||||
|
||||
|
||||
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 3.2 Collapsible Tables for Dense Content (30 min)
|
||||
|
||||
**What:** Use `<details>` tags or tables for long sections.
|
||||
|
||||
**Where:** Troubleshooting, environment variables, MCP server list.
|
||||
|
||||
**Example:**
|
||||
```markdown
|
||||
<details>
|
||||
<summary><b>Environment Variables Reference (click to expand)</b></summary>
|
||||
|
||||
| Variable | Purpose | Example |
|
||||
|----------|---------|---------|
|
||||
| `ANTHROPIC_API_KEY` | API authentication | `sk-ant-...` |
|
||||
| `ANTHROPIC_MODEL` | Default model | `claude-sonnet-4-20250514` |
|
||||
| `BASH_DEFAULT_TIMEOUT_MS` | Bash timeout | `60000` |
|
||||
...
|
||||
|
||||
</details>
|
||||
```
|
||||
|
||||
**Benefit:** Reduces visual clutter while keeping info accessible.
|
||||
|
||||
---
|
||||
|
||||
### 3.3 "C-Style Comment" Format for Multi-Variant Commands (15 min)
|
||||
|
||||
**What:** Visual organization for OS-specific commands.
|
||||
|
||||
**Example:**
|
||||
```C
|
||||
# Quick Start Installation
|
||||
/*──────────────────────────────────────────────────────────────*/
|
||||
/* Universal Method */ npm install -g @anthropic-ai/claude-code
|
||||
/*──────────────────────────────────────────────────────────────*/
|
||||
/* Windows (CMD) */ npm install -g @anthropic-ai/claude-code
|
||||
/* Windows (PowerShell) */ irm https://claude.ai/install.ps1 | iex
|
||||
/*──────────────────────────────────────────────────────────────*/
|
||||
/* macOS */ brew install node && npm install -g @anthropic-ai/claude-code
|
||||
/*──────────────────────────────────────────────────────────────*/
|
||||
/* Linux (Debian/Ubuntu) */ sudo apt update && sudo apt install -y nodejs npm
|
||||
/* */ npm install -g @anthropic-ai/claude-code
|
||||
```
|
||||
|
||||
**Benefit:** Extremely scannable, looks professional.
|
||||
|
||||
---
|
||||
|
||||
## Priority 4: Content Additions 📚
|
||||
|
||||
### 4.1 Security Best Practices - Do/Don't Format (30 min)
|
||||
|
||||
**What:** Clear visual Do/Don't examples.
|
||||
|
||||
**Where:** Section 8 Security
|
||||
|
||||
**Format:**
|
||||
```markdown
|
||||
### Security Pitfalls
|
||||
|
||||
**❌ Don't:**
|
||||
- Use `--dangerously-skip-permissions` on production systems
|
||||
- Hard-code secrets in commands/config files
|
||||
- Grant overly broad permissions (`Bash(*)`)
|
||||
- Run with elevated privileges unnecessarily
|
||||
|
||||
**✅ Do:**
|
||||
- Store secrets in environment variables
|
||||
- Start from minimal permissions and expand gradually
|
||||
- Audit regularly with `claude config list`
|
||||
- Isolate risky operations in containers/VMs
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4.2 Performance Pitfalls Section (20 min)
|
||||
|
||||
**What:** Common performance mistakes.
|
||||
|
||||
**Format:**
|
||||
```markdown
|
||||
### Performance Pitfalls
|
||||
|
||||
**❌ Don't:**
|
||||
- Load entire monorepo when you only need one package
|
||||
- Max out thinking/turn budgets for simple tasks
|
||||
- Ignore session cleanup (old sessions accumulate)
|
||||
- Use `--ultrathink` for trivial edits
|
||||
|
||||
**✅ Do:**
|
||||
- Use `--add-dir` for focused context
|
||||
- Right-size with `--max-turns` and `MAX_THINKING_TOKENS`
|
||||
- Set `cleanupPeriodDays` to prune old sessions
|
||||
- Match thinking level to task complexity
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4.3 Workflow Pitfalls Section (20 min)
|
||||
|
||||
**What:** Common workflow mistakes.
|
||||
|
||||
**Format:**
|
||||
```markdown
|
||||
### Workflow Pitfalls
|
||||
|
||||
**❌ Don't:**
|
||||
- Skip project context (`CLAUDE.md`)
|
||||
- Use vague prompts ("fix this", "check my code")
|
||||
- Ignore errors in logs
|
||||
- Automate workflows without testing first
|
||||
|
||||
**✅ Do:**
|
||||
- Maintain and update `CLAUDE.md` regularly
|
||||
- Be specific and goal-oriented in prompts
|
||||
- Monitor via logs/OpenTelemetry as appropriate
|
||||
- Test automation in safe environments first
|
||||
- Review agent outputs before committing
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4.4 DeepSeek Integration (15 min)
|
||||
|
||||
**What:** Alternative LLM provider integration.
|
||||
|
||||
**Where:** Section 11 "Third-Party Integrations"
|
||||
|
||||
**Content:**
|
||||
```markdown
|
||||
## 11.1 DeepSeek Integration
|
||||
|
||||
Use DeepSeek's Claude-compatible API as a cost-effective alternative.
|
||||
|
||||
### Setup
|
||||
|
||||
1. **Prerequisites:**
|
||||
- Claude Code installed: `npm install -g @anthropic-ai/claude-code`
|
||||
- DeepSeek API key from [platform.deepseek.com](https://platform.deepseek.com)
|
||||
|
||||
2. **Configure Environment:**
|
||||
```bash
|
||||
export ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic
|
||||
export ANTHROPIC_AUTH_TOKEN=${YOUR_DEEPSEEK_API_KEY}
|
||||
export ANTHROPIC_MODEL=deepseek-chat
|
||||
export ANTHROPIC_SMALL_FAST_MODEL=deepseek-chat
|
||||
```
|
||||
|
||||
3. **Launch Claude:**
|
||||
```bash
|
||||
claude
|
||||
```
|
||||
|
||||
### Cost Comparison
|
||||
|
||||
| Provider | Model | Cost per 1M tokens |
|
||||
|----------|-------|-------------------|
|
||||
| Anthropic | Sonnet 4 | ~$3.00 |
|
||||
| DeepSeek | deepseek-chat | ~$0.14 |
|
||||
|
||||
**Savings: ~95% reduction**
|
||||
|
||||
### Limitations
|
||||
|
||||
- DeepSeek models have different capabilities than Claude
|
||||
- Some advanced features may not work identically
|
||||
- Performance/quality trade-offs exist
|
||||
|
||||
### Resources
|
||||
|
||||
- [DeepSeek API Documentation](https://api-docs.deepseek.com/guides/anthropic_api)
|
||||
- [DeepSeek Platform](https://platform.deepseek.com)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Priority 5: Documentation Structure 🏗️
|
||||
|
||||
### 5.1 Add Quick Navigation Links (10 min)
|
||||
|
||||
**What:** Jump links at top of major sections.
|
||||
|
||||
**Example:**
|
||||
```markdown
|
||||
## Section 6: Commands & Usage
|
||||
|
||||
_Quick jump:_ [Slash Commands](#slash-commands) · [CLI Flags](#cli-flags) · [Cheat Sheet](#cheat-sheet) · [Environment Variables](#environment-variables)
|
||||
|
||||
---
|
||||
|
||||
### 6.1 Slash Commands
|
||||
...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 5.2 Appendix: Useful Paths (10 min)
|
||||
|
||||
**What:** Reference for file locations.
|
||||
|
||||
**Content:**
|
||||
```markdown
|
||||
## Appendix A: File Locations Reference
|
||||
|
||||
### Windows
|
||||
- **npm global bin:** `C:\Users\<you>\AppData\Roaming\npm`
|
||||
- **Node.js:** `C:\Program Files\nodejs`
|
||||
- **Claude data:** `C:\Users\<you>\.claude\`
|
||||
- **Claude config:** `C:\Users\<you>\.claude.json`
|
||||
- **Logs:** `%APPDATA%\Claude\logs\`
|
||||
|
||||
### macOS/Linux
|
||||
- **npm global bin:** `$(npm config get prefix)/bin` (often `/usr/local/bin`)
|
||||
- **Claude data:** `~/.claude/`
|
||||
- **Claude config:** `~/.claude.json`
|
||||
- **Logs (macOS):** `~/Library/Logs/Claude/`
|
||||
- **Logs (Linux):** `~/.local/share/claude/logs/`
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Implementation Roadmap
|
||||
|
||||
### Phase 1: Quick Wins (2-3 hours)
|
||||
1. ✅ Add thinking keywords inline syntax
|
||||
2. ✅ Create GitHub Actions examples directory
|
||||
3. Add status overview table
|
||||
4. Create/enhance cheat sheet
|
||||
5. Add CLI flags table
|
||||
6. Add visual badges
|
||||
|
||||
### Phase 2: Troubleshooting (3-4 hours)
|
||||
1. MCP troubleshooting enhancement
|
||||
2. One-shot health check scripts
|
||||
3. Full clean reinstall procedures
|
||||
4. Appendix: useful paths
|
||||
|
||||
### Phase 3: Content Enrichment (4-5 hours)
|
||||
1. Security pitfalls Do/Don't
|
||||
2. Performance pitfalls
|
||||
3. Workflow pitfalls
|
||||
4. DeepSeek integration
|
||||
5. Collapsible tables for dense content
|
||||
|
||||
### Phase 4: Format Polish (2-3 hours)
|
||||
1. C-style comment format for commands
|
||||
2. Quick navigation links
|
||||
3. Consistent emoji hierarchy
|
||||
4. Table of contents update
|
||||
|
||||
---
|
||||
|
||||
## Metrics for Success
|
||||
|
||||
### User Experience
|
||||
- **Time to first success:** < 15 minutes (installation → first task)
|
||||
- **Time to find answer:** < 2 minutes (via cheat sheet or quick links)
|
||||
- **Support ticket reduction:** Target 30% reduction via better troubleshooting
|
||||
|
||||
### Content Quality
|
||||
- **Coverage:** 100% of official features documented
|
||||
- **Accuracy:** < 1% error rate in commands/examples
|
||||
- **Freshness:** Updated within 7 days of new Claude Code releases
|
||||
|
||||
### Community Engagement
|
||||
- **GitHub Stars:** Track growth trend
|
||||
- **Issues/PRs:** Measure community contributions
|
||||
- **Fork activity:** Indicates usage/adaptation
|
||||
|
||||
---
|
||||
|
||||
## What NOT to Change
|
||||
|
||||
**Keep these strengths from our guide:**
|
||||
|
||||
1. **Learning Path Structure** - Junior → Senior → Power User progression
|
||||
2. **Trinity Pattern** - Unique advanced workflow
|
||||
3. **OpusPlan Mode** - Cost optimization strategy
|
||||
4. **Context Management Zones** - Clear guidance on usage levels
|
||||
5. **Maturity Model** - 5-level progression framework
|
||||
6. **Agent-Based Task Delegation** - Advanced orchestration
|
||||
7. **Skill Inheritance Model** - Reusable expertise
|
||||
8. **Git Archaeology Pattern** - Unique debugging approach
|
||||
9. **Narrative Style** - Pedagogical, not just reference
|
||||
10. **Real-world Examples** - Production scenarios, not toy examples
|
||||
|
||||
---
|
||||
|
||||
## Conclusion
|
||||
|
||||
These recommendations balance:
|
||||
- **Immediate impact** (quick wins) with **long-term value** (structural improvements)
|
||||
- **Reference utility** (cheat sheets, tables) with **learning journey** (narrative)
|
||||
- **Completeness** (troubleshooting) with **scannability** (collapsible sections)
|
||||
|
||||
**Core Philosophy:**
|
||||
> zebbern's guide = comprehensive reference
|
||||
> our guide = mastery journey
|
||||
> **enhanced guide = both**
|
||||
|
||||
By selectively adopting zebbern's strengths while preserving our unique pedagogical approach, we create the definitive Claude Code resource.
|
||||
|
|
@ -10,6 +10,7 @@
|
|||
|
||||
[](https://creativecommons.org/licenses/by-sa/4.0/)
|
||||
[](https://github.com/FlorianBruniaux/claude-code-ultimate-guide/stargazers)
|
||||
[](https://zread.ai/FlorianBruniaux/claude-code-ultimate-guide)
|
||||
|
||||
**Author**: [Florian BRUNIAUX](https://github.com/FlorianBruniaux) | Founding Engineer [@Méthode Aristote](https://methode-aristote.fr)
|
||||
|
||||
|
|
@ -288,7 +289,7 @@ Want to know if your Claude Code setup follows best practices?
|
|||
- [DeepTo Claude Code Guide](https://cc.deeptoai.com/docs/en/best-practices/claude-code-comprehensive-guide) — Comprehensive best practices covering XML-structured prompts, session continuation, image processing, Unix piping workflows, and cost tracking (ccusage tool)
|
||||
|
||||
### Community Curated Lists
|
||||
- [awesome-claude-code](https://github.com/hesreallyhim/awesome-claude-code) — Commands, workflows, IDE integrations
|
||||
- [awesome-claude-code](https://github.com/hesreallyhim/awesome-claude-code) — Extensive reference library (19.9k stars) covering commands, workflows, hooks, IDE integrations, and monitoring tools. **Note**: This is a curated collection for discovering solutions, not an architectural guide—it lists tools without guidance on how to combine them intelligently or which to choose based on specific needs
|
||||
- [awesome-claude-skills](https://github.com/ComposioHQ/awesome-claude-skills) — Custom skills collection
|
||||
- [awesome-claude-code-subagents](https://github.com/VoltAgent/awesome-claude-code-subagents) — Full-stack & DevOps subagents
|
||||
- [awesome-claude](https://github.com/alvinunreal/awesome-claude) — General Claude resources (SDKs, tools)
|
||||
|
|
@ -320,4 +321,4 @@ You are free to share and adapt this material, provided you give appropriate cre
|
|||
|
||||
---
|
||||
|
||||
*Last updated: January 2026 | Version 2.5*
|
||||
*Last updated: January 2026 | Version 2.6*
|
||||
|
|
@ -10,7 +10,7 @@
|
|||
|
||||
**Last updated**: January 2026
|
||||
|
||||
**Version**: 2.5
|
||||
**Version**: 2.6
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -77,6 +77,7 @@ Describe → Claude Analyzes → Review Diff → Accept/Reject → Verify
|
|||
| **Skills** | Reusable knowledge modules |
|
||||
| **Hooks** | Automation scripts triggered by events |
|
||||
| **MCP Servers** | External tools (Serena, Context7, Playwright...) |
|
||||
| **Plugins** | Community-created extension packages |
|
||||
|
||||
### The Golden Rules
|
||||
1. **Always review diffs** before accepting changes
|
||||
|
|
@ -144,6 +145,7 @@ Context full → /compact or /clear
|
|||
- [8.2 Available Servers](#82-available-servers)
|
||||
- [8.3 Configuration](#83-configuration)
|
||||
- [8.4 Server Selection Guide](#84-server-selection-guide)
|
||||
- [8.5 Plugin System](#85-plugin-system)
|
||||
- [9. Advanced Patterns](#9-advanced-patterns)
|
||||
- [9.1 The Trinity](#91-the-trinity)
|
||||
- [9.2 Composition Patterns](#92-composition-patterns)
|
||||
|
|
@ -4526,7 +4528,7 @@ exit 0
|
|||
|
||||
# 8. MCP Servers
|
||||
|
||||
_Quick jump:_ [What is MCP](#81-what-is-mcp) · [Available Servers](#82-available-servers) · [Configuration](#83-configuration) · [Server Selection Guide](#84-server-selection-guide)
|
||||
_Quick jump:_ [What is MCP](#81-what-is-mcp) · [Available Servers](#82-available-servers) · [Configuration](#83-configuration) · [Server Selection Guide](#84-server-selection-guide) · [Plugin System](#85-plugin-system)
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -4833,6 +4835,243 @@ Servers can work together:
|
|||
4. Playwright → Test the implementation
|
||||
```
|
||||
|
||||
## 8.5 Plugin System
|
||||
|
||||
Claude Code includes a comprehensive **plugin system** that allows you to extend functionality through community-created or custom plugins and marketplaces.
|
||||
|
||||
### What Are Plugins?
|
||||
|
||||
Plugins are packaged extensions that can add:
|
||||
- Custom agents with specialized behavior
|
||||
- New skills for reusable workflows
|
||||
- Pre-configured commands
|
||||
- Domain-specific tooling
|
||||
|
||||
Think of plugins as **distributable packages** that bundle agents, skills, and configuration into installable modules.
|
||||
|
||||
### Plugin Commands
|
||||
|
||||
| Command | Purpose | Example |
|
||||
|---------|---------|---------|
|
||||
| `claude plugin` | List installed plugins | Shows all plugins with status |
|
||||
| `claude plugin install <name>` | Install plugin from marketplace | `claude plugin install security-audit` |
|
||||
| `claude plugin install <name>@<marketplace>` | Install from specific marketplace | `claude plugin install linter@company` |
|
||||
| `claude plugin enable <name>` | Enable installed plugin | `claude plugin enable security-audit` |
|
||||
| `claude plugin disable <name>` | Disable plugin without removing | `claude plugin disable linter` |
|
||||
| `claude plugin uninstall <name>` | Remove plugin completely | `claude plugin uninstall security-audit` |
|
||||
| `claude plugin update [name]` | Update plugin to latest version | `claude plugin update security-audit` |
|
||||
| `claude plugin validate <path>` | Validate plugin manifest | `claude plugin validate ./my-plugin` |
|
||||
|
||||
### Marketplace Management
|
||||
|
||||
Marketplaces are repositories of plugins you can install from.
|
||||
|
||||
**Marketplace commands:**
|
||||
|
||||
```bash
|
||||
# Add a marketplace
|
||||
claude plugin marketplace add <url-or-path>
|
||||
|
||||
# Examples:
|
||||
claude plugin marketplace add https://github.com/claudecode/plugins
|
||||
claude plugin marketplace add /Users/yourname/company-plugins
|
||||
claude plugin marketplace add gh:myorg/claude-plugins # GitHub shorthand
|
||||
|
||||
# List configured marketplaces
|
||||
claude plugin marketplace list
|
||||
|
||||
# Update marketplace catalog
|
||||
claude plugin marketplace update [name]
|
||||
|
||||
# Remove a marketplace
|
||||
claude plugin marketplace remove <name>
|
||||
```
|
||||
|
||||
### Using Plugins
|
||||
|
||||
**Typical workflow:**
|
||||
|
||||
```bash
|
||||
# 1. Add a marketplace (one-time setup)
|
||||
claude plugin marketplace add https://github.com/awesome-claude/plugins
|
||||
|
||||
# 2. Install a plugin
|
||||
claude plugin install code-reviewer
|
||||
|
||||
# 3. Enable it for your project
|
||||
claude plugin enable code-reviewer
|
||||
|
||||
# 4. Use it in Claude Code session
|
||||
claude
|
||||
You: /review-pr
|
||||
# Plugin command is now available
|
||||
```
|
||||
|
||||
### Plugin Session Loading
|
||||
|
||||
Load plugins temporarily for a single session:
|
||||
|
||||
```bash
|
||||
# Load plugin directory for this session only
|
||||
claude --plugin-dir ~/.claude/custom-plugins
|
||||
|
||||
# Load multiple plugin directories
|
||||
claude --plugin-dir ~/work/plugins --plugin-dir ~/personal/plugins
|
||||
```
|
||||
|
||||
This is useful for testing plugins before permanent installation.
|
||||
|
||||
### When to Use Plugins
|
||||
|
||||
| Scenario | Use Plugins |
|
||||
|----------|-------------|
|
||||
| **Team workflows** | ✅ Share standardized agents/skills across team via private marketplace |
|
||||
| **Domain expertise** | ✅ Install pre-built plugins for security, accessibility, performance analysis |
|
||||
| **Repeating patterns** | ✅ Package your custom workflows for reuse across projects |
|
||||
| **Community solutions** | ✅ Leverage community expertise instead of rebuilding from scratch |
|
||||
| **Quick experiments** | ❌ Use custom agents/skills directly in `.claude/` folder |
|
||||
| **Project-specific** | ❌ Keep as project CLAUDE.md instructions instead |
|
||||
|
||||
### Creating Custom Plugins
|
||||
|
||||
Plugins are structured directories with a manifest:
|
||||
|
||||
```
|
||||
my-plugin/
|
||||
├── plugin.json # Plugin manifest
|
||||
├── agents/
|
||||
│ └── my-agent.md # Custom agents
|
||||
├── skills/
|
||||
│ └── my-skill.md # Custom skills
|
||||
├── commands/
|
||||
│ └── my-cmd.sh # Custom commands
|
||||
└── README.md # Documentation
|
||||
```
|
||||
|
||||
**Example `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"]
|
||||
}
|
||||
```
|
||||
|
||||
**Validate before distribution:**
|
||||
|
||||
```bash
|
||||
claude plugin validate ./my-plugin
|
||||
```
|
||||
|
||||
### Plugin vs. MCP Server
|
||||
|
||||
Understanding when to use which:
|
||||
|
||||
| Feature | Plugin | MCP Server |
|
||||
|---------|--------|------------|
|
||||
| **Purpose** | Bundle Claude-specific workflows (agents, skills) | Add external tool capabilities (databases, APIs) |
|
||||
| **Complexity** | Simpler - just files + manifest | More complex - requires server implementation |
|
||||
| **Scope** | Claude Code instructions and patterns | External system integrations |
|
||||
| **Installation** | `claude plugin install` | Add to `settings.json` MCP config |
|
||||
| **Use case** | Security auditor agent, code review workflows | PostgreSQL access, Playwright browser automation |
|
||||
|
||||
**Rule of thumb:**
|
||||
- **Plugin** = "How Claude thinks" (new workflows, specialized agents)
|
||||
- **MCP Server** = "What Claude can do" (new tools, external systems)
|
||||
|
||||
### Security Considerations
|
||||
|
||||
**Before installing plugins:**
|
||||
|
||||
1. **Trust the source** - Only install from verified marketplaces
|
||||
2. **Review manifest** - Check what the plugin includes with `validate`
|
||||
3. **Test in isolation** - Use `--plugin-dir` for testing before permanent install
|
||||
4. **Company policies** - Check if your organization has approved plugin sources
|
||||
|
||||
**Red flags:**
|
||||
|
||||
- Plugins requesting network access without clear reason
|
||||
- Unclear or obfuscated code in agents/skills
|
||||
- Plugins without documentation or proper manifest
|
||||
|
||||
### Example Use Cases
|
||||
|
||||
**1. Team Code Standards Plugin**
|
||||
|
||||
```bash
|
||||
# Company creates private marketplace
|
||||
git clone git@github.com:yourcompany/claude-plugins.git ~/company-plugins
|
||||
|
||||
# Add marketplace
|
||||
claude plugin marketplace add ~/company-plugins
|
||||
|
||||
# Install company standards
|
||||
claude plugin install code-standards@company
|
||||
|
||||
# Now all team members use same linting, review patterns
|
||||
```
|
||||
|
||||
**2. Security Audit Suite**
|
||||
|
||||
```bash
|
||||
# Install community security plugin
|
||||
claude plugin install owasp-scanner
|
||||
|
||||
# Use in session
|
||||
claude
|
||||
You: /security-scan
|
||||
# Runs OWASP Top 10 checks, dependency audit, secret scanning
|
||||
```
|
||||
|
||||
**3. Accessibility Testing**
|
||||
|
||||
```bash
|
||||
# Install a11y plugin
|
||||
claude plugin install wcag-checker
|
||||
|
||||
# Enable for project
|
||||
claude plugin enable wcag-checker
|
||||
|
||||
# Adds accessibility-focused agents
|
||||
You: Review this component for WCAG 2.1 compliance
|
||||
```
|
||||
|
||||
### Troubleshooting
|
||||
|
||||
**Plugin not found after install:**
|
||||
|
||||
```bash
|
||||
# Refresh marketplace catalogs
|
||||
claude plugin marketplace update
|
||||
|
||||
# Verify plugin is installed
|
||||
claude plugin
|
||||
|
||||
# Check if disabled
|
||||
claude plugin enable <name>
|
||||
```
|
||||
|
||||
**Plugin conflicts:**
|
||||
|
||||
```bash
|
||||
# Disable conflicting plugin
|
||||
claude plugin disable <conflicting-plugin>
|
||||
|
||||
# Or uninstall completely
|
||||
claude plugin uninstall <conflicting-plugin>
|
||||
```
|
||||
|
||||
**Plugin not loading in session:**
|
||||
|
||||
- Plugins are loaded at session start
|
||||
- Restart Claude Code after enabling/disabling
|
||||
- Check `~/.claude/plugins/` for installation
|
||||
|
||||
---
|
||||
|
||||
# 9. Advanced Patterns
|
||||
|
|
@ -7454,6 +7693,7 @@ _Quick jump:_ [Commands Table](#101-commands-table) · [Keyboard Shortcuts](#102
|
|||
| `/stats` | View usage statistics with activity graphs | Info |
|
||||
| `/chrome` | Toggle native browser integration | Mode |
|
||||
| `/mcp` | Manage Model Context Protocol servers | Config |
|
||||
| `/plugin` | Manage Claude Code plugins | Config |
|
||||
| `/plan` | Enter Plan Mode | Mode |
|
||||
| `/execute` | Exit Plan Mode | Mode |
|
||||
| `/rewind` | Undo recent changes | Edit |
|
||||
|
|
@ -7484,6 +7724,7 @@ _Quick jump:_ [Commands Table](#101-commands-table) · [Keyboard Shortcuts](#102
|
|||
| `Ctrl+L` | Clear screen (keeps context) |
|
||||
| `Ctrl+B` | Run command in background |
|
||||
| `Esc` | Dismiss current suggestion |
|
||||
| `Esc×2` (double-tap) | Rewind to previous checkpoint (same as `/rewind`) |
|
||||
|
||||
### Input & Navigation
|
||||
|
||||
|
|
@ -7538,6 +7779,7 @@ Complete reference for all Claude Code command-line flags.
|
|||
| `--disallowedTools` | Blacklist specific tools | `claude --disallowedTools "WebFetch"` |
|
||||
| `--mcp-config` | Load MCP servers from JSON file | `claude --mcp-config ./mcp.json` |
|
||||
| `--strict-mcp-config` | Only use MCP servers from config | `claude --strict-mcp-config` |
|
||||
| `--plugin-dir` | Load plugins from directory (repeatable) | `claude --plugin-dir ~/.claude/plugins` |
|
||||
| `--append-system-prompt` | Add to system prompt | `claude --append-system-prompt "Use TypeScript"` |
|
||||
| `--permission-mode` | Permission mode (default/auto/plan) | `claude --permission-mode plan` |
|
||||
| `--model` | Model selection | `claude --model sonnet` |
|
||||
|
|
@ -8542,4 +8784,4 @@ Thumbs.db
|
|||
|
||||
**Contributions**: Issues and PRs welcome.
|
||||
|
||||
**Last updated**: January 2026 | **Version**: 2.5
|
||||
**Last updated**: January 2026 | **Version**: 2.6
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue