refactor: Reorganize repository structure for optimal learning path

Reorder folders based on learning dependencies, complexity, and frequency of use:
- 01-slash-commands (unchanged) - Quick wins for beginners
- 02-memory (was 03) - Essential foundation
- 03-skills (was 05) - Auto-invoked capabilities
- 04-subagents (was 02) - Task delegation
- 05-mcp (was 04) - External integration
- 06-hooks (was 07) - Event automation
- 07-plugins (was 06) - Bundled solutions
- 08-checkpoints (unchanged) - Safe experimentation
- 09-advanced-features (unchanged) - Power user tools

Documentation improvements:
- Add LEARNING-ROADMAP.md with detailed milestones and exercises
- Simplify README.md for better scannability
- Consolidate Quick Start and Getting Started sections
- Combine Feature Comparison and Use Case Matrix tables
- Reorder README sections: Learning Path → Quick Reference → Getting Started
- Update all cross-references across module READMEs

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

01-slash-commands/README.md

@@ -404,10 +404,10 @@ Access with: `/deploy/production`, `/test/unit`, `/docs/api`
 
 ## Related Concepts
 
-- **[Subagents](../02-subagents/)** - For complex, delegated tasks
-- **[Memory](../03-memory/)** - For persistent context
-- **[Skills](../05-skills/)** - For auto-invoked capabilities
-- **[Plugins](../06-plugins/)** - For bundled command collections
+- **[Memory](../02-memory/)** - For persistent context
+- **[Skills](../03-skills/)** - For auto-invoked capabilities
+- **[Subagents](../04-subagents/)** - For complex, delegated tasks
+- **[Plugins](../07-plugins/)** - For bundled command collections
 
 ## Resources
 

02-memory/README.md

@@ -533,9 +533,9 @@ graph LR
 - [Memory Hierarchy](./examples/)
 
 ### Integration Points
-- [MCP Protocol](../04-mcp/) - Live data access alongside memory
-- [Slash Commands](../02-slash-commands/) - Session-specific shortcuts
-- [Skills](../05-skills/) - Automated workflows with memory context
+- [MCP Protocol](../05-mcp/) - Live data access alongside memory
+- [Slash Commands](../01-slash-commands/) - Session-specific shortcuts
+- [Skills](../03-skills/) - Automated workflows with memory context
 
 ### Best Practices
 - [Code Organization](./examples/)

03-skills/README.md

@@ -615,7 +615,7 @@ const users = fetchUsersWithPosts(); // 1 query
 
 **File:** `.claude/skills/brand-voice/SKILL.md`
 
-```yaml
+```md
 ---
 name: Brand Voice Consistency
 description: Ensure all communication matches brand voice and tone guidelines
@@ -681,7 +681,6 @@ Help teams automate their development workflows with AI
 - "Leverage" (corporate-speak)
 - "Utilize" (use "use")
 - "Paradigm shift" (unclear)
-```
 
 **Good Example:**
 "Claude automates your code review process. Instead of manually checking each PR, Claude reviews security, performance, and quality—saving your team hours every week."
@@ -693,6 +692,8 @@ Why it works: Clear value, specific benefits, action-oriented
 
 Why it doesn't work: Vague, corporate jargon, no specific value
 
+```
+
 **Template:** `email-template.txt`
 
 ```
@@ -741,7 +742,7 @@ Educational blog post:
 
 **File:** `.claude/skills/doc-generator/SKILL.md`
 
-```yaml
+```md
 ---
 name: API Documentation Generator
 description: Generate comprehensive, accurate API documentation from source code
@@ -767,8 +768,7 @@ when_to_use: When creating or updating API documentation
 ## Documentation Structure
 
 ### For Each Endpoint
-
-```markdown
+<document>
 ## GET /api/v1/users/:id
 
 ### Description
@@ -781,50 +781,41 @@ Brief explanation of what this endpoint does
 | id | string | Yes | User ID |
 
 ### Response
-
 **200 Success**
-```json
+
 {
   "id": "usr_123",
   "name": "John Doe",
   "email": "john@example.com",
   "created_at": "2025-01-15T10:30:00Z"
 }
-```
 
 **404 Not Found**
-```json
+
 {
   "error": "USER_NOT_FOUND",
   "message": "User does not exist"
 }
-```
 
 ### Examples
 
 **cURL**
-```bash
 curl -X GET "https://api.example.com/api/v1/users/usr_123" \
   -H "Authorization: Bearer YOUR_TOKEN"
-```
 
 **JavaScript**
-```javascript
 const user = await fetch('/api/v1/users/usr_123', {
   headers: { 'Authorization': 'Bearer token' }
 }).then(r => r.json());
-```
 
 **Python**
-```python
 response = requests.get(
     'https://api.example.com/api/v1/users/usr_123',
     headers={'Authorization': 'Bearer token'}
 )
 user = response.json()
+</document>
 ```
-```
-
 **Python Script:** `.claude/skills/doc-generator/scripts/generate-docs.py`
 
 ```python

04-subagents/README.md

@@ -719,10 +719,10 @@ Main Agent receives: "Build a new authentication feature"
 ### Related Features
 
 - **[Slash Commands](../01-slash-commands/)** - Quick user-invoked shortcuts
-- **[Memory](../03-memory/)** - Persistent cross-session context
-- **[MCP Protocol](../04-mcp-protocol/)** - Real-time external data access
-- **[Agent Skills](../05-agent-skills/)** - Reusable autonomous capabilities
-- **[Plugins](../06-plugins/)** - Bundled extension packages
+- **[Memory](../02-memory/)** - Persistent cross-session context
+- **[MCP Protocol](../05-mcp/)** - Real-time external data access
+- **[Skills](../03-skills/)** - Reusable autonomous capabilities
+- **[Plugins](../07-plugins/)** - Bundled extension packages
 
 ### Comparison with Other Features
 
@@ -803,8 +803,8 @@ Subagent provides:
 
 - [Claude Code Documentation](https://docs.claude.com/en/docs/claude-code/overview)
 - [Subagents in Claude Concepts Guide](../claude_concepts_guide.md#subagents)
-- [Agent Skills Guide](../05-agent-skills/)
-- [Memory and Context](../03-memory/)
+- [Skills Guide](../03-skills/)
+- [Memory and Context](../02-memory/)
 
 ---
 

06-hooks/README.md

@@ -398,7 +398,7 @@ See the example files in this directory:
 
 For more information on related Claude Code features, see:
 - **[Checkpoints and Rewind](../08-checkpoints/)** - Save and restore conversation state
-- **[Custom Commands](../06-commands/)** - Create custom slash commands
-- **[Settings Configuration](../settings/)** - Configure Claude Code behavior
-- **[Advanced Features](../advanced-features/)** - Explore advanced Claude Code capabilities
+- **[Slash Commands](../01-slash-commands/)** - Create custom slash commands
+- **[Plugins](../07-plugins/)** - Bundled extension packages
+- **[Advanced Features](../09-advanced-features/)** - Explore advanced Claude Code capabilities
 - **[Main Concepts Guide](../claude_concepts_guide.md)** - Complete reference documentation

07-plugins/README.md

@@ -526,11 +526,11 @@ Complete PR review workflow with security, testing, and documentation checks.
 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
+- **[Memory](../02-memory/)** - Persistent context for plugins
+- **[Skills](../03-skills/)** - Domain expertise that can be wrapped into plugins
+- **[Subagents](../04-subagents/)** - Specialized agents included as plugin components
+- **[MCP Servers](../05-mcp/)** - Model Context Protocol integrations bundled in plugins
+- **[Hooks](../06-hooks/)** - Event handlers that trigger plugin workflows
 
 ## Complete Example Workflow
 
@@ -592,5 +592,5 @@ The following Claude Code features work together with 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)
+- [Subagent Configuration Guide](../04-subagents/README.md)
+- [Hook System Reference](../06-hooks/README.md)

08-checkpoints/README.md

@@ -461,12 +461,11 @@ Use both together:
 
 ## Related Concepts
 
-- **[Planning Mode](../07-planning/)** - Create detailed implementation plans before coding
-- **[Memory Management](../06-memory/)** - Managing conversation history and context
-- **[Code Navigation](../05-code-navigation/)** - Understanding and navigating your codebase
-- **[Real-time Collaboration](../09-collaboration/)** - Working with teams using Claude Code
-- **[Error Handling](../10-error-handling/)** - Handling and recovering from errors
-- **[Best Practices](../11-best-practices/)** - General best practices for Claude Code usage
+- **[Advanced Features](../09-advanced-features/)** - Planning mode and other advanced capabilities
+- **[Memory Management](../02-memory/)** - Managing conversation history and context
+- **[Slash Commands](../01-slash-commands/)** - User-invoked shortcuts
+- **[Hooks](../06-hooks/)** - Event-driven automation
+- **[Plugins](../07-plugins/)** - Bundled extension packages
 
 ## Summary
 

09-advanced-features/README.md

@@ -1038,9 +1038,13 @@ Create `.claude/config.json` in your project:
 For more information about Claude Code and related features, see:
 
 - [Main Claude Code Guide](../README.md)
-- [Claude Code Basics](../01-basics/)
-- [Advanced Code Analysis](../02-code-analysis/)
-- [Collaboration Features](../03-collaboration/)
-- [Troubleshooting Guide](../troubleshooting.md)
+- [Slash Commands](../01-slash-commands/)
+- [Memory](../02-memory/)
+- [Skills](../03-skills/)
+- [Subagents](../04-subagents/)
+- [MCP](../05-mcp/)
+- [Hooks](../06-hooks/)
+- [Plugins](../07-plugins/)
+- [Checkpoints](../08-checkpoints/)
 - [Claude Documentation](https://docs.claude.com)
 - [MCP GitHub Servers](https://github.com/modelcontextprotocol/servers)

LEARNING-ROADMAP.md

@@ -0,0 +1,468 @@
+![Claude How To](claude-howto-logo.svg)
+
+# 📚 Claude Code Learning Roadmap
+
+**New to Claude Code?** This comprehensive guide will help you master Claude Code features progressively, starting with the simplest and most frequently used capabilities.
+
+---
+
+## 🎯 Learning Philosophy
+
+The folders in this repository are numbered in **recommended learning order** based on three key principles:
+
+1. **Dependencies** - Foundational concepts come first
+2. **Complexity** - Easier features before advanced ones
+3. **Frequency of Use** - Most common features taught early
+
+This approach ensures you build a solid foundation while gaining immediate productivity benefits.
+
+---
+
+## 🗺️ Your Learning Path
+
+```mermaid
+graph TD
+    A[1. Slash Commands<br/>⭐ START HERE] --> B[2. Memory<br/>Essential Foundation]
+    B --> C[3. Skills<br/>Auto-invoked Capabilities]
+    C --> D[4. Subagents<br/>Task Delegation]
+    D --> E[5. MCP<br/>External Integration]
+    E --> F[6. Hooks<br/>Event Automation]
+    F --> G[7. Plugins<br/>Bundled Solutions]
+    G --> H[8. Checkpoints<br/>Safe Experimentation]
+    H --> I[9. Advanced Features<br/>Power User Tools]
+
+    style A fill:#90EE90
+    style B fill:#87CEEB
+    style C fill:#87CEEB
+    style D fill:#FFD700
+    style E fill:#FFD700
+    style F fill:#FFA500
+    style G fill:#FF6347
+    style H fill:#FF6347
+    style I fill:#8B0000,color:#fff
+```
+
+**Color Legend:**
+- 🟢 Green: Beginner - Start here!
+- 🔵 Light Blue: Beginner+ - Essential foundations
+- 🟡 Gold: Intermediate - Common usage
+- 🟠 Orange: Intermediate-Advanced - Specialized
+- 🔴 Red: Advanced - Power user features
+- 🔴 Dark Red: Most Advanced - Expert territory
+
+---
+
+## 📊 Complete Roadmap Table
+
+| Step | Feature | Complexity | Time | Dependencies | Why Learn This | Key Benefits |
+|------|---------|-----------|------|--------------|----------------|--------------|
+| **1** | [Slash Commands](01-slash-commands/) | ⭐ Beginner | 30 min | None | Quick productivity wins | Instant automation, team standards |
+| **2** | [Memory](02-memory/) | ⭐⭐ Beginner+ | 45 min | None | Essential for all features | Persistent context, preferences |
+| **3** | [Skills](03-skills/) | ⭐⭐ Intermediate | 1 hour | Slash Commands | Automatic expertise | Reusable capabilities, consistency |
+| **4** | [Subagents](04-subagents/) | ⭐⭐⭐ Intermediate+ | 1.5 hours | Memory, Commands | Complex task handling | Delegation, specialized expertise |
+| **5** | [MCP](05-mcp/) | ⭐⭐⭐ Intermediate+ | 1 hour | Configuration | Live data access | Real-time integration, APIs |
+| **6** | [Hooks](06-hooks/) | ⭐⭐ Intermediate | 1 hour | Tools, Commands | Workflow automation | Validation, quality gates |
+| **7** | [Plugins](07-plugins/) | ⭐⭐⭐⭐ Advanced | 2 hours | All previous | Complete solutions | Team onboarding, distribution |
+| **8** | [Checkpoints](08-checkpoints/) | ⭐⭐ Intermediate | 45 min | Session management | Safe exploration | Experimentation, recovery |
+| **9** | [Advanced Features](09-advanced-features/) | ⭐⭐⭐⭐⭐ Advanced | 2-3 hours | All previous | Power user tools | Planning, headless, permissions |
+
+**Total Learning Time**: ~10-12 hours (spread across 4-5 weeks recommended)
+
+---
+
+## 🎯 Learning Milestones
+
+### Milestone 1: Essential Productivity (Week 1)
+
+**Topics**: Slash Commands + Memory
+**Time**: 1-2 hours
+**Complexity**: ⭐ Beginner
+**Goal**: Immediate productivity boost with custom commands and persistent context
+
+#### What You'll Achieve
+✅ Create custom slash commands for repetitive tasks
+✅ Set up project memory for team standards
+✅ Configure personal preferences
+✅ Understand how Claude loads context automatically
+
+#### Hands-on Exercises
+
+```bash
+# Exercise 1: Install your first slash command
+mkdir -p .claude/commands
+cp 01-slash-commands/optimize.md .claude/commands/
+
+# Exercise 2: Create project memory
+cp 02-memory/project-CLAUDE.md ./CLAUDE.md
+
+# Exercise 3: Try it out
+# In Claude Code, type: /optimize
+```
+
+#### Success Criteria
+- [ ] Successfully invoke `/optimize` command
+- [ ] Claude remembers your project standards from CLAUDE.md
+- [ ] You understand when to use slash commands vs. memory
+
+#### Next Steps
+Once comfortable, read:
+- [01-slash-commands/README.md](01-slash-commands/README.md)
+- [02-memory/README.md](02-memory/README.md)
+
+---
+
+### Milestone 2: Automation (Week 2)
+
+**Topics**: Skills + Hooks
+**Time**: 2-3 hours
+**Complexity**: ⭐⭐ Intermediate
+**Goal**: Automate common workflows and quality checks
+
+#### What You'll Achieve
+✅ Auto-invoke specialized capabilities
+✅ Set up event-driven automation
+✅ Enforce code quality standards
+✅ Create custom hooks for your workflow
+
+#### Hands-on Exercises
+
+```bash
+# Exercise 1: Install a skill
+cp -r 03-skills/code-review ~/.claude/skills/
+
+# Exercise 2: Set up hooks
+mkdir -p ~/.claude/hooks
+cp 06-hooks/pre-commit.sh ~/.claude/hooks/
+chmod +x ~/.claude/hooks/pre-commit.sh
+
+# Exercise 3: Configure hooks in settings
+# Add to ~/.claude/config.json:
+{
+  "hooks": {
+    "PreCommit": "~/.claude/hooks/pre-commit.sh"
+  }
+}
+```
+
+#### Success Criteria
+- [ ] Code review skill automatically invoked when relevant
+- [ ] Pre-commit hook runs before git commits
+- [ ] You understand skill auto-invocation vs. hook triggers
+
+#### Next Steps
+- Create your own custom skill
+- Set up additional hooks for your workflow
+- Read: [03-skills/README.md](03-skills/README.md)
+- Read: [06-hooks/README.md](06-hooks/README.md)
+
+---
+
+### Milestone 3: Advanced Integration (Week 3-4)
+
+**Topics**: Subagents + MCP + Plugins
+**Time**: 4-5 hours
+**Complexity**: ⭐⭐⭐ Intermediate-Advanced
+**Goal**: Integrate external services and delegate complex tasks
+
+#### What You'll Achieve
+✅ Delegate work to specialized AI agents
+✅ Access live data from GitHub, databases, etc.
+✅ Install complete bundled solutions
+✅ Understand when to use each integration type
+
+#### Hands-on Exercises
+
+```bash
+# Exercise 1: Set up GitHub MCP
+export GITHUB_TOKEN="your_github_token"
+cp 05-mcp/github-mcp.json ~/.claude/mcp.json
+
+# Exercise 2: Test MCP integration
+# In Claude Code: /mcp__github__list_prs
+
+# Exercise 3: Install subagents
+mkdir -p .claude/agents
+cp 04-subagents/*.md .claude/agents/
+
+# Exercise 4: Install a complete plugin
+# In Claude Code: /plugin install pr-review
+```
+
+#### Success Criteria
+- [ ] Successfully query GitHub data via MCP
+- [ ] Claude delegates complex tasks to subagents
+- [ ] You've installed and used a plugin
+- [ ] You understand the difference between MCP, subagents, and plugins
+
+#### Integration Exercise
+Try this complete workflow:
+1. Use MCP to fetch a GitHub PR
+2. Let Claude delegate review to code-reviewer subagent
+3. Use hooks to run tests automatically
+4. See how the plugin bundles everything together
+
+#### Next Steps
+- Set up additional MCP servers (database, Slack, etc.)
+- Create custom subagents for your domain
+- Read: [04-subagents/README.md](04-subagents/README.md)
+- Read: [05-mcp/README.md](05-mcp/README.md)
+- Read: [07-plugins/README.md](07-plugins/README.md)
+
+---
+
+### Milestone 4: Power User (Week 5+)
+
+**Topics**: Checkpoints + Advanced Features
+**Time**: 3-4 hours
+**Complexity**: ⭐⭐⭐⭐⭐ Advanced
+**Goal**: Master advanced workflows and experimentation
+
+#### What You'll Achieve
+✅ Safe experimentation with checkpoints
+✅ Planning mode for complex features
+✅ Headless mode for CI/CD
+✅ Fine-grained permission control
+✅ Background task management
+
+#### Hands-on Exercises
+
+```bash
+# Exercise 1: Try checkpoint workflow
+# In Claude Code:
+/checkpoint save "Before experiment"
+# ... make experimental changes ...
+/checkpoint rewind "Before experiment"
+
+# Exercise 2: Use planning mode
+/plan Implement user authentication system
+
+# Exercise 3: Try headless mode
+claude-code --headless --task "Run all tests and generate report"
+
+# Exercise 4: Configure advanced features
+# See 09-advanced-features/config-examples.json
+```
+
+#### Success Criteria
+- [ ] Created and reverted to a checkpoint
+- [ ] Used planning mode for a complex feature
+- [ ] Ran Claude Code in headless mode
+- [ ] Configured permission modes
+- [ ] Used background tasks for long operations
+
+#### Advanced Exercise
+Complete this end-to-end workflow:
+1. Create checkpoint "Clean state"
+2. Use planning mode to design a feature
+3. Implement with subagent delegation
+4. Run tests in background
+5. If tests fail, rewind to checkpoint
+6. Try alternative approach
+7. Use headless mode in CI/CD
+
+#### Next Steps
+- Set up CI/CD integration
+- Create custom configuration for your team
+- Read: [08-checkpoints/README.md](08-checkpoints/README.md)
+- Read: [09-advanced-features/README.md](09-advanced-features/README.md)
+
+---
+
+## ⚡ Quick Start Paths
+
+### If You Only Have 15 Minutes
+**Goal**: Get your first win
+
+1. Copy one slash command: `cp 01-slash-commands/optimize.md .claude/commands/`
+2. Try it in Claude Code: `/optimize`
+3. Read: [01-slash-commands/README.md](01-slash-commands/README.md)
+
+**Outcome**: You'll have a working slash command and understand the basics
+
+---
+
+### If You Have 1 Hour
+**Goal**: Set up essential productivity tools
+
+1. **Slash commands** (15 min): Copy and test `/optimize` and `/pr`
+2. **Project memory** (15 min): Create CLAUDE.md with your project standards
+3. **Install a skill** (15 min): Set up code-review skill
+4. **Try them together** (15 min): See how they work in harmony
+
+**Outcome**: Basic productivity boost with commands, memory, and auto-skills
+
+---
+
+### If You Have a Weekend
+**Goal**: Become proficient with most features
+
+**Saturday Morning** (3 hours):
+- Complete Milestone 1: Slash Commands + Memory
+- Complete Milestone 2: Skills + Hooks
+
+**Saturday Afternoon** (3 hours):
+- Complete Milestone 3: Subagents + MCP
+- Install and explore plugins
+
+**Sunday** (4 hours):
+- Complete Milestone 4: Checkpoints + Advanced Features
+- Build a custom plugin for your team
+- Set up complete CI/CD workflow
+
+**Outcome**: You'll be a Claude Code power user ready to train others
+
+---
+
+## 💡 Learning Tips
+
+### ✅ Do
+
+- **Follow the numbered order** (01 → 02 → 03...)
+- **Complete hands-on exercises** for each topic
+- **Start simple** and add complexity gradually
+- **Test each feature** before moving to the next
+- **Take notes** on what works for your workflow
+- **Refer back** to earlier concepts as you learn advanced topics
+- **Experiment safely** using checkpoints
+- **Share knowledge** with your team
+
+### ❌ Don't
+
+- **Skip directly to advanced features** - you'll miss foundations
+- **Try to learn everything at once** - it's overwhelming
+- **Copy configurations without understanding them** - you won't know how to debug
+- **Forget to test** - always verify features work
+- **Rush through milestones** - take time to understand
+- **Ignore the documentation** - each README has valuable details
+- **Work in isolation** - discuss with teammates
+
+---
+
+## 🎓 Learning Styles
+
+### Visual Learners
+- Study the mermaid diagrams in each README
+- Watch the command execution flow
+- Draw your own workflow diagrams
+- Use the visual learning path above
+
+### Hands-on Learners
+- Complete every hands-on exercise
+- Experiment with variations
+- Break things and fix them
+- Create your own examples
+
+### Reading Learners
+- Read each README thoroughly
+- Study the code examples
+- Review the comparison tables
+- Read the blog posts linked in resources
+
+### Social Learners
+- Set up pair programming sessions
+- Teach concepts to teammates
+- Join Claude Code community discussions
+- Share your custom configurations
+
+---
+
+## 📈 Progress Tracking
+
+Use this checklist to track your progress:
+
+### Week 1: Foundations
+- [ ] Completed 01-slash-commands
+- [ ] Completed 02-memory
+- [ ] Created first custom slash command
+- [ ] Set up project memory
+- [ ] Milestone 1 achieved
+
+### Week 2: Automation
+- [ ] Completed 03-skills
+- [ ] Completed 06-hooks
+- [ ] Installed first skill
+- [ ] Set up pre-commit hook
+- [ ] Milestone 2 achieved
+
+### Week 3-4: Integration
+- [ ] Completed 04-subagents
+- [ ] Completed 05-mcp
+- [ ] Completed 07-plugins
+- [ ] Connected GitHub MCP
+- [ ] Created custom subagent
+- [ ] Installed plugin
+- [ ] Milestone 3 achieved
+
+### Week 5+: Mastery
+- [ ] Completed 08-checkpoints
+- [ ] Completed 09-advanced-features
+- [ ] Used planning mode successfully
+- [ ] Set up headless CI/CD
+- [ ] Created team plugin
+- [ ] Milestone 4 achieved
+
+---
+
+## 🆘 Common Learning Challenges
+
+### Challenge 1: "Too many concepts at once"
+**Solution**: Focus on one milestone at a time. Complete all exercises before moving forward.
+
+### Challenge 2: "Don't know which feature to use when"
+**Solution**: Refer to the [Use Case Matrix](README.md#use-case-matrix) in the main README.
+
+### Challenge 3: "Configuration not working"
+**Solution**: Check the [Troubleshooting](README.md#troubleshooting) section and verify file locations.
+
+### Challenge 4: "Concepts seem to overlap"
+**Solution**: Review the [Feature Comparison](README.md#feature-comparison) table to understand differences.
+
+### Challenge 5: "Hard to remember everything"
+**Solution**: Create your own cheat sheet. Use checkpoints to experiment safely.
+
+---
+
+## 🎯 What's Next After Completion?
+
+Once you've completed all milestones:
+
+1. **Create team documentation** - Document your team's Claude Code setup
+2. **Build custom plugins** - Package your team's workflows
+3. **Contribute examples** - Share with the community
+4. **Mentor others** - Help teammates learn
+5. **Optimize workflows** - Continuously improve based on usage
+6. **Stay updated** - Follow Claude Code releases and new features
+
+---
+
+## 📚 Additional Resources
+
+### Official Documentation
+- [Claude Code Documentation](https://docs.claude.com/en/docs/claude-code)
+- [MCP Protocol Specification](https://modelcontextprotocol.io)
+- [Plugin Marketplace](https://plugins.claude.com)
+
+### Blog Posts
+- [Discovering Claude Code Slash Commands](https://medium.com/@luongnv89/discovering-claude-code-slash-commands-cdc17f0dfb29)
+
+### Community
+- [Claude Code Examples](https://github.com/anthropic/claude-examples)
+- [MCP Servers Repository](https://github.com/modelcontextprotocol/servers)
+
+---
+
+## 💬 Feedback & Support
+
+- **Found an issue?** Create an issue in the repository
+- **Have a suggestion?** Submit a pull request
+- **Need help?** Check the documentation or ask the community
+
+---
+
+**Last Updated**: November 2025
+**Maintained by**: Claude How-To Contributors
+**License**: Educational purposes, free to use and adapt
+
+---
+
+[← Back to Main README](README.md)

README.md

@@ -9,17 +9,108 @@ Complete collection of examples for some important Claude Code features and conc
 | Feature | Description | Folder |
 |---------|-------------|--------|
 | **Slash Commands** | User-invoked shortcuts | [01-slash-commands/](01-slash-commands/) |
-| **Subagents** | Specialized AI assistants | [02-subagents/](02-subagents/) |
-| **Memory** | Persistent context | [03-memory/](03-memory/) |
-| **MCP Protocol** | External tool access | [04-mcp/](04-mcp/) |
-| **Skills** | Reusable capabilities | [05-skills/](05-skills/) |
-| **Plugins** | Bundled features | [06-plugins/](06-plugins/) |
-| **Hooks** | Event-driven automation | [07-hooks/](07-hooks/) |
+| **Memory** | Persistent context | [02-memory/](02-memory/) |
+| **Skills** | Reusable capabilities | [03-skills/](03-skills/) |
+| **Subagents** | Specialized AI assistants | [04-subagents/](04-subagents/) |
+| **MCP Protocol** | External tool access | [05-mcp/](05-mcp/) |
+| **Hooks** | Event-driven automation | [06-hooks/](06-hooks/) |
+| **Plugins** | Bundled features | [07-plugins/](07-plugins/) |
 | **Checkpoints** | Session snapshots & rewind | [08-checkpoints/](08-checkpoints/) |
 | **Advanced Features** | Planning, thinking, background tasks | [09-advanced-features/](09-advanced-features/) |
 
 ---
 
+## 📚 Learning Path
+
+**New to Claude Code?** The folders are numbered in **recommended learning order**:
+
+| Order | Feature | Level | Time | Start Here |
+|-------|---------|-------|------|------------|
+| **1** | [Slash Commands](01-slash-commands/) | ⭐ Beginner | 30 min | ✅ **START** |
+| **2** | [Memory](02-memory/) | ⭐⭐ Beginner+ | 45 min | Essential |
+| **3** | [Skills](03-skills/) | ⭐⭐ Intermediate | 1 hour | Auto-invoke |
+| **4** | [Subagents](04-subagents/) | ⭐⭐⭐ Intermediate+ | 1.5 hours | Delegation |
+| **5** | [MCP](05-mcp/) | ⭐⭐⭐ Intermediate+ | 1 hour | Live data |
+| **6** | [Hooks](06-hooks/) | ⭐⭐ Intermediate | 1 hour | Automation |
+| **7** | [Plugins](07-plugins/) | ⭐⭐⭐⭐ Advanced | 2 hours | Bundles |
+| **8** | [Checkpoints](08-checkpoints/) | ⭐⭐ Intermediate | 45 min | Safe tests |
+| **9** | [Advanced](09-advanced-features/) | ⭐⭐⭐⭐⭐ Advanced | 2-3 hours | Power user |
+
+**Total**: ~10-12 hours | 📖 **[Complete Learning Roadmap →](LEARNING-ROADMAP.md)**
+
+---
+
+## 🎯 Quick Reference: Choose Your Features
+
+### Feature Comparison
+
+| Feature | Invocation | Persistence | Best For |
+|---------|-----------|------------|----------|
+| **Slash Commands** | Manual (`/cmd`) | Session only | Quick shortcuts |
+| **Memory** | Auto-loaded | Cross-session | Long-term learning |
+| **Skills** | Auto-invoked | Filesystem | Automated workflows |
+| **Subagents** | Auto-delegated | Isolated context | Task distribution |
+| **MCP Protocol** | Auto-queried | Real-time | Live data access |
+| **Hooks** | Event-triggered | Configured | Automation & validation |
+| **Plugins** | One command | All features | Complete solutions |
+| **Checkpoints** | Manual/Auto | Session-based | Safe experimentation |
+| **Planning Mode** | Manual/Auto | Plan phase | Complex implementations |
+| **Background Tasks** | Manual | Task duration | Long-running operations |
+
+### Use Case Matrix
+
+| Use Case | Recommended Features |
+|----------|---------------------|
+| **Team Onboarding** | Memory + Slash Commands + Plugins |
+| **Code Quality** | Subagents + Skills + Memory + Hooks |
+| **Documentation** | Skills + Subagents + Plugins |
+| **DevOps** | Plugins + MCP + Hooks + Background Tasks |
+| **Security Review** | Subagents + Skills + Hooks (read-only mode) |
+| **API Integration** | MCP + Memory |
+| **Quick Tasks** | Slash Commands |
+| **Complex Projects** | All Features + Planning Mode |
+| **Refactoring** | Checkpoints + Planning Mode + Hooks |
+| **Learning/Experimentation** | Checkpoints + Extended Thinking + Permission Mode |
+| **CI/CD Automation** | Headless Mode + Hooks + Background Tasks |
+| **Performance Optimization** | Planning Mode + Checkpoints + Background Tasks |
+
+---
+
+## ⚡ Getting Started
+
+### 15 Minutes - First Steps
+```bash
+# Copy your first slash command
+cp 01-slash-commands/optimize.md .claude/commands/
+
+# Try it!
+# In Claude Code: /optimize
+```
+
+### 1 Hour - Essential Setup
+```bash
+# 1. Slash commands (15 min)
+cp 01-slash-commands/*.md .claude/commands/
+
+# 2. Project memory (15 min)
+cp 02-memory/project-CLAUDE.md ./CLAUDE.md
+
+# 3. Install a skill (15 min)
+cp -r 03-skills/code-review ~/.claude/skills/
+
+# 4. Try them together (15 min)
+# See how they work in harmony!
+```
+
+### Weekend - Full Setup
+- **Day 1**: Slash Commands, Memory, Skills, Hooks
+- **Day 2**: Subagents, MCP integration, Plugins
+- **Result**: Complete Claude Code power user setup
+
+📖 **[Detailed milestones and exercises →](LEARNING-ROADMAP.md)**
+
+---
+
 ## 01. Slash Commands
 
 **Location**: [01-slash-commands/](01-slash-commands/)
@@ -47,9 +138,60 @@ cp 01-slash-commands/*.md /path/to/project/.claude/commands/
 
 ---
 
-## 02. Subagents
+## 02. Memory
 
-**Location**: [02-subagents/](02-subagents/)
+**Location**: [02-memory/](02-memory/)
+
+**What**: Persistent context across sessions
+
+**Examples**:
+- `project-CLAUDE.md` - Team-wide project standards
+- `directory-api-CLAUDE.md` - Directory-specific rules
+- `personal-CLAUDE.md` - Personal preferences
+
+**Installation**:
+```bash
+# Project memory
+cp 02-memory/project-CLAUDE.md /path/to/project/CLAUDE.md
+
+# Directory memory
+cp 02-memory/directory-api-CLAUDE.md /path/to/project/src/api/CLAUDE.md
+
+# Personal memory
+cp 02-memory/personal-CLAUDE.md ~/.claude/CLAUDE.md
+```
+
+**Usage**: Automatically loaded by Claude
+
+---
+
+## 03. Skills
+
+**Location**: [03-skills/](03-skills/)
+
+**What**: Reusable, auto-invoked capabilities with instructions and scripts
+
+**Examples**:
+- `code-review/` - Comprehensive code review with scripts
+- `brand-voice/` - Brand voice consistency checker
+- `doc-generator/` - API documentation generator
+
+**Installation**:
+```bash
+# Personal skills
+cp -r 03-skills/code-review ~/.claude/skills/
+
+# Project skills
+cp -r 03-skills/code-review /path/to/project/.claude/skills/
+```
+
+**Usage**: Automatically invoked when relevant
+
+---
+
+## 04. Subagents
+
+**Location**: [04-subagents/](04-subagents/)
 
 **What**: Specialized AI assistants with isolated contexts and custom prompts
 
@@ -62,43 +204,16 @@ cp 01-slash-commands/*.md /path/to/project/.claude/commands/
 
 **Installation**:
 ```bash
-cp 02-subagents/*.md /path/to/project/.claude/agents/
+cp 04-subagents/*.md /path/to/project/.claude/agents/
 ```
 
 **Usage**: Automatically delegated by main agent
 
 ---
 
-## 03. Memory
+## 05. MCP Protocol
 
-**Location**: [03-memory/](03-memory/)
-
-**What**: Persistent context across sessions
-
-**Examples**:
-- `project-CLAUDE.md` - Team-wide project standards
-- `directory-api-CLAUDE.md` - Directory-specific rules
-- `personal-CLAUDE.md` - Personal preferences
-
-**Installation**:
-```bash
-# Project memory
-cp 03-memory/project-CLAUDE.md /path/to/project/CLAUDE.md
-
-# Directory memory
-cp 03-memory/directory-api-CLAUDE.md /path/to/project/src/api/CLAUDE.md
-
-# Personal memory
-cp 03-memory/personal-CLAUDE.md ~/.claude/CLAUDE.md
-```
-
-**Usage**: Automatically loaded by Claude
-
----
-
-## 04. MCP Protocol
-
-**Location**: [04-mcp/](04-mcp/)
+**Location**: [05-mcp/](05-mcp/)
 
 **What**: Model Context Protocol for accessing external tools and APIs
 
@@ -115,7 +230,7 @@ export GITHUB_TOKEN="your_token"
 export DATABASE_URL="postgresql://..."
 
 # Copy configuration
-cp 04-mcp/github-mcp.json ~/.claude/mcp.json
+cp 05-mcp/github-mcp.json ~/.claude/mcp.json
 ```
 
 **Usage**:
@@ -126,55 +241,9 @@ cp 04-mcp/github-mcp.json ~/.claude/mcp.json
 
 ---
 
-## 05. Skills
+## 06. Hooks
 
-**Location**: [05-skills/](05-skills/)
-
-**What**: Reusable, auto-invoked capabilities with instructions and scripts
-
-**Examples**:
-- `code-review/` - Comprehensive code review with scripts
-- `brand-voice/` - Brand voice consistency checker
-- `doc-generator/` - API documentation generator
-
-**Installation**:
-```bash
-# Personal skills
-cp -r 05-skills/code-review ~/.claude/skills/
-
-# Project skills
-cp -r 05-skills/code-review /path/to/project/.claude/skills/
-```
-
-**Usage**: Automatically invoked when relevant
-
----
-
-## 06. Plugins
-
-**Location**: [06-plugins/](06-plugins/)
-
-**What**: Bundled collections of commands, agents, MCP, and hooks
-
-**Examples**:
-- `pr-review/` - Complete PR review workflow
-- `devops-automation/` - Deployment and monitoring
-- `documentation/` - Documentation generation
-
-**Installation**:
-```bash
-/plugin install pr-review
-/plugin install devops-automation
-/plugin install documentation
-```
-
-**Usage**: Use bundled slash commands and features
-
----
-
-## 07. Hooks
-
-**Location**: [07-hooks/](07-hooks/)
+**Location**: [06-hooks/](06-hooks/)
 
 **What**: Event-driven shell commands that execute automatically in response to Claude Code events
 
@@ -189,7 +258,7 @@ cp -r 05-skills/code-review /path/to/project/.claude/skills/
 **Installation**:
 ```bash
 mkdir -p ~/.claude/hooks
-cp 07-hooks/*.sh ~/.claude/hooks/
+cp 06-hooks/*.sh ~/.claude/hooks/
 chmod +x ~/.claude/hooks/*.sh
 
 # Configure in settings
@@ -211,6 +280,28 @@ echo '{
 
 ---
 
+## 07. Plugins
+
+**Location**: [07-plugins/](07-plugins/)
+
+**What**: Bundled collections of commands, agents, MCP, and hooks
+
+**Examples**:
+- `pr-review/` - Complete PR review workflow
+- `devops-automation/` - Deployment and monitoring
+- `documentation/` - Documentation generation
+
+**Installation**:
+```bash
+/plugin install pr-review
+/plugin install devops-automation
+/plugin install documentation
+```
+
+**Usage**: Use bundled slash commands and features
+
+---
+
 ## 08. Checkpoints and Rewind
 
 **Location**: [08-checkpoints/](08-checkpoints/)
@@ -355,52 +446,6 @@ See [config-examples.json](09-advanced-features/config-examples.json) for comple
 
 ---
 
-## Feature Comparison
-
-| Feature | Invocation | Persistence | Best For |
-|---------|-----------|------------|----------|
-| **Slash Commands** | Manual (`/cmd`) | Session only | Quick shortcuts |
-| **Subagents** | Auto-delegated | Isolated context | Task distribution |
-| **Memory** | Auto-loaded | Cross-session | Long-term learning |
-| **MCP Protocol** | Auto-queried | Real-time | Live data access |
-| **Skills** | Auto-invoked | Filesystem | Automated workflows |
-| **Plugins** | One command | All features | Complete solutions |
-| **Hooks** | Event-triggered | Configured | Automation & validation |
-| **Checkpoints** | Manual/Auto | Session-based | Safe experimentation |
-| **Planning Mode** | Manual/Auto | Plan phase | Complex implementations |
-| **Background Tasks** | Manual | Task duration | Long-running operations |
-
----
-
-## Getting Started
-
-### Week 1: Basics
-1. Copy slash commands to `.claude/commands/`
-2. Try `/optimize` and `/pr` commands
-3. Create project memory in `CLAUDE.md`
-
-### Week 2: Real-time Access
-1. Set up GitHub MCP
-2. Query PRs and issues
-3. Try multi-MCP configuration
-
-### Week 3: Distribution
-1. Create first subagent
-2. Test with complex task
-3. Delegate work to specialists
-
-### Week 4: Automation
-1. Install a skill
-2. Let Claude auto-invoke it
-3. Create custom skill
-
-### Week 5: Complete Solution
-1. Install a plugin
-2. Use bundled features
-3. Consider creating your own
-
----
-
 ## Directory Structure
 
 ```
@@ -410,25 +455,12 @@ See [config-examples.json](09-advanced-features/config-examples.json) for comple
 │   ├── pr.md
 │   ├── generate-api-docs.md
 │   └── README.md
-├── 02-subagents/
-│   ├── code-reviewer.md
-│   ├── test-engineer.md
-│   ├── documentation-writer.md
-│   ├── secure-reviewer.md
-│   ├── implementation-agent.md
-│   └── README.md
-├── 03-memory/
+├── 02-memory/
 │   ├── project-CLAUDE.md
 │   ├── directory-api-CLAUDE.md
 │   ├── personal-CLAUDE.md
 │   └── README.md
-├── 04-mcp/
-│   ├── github-mcp.json
-│   ├── database-mcp.json
-│   ├── filesystem-mcp.json
-│   ├── multi-mcp.json
-│   └── README.md
-├── 05-skills/
+├── 03-skills/
 │   ├── code-review/
 │   │   ├── SKILL.md
 │   │   ├── scripts/
@@ -440,12 +472,20 @@ See [config-examples.json](09-advanced-features/config-examples.json) for comple
 │   │   ├── SKILL.md
 │   │   └── generate-docs.py
 │   └── README.md
-├── 06-plugins/
-│   ├── pr-review/
-│   ├── devops-automation/
-│   ├── documentation/
+├── 04-subagents/
+│   ├── code-reviewer.md
+│   ├── test-engineer.md
+│   ├── documentation-writer.md
+│   ├── secure-reviewer.md
+│   ├── implementation-agent.md
 │   └── README.md
-├── 07-hooks/
+├── 05-mcp/
+│   ├── github-mcp.json
+│   ├── database-mcp.json
+│   ├── filesystem-mcp.json
+│   ├── multi-mcp.json
+│   └── README.md
+├── 06-hooks/
 │   ├── format-code.sh
 │   ├── pre-commit.sh
 │   ├── security-scan.sh
@@ -453,6 +493,11 @@ See [config-examples.json](09-advanced-features/config-examples.json) for comple
 │   ├── validate-prompt.sh
 │   ├── notify-team.sh
 │   └── README.md
+├── 07-plugins/
+│   ├── pr-review/
+│   ├── devops-automation/
+│   ├── documentation/
+│   └── README.md
 ├── 08-checkpoints/
 │   ├── checkpoint-examples.md
 │   └── README.md
@@ -465,6 +510,42 @@ See [config-examples.json](09-advanced-features/config-examples.json) for comple
 
 ---
 
+## Installation Quick Reference
+
+```bash
+# Slash Commands
+cp 01-slash-commands/*.md .claude/commands/
+
+# Memory
+cp 02-memory/project-CLAUDE.md ./CLAUDE.md
+
+# Skills
+cp -r 03-skills/code-review ~/.claude/skills/
+
+# Subagents
+cp 04-subagents/*.md .claude/agents/
+
+# MCP
+export GITHUB_TOKEN="token"
+cp 05-mcp/github-mcp.json .claude/mcp.json
+
+# Hooks
+mkdir -p ~/.claude/hooks
+cp 06-hooks/*.sh ~/.claude/hooks/
+chmod +x ~/.claude/hooks/*.sh
+
+# Plugins
+/plugin install pr-review
+
+# Checkpoints (auto-enabled, configure in settings)
+# See 08-checkpoints/README.md
+
+# Advanced Features (configure in settings)
+# See 09-advanced-features/config-examples.json
+```
+
+---
+
 ## Example Workflows
 
 ### 1. Complete Code Review Workflow
@@ -516,61 +597,6 @@ Claude:
 
 ---
 
-## Installation Quick Reference
-
-```bash
-# Slash Commands
-cp 01-slash-commands/*.md .claude/commands/
-
-# Subagents
-cp 02-subagents/*.md .claude/agents/
-
-# Memory
-cp 03-memory/project-CLAUDE.md ./CLAUDE.md
-
-# MCP
-export GITHUB_TOKEN="token"
-cp 04-mcp/github-mcp.json .claude/mcp.json
-
-# Skills
-cp -r 05-skills/code-review ~/.claude/skills/
-
-# Plugins
-/plugin install pr-review
-
-# Hooks
-mkdir -p ~/.claude/hooks
-cp 07-hooks/*.sh ~/.claude/hooks/
-chmod +x ~/.claude/hooks/*.sh
-
-# Checkpoints (auto-enabled, configure in settings)
-# See 08-checkpoints/README.md
-
-# Advanced Features (configure in settings)
-# See 09-advanced-features/config-examples.json
-```
-
----
-
-## Use Case Matrix
-
-| Use Case | Recommended Features |
-|----------|---------------------|
-| **Team Onboarding** | Memory + Slash Commands + Plugins |
-| **Code Quality** | Subagents + Skills + Memory + Hooks |
-| **Documentation** | Skills + Subagents + Plugins |
-| **DevOps** | Plugins + MCP + Hooks + Background Tasks |
-| **Security Review** | Subagents + Skills + Hooks (read-only mode) |
-| **API Integration** | MCP + Memory |
-| **Quick Tasks** | Slash Commands |
-| **Complex Projects** | All Features + Planning Mode |
-| **Refactoring** | Checkpoints + Planning Mode + Hooks |
-| **Learning/Experimentation** | Checkpoints + Extended Thinking + Permission Mode |
-| **CI/CD Automation** | Headless Mode + Hooks + Background Tasks |
-| **Performance Optimization** | Planning Mode + Checkpoints + Background Tasks |
-
----
-
 ## Best Practices
 
 ### Do's ✅