claude-howto-guide

---
name: claude-howto-guide
description: Master Claude Code features — slash commands, memory, hooks, subagents, MCP, skills, plugins, checkpoints, and CLI — using the claude-howto structured tutorial guide.
triggers:
  - how do I use Claude Code effectively
  - set up Claude Code slash commands
  - configure hooks in Claude Code
  - create a subagent workflow with Claude Code
  - install MCP servers for Claude Code
  - use Claude Code memory and CLAUDE.md
  - set up a Claude Code plugin
  - automate code review with Claude Code
---

# Claude How-To: Master Claude Code Features

> Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection.

`claude-howto` is a structured, visual, example-driven tutorial guide for Claude Code. It covers every major feature — slash commands, memory, skills, subagents, MCP, hooks, plugins, checkpoints, and CLI — with copy-paste templates, Mermaid diagrams, and a progressive 11–13 hour learning path.

---

## Installation

```bash
git clone https://github.com/luongnv89/claude-howto.git
cd claude-howto

No Python dependencies are required to use the templates. To build the offline EPUB:

uv run scripts/build_epub.py

---

Repository Structure

claude-howto/
├── 01-slash-commands/     # User-invoked shortcuts (/cmd)
├── 02-memory/             # Persistent context (CLAUDE.md)
├── 03-skills/             # Reusable capabilities (auto-invoked)
├── 04-subagents/          # Specialized AI assistants
├── 05-mcp/                # External tool access via MCP protocol
├── 06-hooks/              # Event-driven automation
├── 07-plugins/            # Bundled feature packages
├── 08-checkpoints/        # Session snapshots and rewind
├── 09-advanced-features/  # Planning, thinking, background tasks
├── 10-cli/                # CLI commands, flags, options
├── LEARNING-ROADMAP.md    # Guided learning path
├── CATALOG.md             # Full feature catalog
└── CONTRIBUTING.md

---

Quick 15-Minute Setup

# Create Claude Code command directory in your project
mkdir -p /path/to/your-project/.claude/commands

# Copy a slash command template
cp 01-slash-commands/optimize.md /path/to/your-project/.claude/commands/

# Set up project memory
cp 02-memory/project-CLAUDE.md /path/to/your-project/CLAUDE.md

# Install a skill
cp -r 03-skills/code-review ~/.claude/skills/

---

Feature 1: Slash Commands

Slash commands are Markdown files in .claude/commands/. The filename becomes the command name.

File: .claude/commands/review.md

# Code Review

Review the current file or selection for:
- Logic errors and edge cases
- Performance bottlenecks
- Security vulnerabilities
- Style and readability

Provide a structured report with severity levels (critical / warning / suggestion).

Usage in Claude Code:

/review

Copy all example commands:

cp 01-slash-commands/*.md .claude/commands/

---

Feature 2: Memory (CLAUDE.md)

CLAUDE.md files give Claude persistent context about your project. They are auto-loaded at session start.

Scopes:

• ~/.claude/CLAUDE.md — global, applies to all projects
• ./CLAUDE.md — project-level
• ./src/CLAUDE.md — directory-level

Template: ./CLAUDE.md

# Project: my-api

## Stack
- Python 3.12, FastAPI, PostgreSQL
- Tests: pytest, httpx
- Linting: ruff, mypy

## Conventions
- All endpoints return `{"data": ..., "error": null}` or `{"data": null, "error": "..."}`
- Use `async def` for all route handlers
- Database sessions via `get_db()` dependency injection

## Key Commands
- `make test` — run test suite
- `make lint` — ruff + mypy
- `make migrate` — run Alembic migrations

## Do Not
- Never commit secrets or `.env` files
- Never use `print()` for logging — use `structlog`

Copy the template:

cp 02-memory/project-CLAUDE.md ./CLAUDE.md

---

Feature 3: Skills

Skills are reusable capability definitions that Claude invokes automatically based on context. They live in ~/.claude/skills/ (global) or .claude/skills/ (project).

Structure:

~/.claude/skills/
└── code-review/
    ├── skill.md        # Skill definition
    └── templates/      # Supporting templates

Install a skill:

cp -r 03-skills/code-review ~/.claude/skills/

Example skill.md:

# Skill: Code Review

Trigger: When reviewing code, PRs, or diffs.

## Behavior
1. Check for security vulnerabilities (injection, secrets, auth bypass)
2. Identify performance issues (N+1 queries, unbounded loops)
3. Verify error handling completeness
4. Assess test coverage gaps
5. Output findings as a structured Markdown report

---

Feature 4: Subagents

Subagents are specialized Claude instances delegated subtasks. Define them in .claude/agents/.

File: .claude/agents/security-auditor.md

# Agent: Security Auditor

## Role
Specialized security review agent. Focus exclusively on:
- Injection vulnerabilities (SQL, command, LDAP)
- Authentication and authorization flaws
- Secrets or credentials in code
- Insecure dependencies

## Output Format
Return a JSON report:
{
  "critical": [...],
  "high": [...],
  "medium": [...],
  "low": [...]
}

Orchestrating subagents in a workflow:

# Example: Trigger subagent delegation via Claude Code SDK
import anthropic

client = anthropic.Anthropic()

orchestrator_prompt = """
You are an orchestrator. For the following code diff, delegate to:
1. The security-auditor agent for vulnerability scanning
2. The performance-reviewer agent for bottleneck detection

Return a combined report.

Code diff:
{diff}
""".format(diff=open("changes.diff").read())

response = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=4096,
    messages=[{"role": "user", "content": orchestrator_prompt}]
)
print(response.content[0].text)

---

Feature 5: MCP (Model Context Protocol)

MCP servers give Claude access to external tools and live data. Configure in .claude/mcp.json.

File: .claude/mcp.json

{
  "servers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"]
    }
  }
}

Environment variables (never hardcode):

export GITHUB_TOKEN="your-token-here"
export DATABASE_URL="postgresql://user:pass@localhost/db"

Copy MCP config templates:

cp 05-mcp/mcp.json .claude/mcp.json

---

Feature 6: Hooks

Hooks are scripts triggered by Claude Code events. They live in .claude/hooks/.

Supported events:

Event	Trigger
pre-tool-use	Before Claude runs any tool
post-tool-use	After a tool completes
pre-file-write	Before writing a file
post-file-write	After writing a file
session-start	When a session begins
session-end	When a session ends

File: .claude/hooks/post-file-write.sh

#!/bin/bash
# Auto-run linter after Claude writes a Python file

FILE="$1"

if [[ "$FILE" == *.py ]]; then
  echo "Running ruff on $FILE..."
  ruff check --fix "$FILE"
  mypy "$FILE" --ignore-missing-imports
fi

File: .claude/hooks/pre-file-write.py

#!/usr/bin/env python3
"""Block writes to protected paths."""

import sys
import os

PROTECTED = [".env", "secrets.json", "credentials.yaml"]

file_path = sys.argv[1] if len(sys.argv) > 1 else ""
filename = os.path.basename(file_path)

if filename in PROTECTED:
    print(f"BLOCKED: Writing to {filename} is not allowed.", file=sys.stderr)
    sys.exit(1)

sys.exit(0)

Register hooks in .claude/config.json:

{
  "hooks": {
    "post-file-write": ".claude/hooks/post-file-write.sh",
    "pre-file-write": ".claude/hooks/pre-file-write.py"
  }
}

Copy hook templates:

cp 06-hooks/*.sh .claude/hooks/
cp 06-hooks/*.py .claude/hooks/
chmod +x .claude/hooks/*

---

Feature 7: Plugins

Plugins bundle slash commands, skills, hooks, and memory into a single installable package.

Plugin structure:

my-plugin/
├── plugin.json
├── commands/
│   └── deploy.md
├── hooks/
│   └── pre-deploy.sh
├── skills/
│   └── deployment/skill.md
└── memory/
    └── CLAUDE.md

File: plugin.json

{
  "name": "devops-pipeline",
  "version": "1.0.0",
  "description": "Full DevOps automation plugin",
  "commands": ["commands/deploy.md"],
  "hooks": {
    "pre-tool-use": "hooks/pre-deploy.sh"
  },
  "skills": ["skills/deployment/"],
  "memory": "memory/CLAUDE.md"
}

Install a plugin:

# Copy from claude-howto examples
cp -r 07-plugins/devops-pipeline .claude/plugins/devops-pipeline

---

Feature 8: Checkpoints

Checkpoints save session state so you can rewind to a known-good point.

In Claude Code:

/checkpoint save before-refactor
/checkpoint list
/checkpoint restore before-refactor

Use case — safe large refactoring:

1. /checkpoint save pre-auth-rewrite
2. Ask Claude to rewrite authentication module
3. Run tests: make test
4. If tests fail: /checkpoint restore pre-auth-rewrite

---

Feature 9: Advanced Features

Planning Mode

Force Claude to plan before acting:

/plan Refactor the user authentication module to use JWT tokens

Or in a slash command:

# Refactor Plan

Before making any changes:
1. Analyze the current implementation
2. Identify all affected files and dependencies
3. Write a step-by-step migration plan
4. Ask for approval before proceeding

Then execute the approved plan.

Extended Thinking

For complex problems, enable deep reasoning:

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=16000,
    thinking={
        "type": "enabled",
        "budget_tokens": 10000
    },
    messages=[{
        "role": "user",
        "content": "Design a distributed rate limiter for 10M req/s with Redis"
    }]
)

for block in response.content:
    if block.type == "thinking":
        print("Reasoning:", block.thinking)
    elif block.type == "text":
        print("Answer:", block.text)

Background Tasks

Long-running tasks that don't block your session:

/background Run the full test suite and report results when complete
/background Generate API documentation for all endpoints
/background Scan all Python files for security vulnerabilities

---

Feature 10: CLI Reference

Key Claude Code CLI commands and flags:

# Start interactive session
claude

# Run a one-shot prompt (non-interactive)
claude -p "Explain the auth middleware in src/middleware/auth.py"

# Run with a specific model
claude --model claude-opus-4-6

# Read-only mode (no file writes)
claude --read-only

# Output as JSON (for scripting)
claude -p "List all TODO comments" --output-format json

# Continue last session
claude --continue

# Resume a specific session
claude --resume <session-id>

# Set system prompt
claude --system-prompt "You are a security-focused reviewer"

# Pipe input
cat src/api.py | claude -p "Review this file for security issues"

# Run in a specific directory
claude --cwd /path/to/project

Scripting with Claude Code CLI:

#!/bin/bash
# ci-review.sh — Run Claude Code review in CI pipeline

FILES=$(git diff --name-only HEAD~1 HEAD | grep '\.py$')

for FILE in $FILES; do
  echo "Reviewing $FILE..."
  claude -p "Review $FILE for bugs and security issues. Output JSON." \
    --output-format json \
    --read-only \
    --cwd "$(pwd)" \
    >> review-results.json
done

echo "Review complete. Results in review-results.json"

---

Common Workflow Patterns

Pattern 1: Automated Code Review Pipeline

Slash Command (/review)
  → Subagent: security-auditor
  → Subagent: performance-reviewer
  → Hook (post-tool-use): format and post results
  → Memory: store findings in CLAUDE.md

.claude/commands/review.md:

# Full Code Review

Orchestrate a comprehensive review:

1. Delegate security analysis to the security-auditor agent
2. Delegate performance analysis to the performance-reviewer agent
3. Combine results into a single Markdown report
4. Save a summary to `.claude/review-log.md`

Format: Use severity badges (🔴 Critical, 🟠 High, 🟡 Medium, 🟢 Low)

Pattern 2: Safe Refactoring

# 1. Save checkpoint
# In Claude Code: /checkpoint save pre-refactor

# 2. Run refactor with planning mode
# /plan Refactor database layer to use async SQLAlchemy

# 3. Validate
make test

# 4. On failure, restore
# /checkpoint restore pre-refactor

Pattern 3: CI/CD Integration

# .github/workflows/claude-review.yml equivalent as shell

#!/bin/bash
# Run on every PR

PR_DIFF=$(git diff main...HEAD)

echo "$PR_DIFF" | claude \
  -p "Review this PR diff. Return JSON with: summary, risks, suggestions." \
  --output-format json \
  --read-only > pr-review.json

# Post results to PR via GitHub API
curl -X POST \
  -H "Authorization: Bearer $GITHUB_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"body\": \"$(cat pr-review.json | python3 -c 'import sys,json; d=json.load(sys.stdin); print(d[\"summary\"])')\"}" \
  "https://api.github.com/repos/$REPO/issues/$PR_NUMBER/comments"

---

Built-In Self-Assessment

Run directly inside Claude Code:

/self-assessment          # Full quiz — identifies your gaps and builds a personalized roadmap
/lesson-quiz hooks        # Quiz on hooks specifically
/lesson-quiz subagents    # Quiz on subagents
/lesson-quiz mcp          # Quiz on MCP protocol

---

Learning Path (Recommended Order)

Step	Module	Time
1	Slash Commands	30 min
2	Memory	45 min
3	Checkpoints	45 min
4	CLI Basics	30 min
5	Skills	1 hour
6	Hooks	1 hour
7	MCP	1 hour
8	Subagents	1.5 hours
9	Advanced Features	2–3 hours
10	Plugins	2 hours

---

Troubleshooting

Slash command not appearing:

• Verify the file is in .claude/commands/ (project) or ~/.claude/commands/ (global)
• Filename must end in .md
• Restart Claude Code session

CLAUDE.md not loading:

• Must be named exactly CLAUDE.md (case-sensitive)
• Place in project root or relevant subdirectory
• Check for YAML syntax errors if using frontmatter

Hook not triggering:

• Ensure hook script is executable: chmod +x .claude/hooks/myhook.sh
• Verify hook is registered in .claude/config.json
• Check hook output for errors: hooks that exit non-zero block the action

MCP server not connecting:

• Confirm environment variables are exported: echo $GITHUB_TOKEN
• Test the MCP server binary directly: npx -y @modelcontextprotocol/server-github
• Check .claude/mcp.json for JSON syntax errors

Subagent not delegating:

• Agent definition file must be in .claude/agents/
• Verify the orchestrator prompt explicitly references the agent by name
• Check that the agent .md file has a clear ## Role section

---

Resources

• Repo: https://github.com/luongnv89/claude-howto
• Learning Roadmap: LEARNING-ROADMAP.md
• Feature Catalog: CATALOG.md
• Claude Code Docs: https://code.claude.com
• Contributing: CONTRIBUTING.md
• License: MIT