A visual, example-driven guide to Claude Code — from basic concepts to advanced agents, with copy-paste templates that bring immediate value.

This project complements Anthropic's official documentation with a different approach:

What you'll find here:

• Mermaid diagrams explaining how each feature works
• Ready-to-use configurations you can copy into your project
• Real-world examples with context and best practices
• Clear progression from /help to building custom agents
• Troubleshooting guides based on common issues

• Why This Guide?
• Quick Navigation
• Learning Path
• Quick Reference
• Getting Started
• Features
  • 01. Slash Commands
  • 02. Memory
  • 03. Skills
  • 04. Subagents
  • 05. MCP Protocol
  • 06. Hooks
  • 07. Plugins
  • 08. Checkpoints
  • 09. Advanced Features
  • 10. CLI Reference
• Directory Structure
• Installation Quick Reference
• Example Workflows
• Best Practices
• Troubleshooting
• Testing
• Additional Resources
• Contributing
• EPUB Generation
• Contributors
• Star History

New to Claude Code? The folders are numbered in recommended learning order:

Total: ~11-13 hours | 📖 Complete Learning Roadmap →

# Copy your first slash command
cp 01-slash-commands/optimize.md .claude/commands/

# Try it!
# In Claude Code: /optimize

# 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!

• Day 1: Slash Commands, Memory, Skills, Hooks
• Day 2: Subagents, MCP integration, Plugins
• Result: Complete Claude Code power user setup

📖 Detailed milestones and exercises →

Location: 01-slash-commands/

What: User-invoked shortcuts stored as Markdown files

Examples:

• optimize.md - Code optimization analysis
• pr.md - Pull request preparation
• generate-api-docs.md - API documentation generator

Installation:

cp 01-slash-commands/*.md /path/to/project/.claude/commands/

Usage:

/optimize
/pr
/generate-api-docs

Learn More: Discovering Claude Code Slash Commands

Location: 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:

# 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

Location: 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:

# 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

Location: 04-subagents/

What: Specialized AI assistants with isolated contexts and custom prompts

Examples:

• code-reviewer.md - Comprehensive code quality analysis
• test-engineer.md - Test strategy and coverage
• documentation-writer.md - Technical documentation
• secure-reviewer.md - Security-focused review (read-only)
• implementation-agent.md - Full feature implementation

Installation:

cp 04-subagents/*.md /path/to/project/.claude/agents/

Usage: Automatically delegated by main agent

Location: 05-mcp/

What: Model Context Protocol for accessing external tools and APIs

Examples:

• github-mcp.json - GitHub integration
• database-mcp.json - Database queries
• filesystem-mcp.json - File operations
• multi-mcp.json - Multiple MCP servers

Installation:

# Set environment variables
export GITHUB_TOKEN="your_token"
export DATABASE_URL="postgresql://..."

# Copy configuration
cp 05-mcp/github-mcp.json ~/.claude/mcp.json

Usage:

/mcp__github__list_prs
/mcp__github__get_pr 456

Location: 06-hooks/

What: Event-driven shell commands that execute automatically in response to Claude Code events

Examples:

• format-code.sh - Auto-format code before writing
• pre-commit.sh - Run tests before commits
• security-scan.sh - Scan for security issues
• log-bash.sh - Log all bash commands
• validate-prompt.sh - Validate user prompts
• notify-team.sh - Send notifications on events

Installation:

mkdir -p ~/.claude/hooks
cp 06-hooks/*.sh ~/.claude/hooks/
chmod +x ~/.claude/hooks/*.sh

# Configure in settings
echo '{
  "hooks": {
    "PreToolUse:Write": "~/.claude/hooks/format-code.sh ${file_path}",
    "PostToolUse:Write": "~/.claude/hooks/security-scan.sh ${file_path}",
    "PreCommit": "~/.claude/hooks/pre-commit.sh"
  }
}' > ~/.claude/hooks-config.json

Usage: Hooks execute automatically on events

Hook Types:

• Tool Hooks: PreToolUse:*, PostToolUse:*
• Session Hooks: UserPromptSubmit, SessionStart, SessionEnd
• Git Hooks: PreCommit, PostCommit, PrePush

Location: 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:

/plugin install pr-review
/plugin install devops-automation
/plugin install documentation

Usage: Use bundled slash commands and features

Location: 08-checkpoints/

What: Save conversation state and rewind to previous points to explore different approaches

Key Concepts:

• Checkpoint: Snapshot of conversation state
• Rewind: Return to previous checkpoint
• Branch Point: Explore multiple approaches from same checkpoint

Usage:

# Create checkpoint
/checkpoint save "Before refactoring"

# List checkpoints
/checkpoint list

# Rewind to checkpoint
/checkpoint rewind "Before refactoring"

# Compare checkpoints
/checkpoint diff checkpoint-1 checkpoint-2

Use Cases:

• Try different implementation approaches
• Recover from mistakes
• Safe experimentation
• Compare alternative solutions
• A/B testing different designs

Example Workflow:

1. /checkpoint save "Working state"
2. Try experimental approach
3. If it works: Continue
4. If it fails: /checkpoint rewind "Working state"

Location: 09-advanced-features/

What: Advanced capabilities for complex workflows and automation

Create detailed implementation plans before coding:

User: /plan Implement user authentication system

Claude: [Creates comprehensive step-by-step plan]

User: Approve and proceed

Benefits: Clear roadmap, time estimates, risk assessment

Deep reasoning for complex problems:

User: /think Should we use microservices or monolith?

Claude: [Analyzes trade-offs systematically]

Benefits: Better architectural decisions, thorough analysis

Run long operations without blocking:

User: Run tests in background

Claude: Started bg-1234, you can continue working

[Later] Test results: 245 passed, 3 failed

Benefits: Parallel development, no waiting

Control what Claude can do:

• Unrestricted: Full access (default)
• Confirm: Ask before actions
• Read-only: Analysis only, no modifications
• Custom: Granular permissions

/permission readonly    # Code review mode
/permission confirm     # Learning mode
/permission unrestricted # Full automation

Run Claude Code in CI/CD and automation:

claude-code --headless --task "Run tests and generate report"

Use Cases: CI/CD, automated reviews, batch processing

Manage multiple work sessions:

/session list           # Show all sessions
/session new "Feature"  # Create new session
/session switch "Bug"   # Switch sessions
/session save           # Save current state

Keyboard Shortcuts: Ctrl+R (search), Tab (complete), ↑/↓ (history)

Command History: Access previous commands

Multi-line Input: Complex prompts across multiple lines

Customize Claude Code behavior:

{
  "planning": { "autoEnter": true },
  "extendedThinking": { "enabled": true },
  "backgroundTasks": { "maxConcurrentTasks": 5 },
  "permissions": { "mode": "unrestricted" },
  "checkpoints": { "autoCheckpoint": true }
}

See config-examples.json for complete configurations.

Location: 10-cli/

What: Complete command-line interface reference for Claude Code

Key Areas:

• CLI commands (claude, claude -p, claude -c, claude -r)
• Core flags (print mode, continue, resume, version)
• Model & configuration (--model, --agents)
• System prompt customization
• Tool & permission management
• Output formats (text, JSON, stream-JSON)
• MCP configuration
• Session management

Quick Examples:

# Interactive mode
claude "explain this project"

# Print mode (non-interactive)
claude -p "review this code"

# Process file content
cat error.log | claude -p "explain this error"

# JSON output for scripts
claude -p --output-format json "list functions"

# Resume session
claude -r "feature-auth" "continue implementation"

Use Cases:

• CI/CD pipeline integration
• Script automation and piping
• Batch processing
• Multi-session workflows
• Custom agent configurations

├── 01-slash-commands/
│   ├── optimize.md
│   ├── pr.md
│   ├── generate-api-docs.md
│   └── README.md
├── 02-memory/
│   ├── project-CLAUDE.md
│   ├── directory-api-CLAUDE.md
│   ├── personal-CLAUDE.md
│   └── README.md
├── 03-skills/
│   ├── code-review/
│   │   ├── SKILL.md
│   │   ├── scripts/
│   │   └── templates/
│   ├── brand-voice/
│   │   ├── SKILL.md
│   │   └── templates/
│   ├── doc-generator/
│   │   ├── SKILL.md
│   │   └── generate-docs.py
│   └── README.md
├── 04-subagents/
│   ├── code-reviewer.md
│   ├── test-engineer.md
│   ├── documentation-writer.md
│   ├── secure-reviewer.md
│   ├── implementation-agent.md
│   └── README.md
├── 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
│   ├── log-bash.sh
│   ├── validate-prompt.sh
│   ├── notify-team.sh
│   └── README.md
├── 07-plugins/
│   ├── pr-review/
│   ├── devops-automation/
│   ├── documentation/
│   └── README.md
├── 08-checkpoints/
│   ├── checkpoint-examples.md
│   └── README.md
├── 09-advanced-features/
│   ├── config-examples.json
│   ├── planning-mode-examples.md
│   └── README.md
├── 10-cli/
│   └── README.md
└── README.md (this file)

# 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

# CLI Reference (no installation needed)
# See 10-cli/README.md for usage examples

# Uses: Slash Commands + Subagents + Memory + MCP

User: /review-pr

Claude:
1. Loads project memory (coding standards)
2. Fetches PR via GitHub MCP
3. Delegates to code-reviewer subagent
4. Delegates to test-engineer subagent
5. Synthesizes findings
6. Provides comprehensive review

# Uses: Skills + Subagents + Memory

User: "Generate API documentation for the auth module"

Claude:
1. Loads project memory (doc standards)
2. Detects doc generation request
3. Auto-invokes doc-generator skill
4. Delegates to api-documenter subagent
5. Creates comprehensive docs with examples

# Uses: Plugins + MCP + Hooks

User: /deploy production

Claude:
1. Runs pre-deploy hook (validates environment)
2. Delegates to deployment-specialist subagent
3. Executes deployment via Kubernetes MCP
4. Monitors progress
5. Runs post-deploy hook (health checks)
6. Reports status

• Start simple with slash commands
• Add features incrementally
• Use memory for team standards
• Test configurations locally first
• Document custom implementations
• Version control project configurations
• Share plugins with team

• Don't create redundant features
• Don't hardcode credentials
• Don't skip documentation
• Don't over-complicate simple tasks
• Don't ignore security best practices
• Don't commit sensitive data

1. Check file location and naming
2. Verify YAML frontmatter syntax
3. Check file permissions
4. Review Claude Code version compatibility

1. Verify environment variables
2. Check MCP server installation
3. Test credentials
4. Review network connectivity

1. Check tool permissions
2. Verify agent description clarity
3. Review task complexity
4. Test agent independently

This project includes comprehensive automated testing to ensure code quality and reliability.

• Unit Tests: Python tests using pytest (Python 3.10, 3.11, 3.12)
• Code Quality: Linting and formatting with Ruff
• Security: Vulnerability scanning with Bandit
• Type Checking: Static type analysis with mypy
• Build Verification: EPUB generation testing
• Coverage Tracking: Codecov integration

# Install development dependencies
uv pip install -r requirements-dev.txt

# Run all unit tests
pytest scripts/tests/ -v

# Run tests with coverage report
pytest scripts/tests/ -v --cov=scripts --cov-report=html

# Run code quality checks
ruff check scripts/
ruff format --check scripts/

# Run security scan
bandit -c pyproject.toml -r scripts/ --exclude scripts/tests/

# Run type checking
mypy scripts/ --ignore-missing-imports

Tests run automatically on:

• Every push to main or develop branches
• Every pull request to main

View test results in the GitHub Actions tab or check the TESTING.md guide for detailed information.

When contributing, please include tests for new functionality:

1. Write tests in scripts/tests/test_*.py
2. Run tests locally to verify they pass
3. Check coverage with pytest --cov=scripts
4. Submit with PR - tests are required for all contributions

For detailed testing guidelines, see TESTING.md.

• Claude Code Documentation
• MCP Protocol Specification
• Plugin Marketplace
• Community Examples
• Boris Cherny's Claude Code Workflow - The creator of Claude Code shares his systematized workflow: parallel agents, shared CLAUDE.md, Plan mode, slash commands, subagents, and verification hooks for autonomous long-running sessions. Key insights include turning recurring workflows into reusable commands and wiring Claude into team tools (GitHub, Slack, BigQuery, Sentry) for end-to-end work with feedback loops.

Found an issue or want to contribute an example? We'd love your help!

Please read CONTRIBUTING.md for detailed guidelines on:

• Types of contributions (examples, docs, features, bugs, feedback)
• How to set up your development environment
• Directory structure and how to add content
• Writing guidelines and best practices
• Commit and PR process

Our Community Standards:

• CODE_OF_CONDUCT.md - How we treat each other
• SECURITY.md - Security policy and vulnerability reporting

If you discover a security vulnerability, please report it responsibly:

1. Use GitHub Private Vulnerability Reporting: https://github.com/luongnv89/claude-howto/security/advisories
2. Or read .github/SECURITY_REPORTING.md for detailed instructions
3. Do NOT open a public issue for security vulnerabilities

Security issues are taken seriously and will be addressed promptly. See SECURITY.md for our full security policy.

Quick start:

1. Fork and clone the repository
2. Create a descriptive branch (add/feature-name, fix/bug, docs/improvement)
3. Make your changes following the guidelines
4. Submit a pull request with a clear description

Need help? Open an issue or discussion, and we'll guide you through the process.

This project is licensed under the MIT License - see LICENSE file for details.

You are free to:

• Use this guide and examples in your projects
• Modify and adapt the content
• Share and distribute
• Use for commercial purposes

The only requirement is to include a copy of the license and copyright notice.

Want to read this guide offline? Generate an EPUB ebook:

uv run scripts/build_epub.py

This creates claude-howto-guide.epub with all content, including rendered Mermaid diagrams.

See scripts/README.md for more options.

Thanks to everyone who has contributed to this project!

Last Updated: January 2026 Claude Code Version: 1.0+ Compatible Models: Claude Sonnet 4.5, Claude Opus 4.5, Claude Haiku 4.5