claude-howto Documentation

1. Project Overview & Quickstart (luongnv89/claude-howto) Copy Chapter

File: README.md Copy Chapter

🌐 Language / Ngôn ngữ / 语言 / Мова: English | Tiếng Việt | 中文 | Українська | 日本語

Master Claude Code in a Weekend

Go from typing claude to orchestrating agents, hooks, skills, and MCP servers — with visual tutorials, copy-paste templates, and a guided learning path.

Get Started in 15 Minutes | Find Your Level | Browse the Feature Catalog

Table of Contents Copy Chapter

• The Problem
• How Claude How To Fixes This
• How It Works
• Not Sure Where to Start?
• Get Started in 15 Minutes
• What Can You Build With This?
• FAQ
• Contributing
• License

The Problem Copy Chapter

You installed Claude Code. You ran a few prompts. Now what?

• The official docs describe features — but don't show you how to combine them. You know slash commands exist, but not how to chain them with hooks, memory, and subagents into a workflow that actually saves hours.
• There's no clear learning path. Should you learn MCP before hooks? Skills before subagents? You end up skimming everything and mastering nothing.
• Examples are too basic. A "hello world" slash command doesn't help you build a production code review pipeline that uses memory, delegates to specialized agents, and runs security scans automatically.

You're leaving 90% of Claude Code's power on the table — and you don't know what you don't know.

How Claude How To Fixes This Copy Chapter

This isn't another feature reference. It's a structured, visual, example-driven guide that teaches you to use every Claude Code feature with real-world templates you can copy into your project today.

What you get: Copy Section

• 10 tutorial modules covering every Claude Code feature — from slash commands to custom agent teams
• Copy-paste configs — slash commands, CLAUDE.md templates, hook scripts, MCP configs, subagent definitions, and full plugin bundles
• Mermaid diagrams showing how each feature works internally, so you understand why, not just how
• A guided learning path that takes you from beginner to power user in 11-13 hours
• Built-in self-assessment — run /self-assessment or /lesson-quiz hooks directly in Claude Code to identify gaps

Start the Learning Path ->

How It Works Copy Chapter

1. Find your level Copy Section

Take the self-assessment quiz or run /self-assessment in Claude Code. Get a personalized roadmap based on what you already know.

2. Follow the guided path Copy Section

Work through 10 modules in order — each builds on the last. Copy templates directly into your project as you learn.

3. Combine features into workflows Copy Section

The real power is in combining features. Learn to wire slash commands + memory + subagents + hooks into automated pipelines that handle code reviews, deployments, and documentation generation.

4. Test your understanding Copy Section

Run /lesson-quiz [topic] after each module. The quiz pinpoints what you missed so you can fill gaps fast.

Get Started in 15 Minutes

Trusted by Developers Copy Chapter

• GitHub stars from developers who use Claude Code daily
• Forks from teams adapting this guide for their own workflows
• Actively maintained — synced with every Claude Code release (latest: v2.1.235, August 2026)
• Community-driven — contributions from developers who share their real-world configurations

Not Sure Where to Start? Copy Chapter

Take the self-assessment or pick your level:

Full learning path with all 10 modules:

Complete Learning Roadmap ->

Get Started in 15 Minutes Copy Chapter

Installation note: Starting in v2.1.113, Claude Code ships as a native per-platform binary (macOS/Linux/Windows). npm install @anthropic-ai/claude-code still works — the native binary is downloaded as an optional dep on first use. As of v2.1.116, downloads come from https://downloads.claude.ai/claude-code-releases — corporate proxies must allowlist this host.

# 1. Clone the guide
git clone https://github.com/luongnv89/claude-howto.git
cd claude-howto

# 2. Copy your first slash command
mkdir -p /path/to/your-project/.claude/commands
cp 01-slash-commands/optimize.md /path/to/your-project/.claude/commands/

# 3. Try it — in Claude Code, type:
# /optimize

# 4. Ready for more? Set up project memory:
cp 02-memory/project-CLAUDE.md /path/to/your-project/CLAUDE.md

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

Want the full setup? Here's the 1-hour essential setup:

# Slash commands (15 min)
cp 01-slash-commands/*.md .claude/commands/

# Project memory (15 min)
cp 02-memory/project-CLAUDE.md ./CLAUDE.md

# Install a skill (15 min)
cp -r 03-skills/code-review-specialist ~/.claude/skills/

# Weekend goal: add hooks, subagents, MCP, and plugins
# Follow the learning path for guided setup

View the Full Installation Reference

What Can You Build With This? Copy Chapter

FAQ Copy Chapter

Is this free?
Yes. MIT licensed, free forever. Use it in personal projects, at work, in your team — no restrictions beyond including the license notice.

Is this maintained?
Actively. The guide is synced with every Claude Code release. Current version: v2.1.220 (July 2026), compatible with Claude Code 2.1+.

How is this different from the official docs?
The official docs are a feature reference. This guide is a tutorial with diagrams, production-ready templates, and a progressive learning path. They complement each other — start here to learn, reference the docs when you need specifics.

How long does it take to go through everything?
11-13 hours for the full path. But you'll get immediate value in 15 minutes — just copy a slash command template and try it.

Can I use this with Claude Sonnet / Haiku / Opus?
Yes. All templates work with Claude Opus 5, Claude Sonnet 5, Claude Sonnet 4.6, Claude Opus 4.8, and Claude Haiku 4.5.

Can I contribute?
Absolutely. See CONTRIBUTING.md for guidelines. We welcome new examples, bug fixes, documentation improvements, and community templates.

Can I read this offline?
Yes. Run uv run scripts/build_epub.py to generate an EPUB ebook with all content and rendered diagrams.

Start Mastering Claude Code Today Copy Chapter

You already have Claude Code installed. The only thing between you and 10x productivity is knowing how to use it. This guide gives you the structured path, the visual explanations, and the copy-paste templates to get there.

MIT licensed. Free forever. Clone it, fork it, make it yours.

Start the Learning Path -> | Browse the Feature Catalog | Get Started in 15 Minutes

Quick Navigation — All Features

Feature Comparison

Installation Quick Reference

# 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-specialist ~/.claude/skills/

# Subagents
cp 04-subagents/*.md .claude/agents/

# MCP
export GITHUB_TOKEN="token"
claude mcp add github -- npx -y @modelcontextprotocol/server-github

# 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

1. Slash Commands

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

2. Memory

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

3. Skills

Location: 03-skills/

What: Reusable, auto-invoked capabilities with instructions and scripts

Examples:

• code-review-specialist/ - 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-specialist ~/.claude/skills/

# Project skills
cp -r 03-skills/code-review-specialist /path/to/project/.claude/skills/

Usage: Automatically invoked when relevant

4. Subagents

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

5. MCP Protocol

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://..."

# Add MCP server via CLI
claude mcp add github -- npx -y @modelcontextprotocol/server-github

# Or add to project .mcp.json manually (see 05-mcp/ for examples)

Usage: MCP tools are automatically available to Claude once configured

6. Hooks

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 hooks in ~/.claude/settings.json:

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Write",
      "hooks": ["~/.claude/hooks/format-code.sh"]
    }],
    "PostToolUse": [{
      "matcher": "Write",
      "hooks": ["~/.claude/hooks/security-scan.sh"]
    }]
  }
}

Usage: Hooks execute automatically on events

Hook Types (5): command, http, prompt, mcp_tool, agent — how a hook runs.

Hook Events (31, in 4 categories) — when it runs:

• Tool Hooks: PreToolUse, PostToolUse, PostToolUseFailure, PostToolBatch, PermissionRequest, PermissionDenied
• Session Hooks: SessionStart, Setup, SessionEnd, Stop, StopFailure, SubagentStart, SubagentStop
• Task Hooks: UserPromptSubmit, UserPromptExpansion, MessageDisplay, TaskCompleted, TaskCreated, TeammateIdle — TaskCompleted and TaskCreated only fire when the todo tools are enabled, which is off by default on Opus 4.8, Sonnet 5, Fable 5, Mythos 5, and newer models (CLAUDE_CODE_ENABLE_TODO_TOOLS=1 restores them)
• Lifecycle Hooks: ConfigChange, CwdChanged, DirectoryAdded, FileChanged, PreCompact, PostCompact, WorktreeCreate, WorktreeRemove, Notification, InstructionsLoaded, Elicitation, ElicitationResult

7. Plugins

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

8. Checkpoints and Rewind

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:

# Checkpoints are created automatically with every user prompt
# To rewind, press Esc twice or use:
/rewind

# Then choose from five options:
# 1. Restore code and conversation
# 2. Restore conversation
# 3. Restore code
# 4. Summarize from here
# 5. Never mind

Use Cases:

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

9. Advanced Features

Location: 09-advanced-features/

What: Advanced capabilities for complex workflows and automation

Includes:

• Planning Mode — Create detailed implementation plans before coding
• Extended Thinking — Deep reasoning for complex problems (toggle with Alt+T / Option+T)
• Background Tasks — Run long operations without blocking
• Permission Modes — manual (formerly default; default still accepted), acceptEdits, plan, auto, dontAsk, bypassPermissions
• Headless Mode — Run Claude Code in CI/CD: claude -p "Run tests and generate report"
• Session Management — /resume, /rename, /fork, /branch, claude -c, claude -r
• Configuration — Customize behavior in ~/.claude/settings.json

See config-examples.json for complete configurations.

10. CLI Reference

Location: 10-cli/

What: Complete command-line interface reference for Claude Code

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, batch processing, multi-session workflows, custom agent configurations

Example Workflows

Complete Code Review Workflow Copy Section

# 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

Automated Documentation Copy Section

# 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

DevOps Deployment Copy Section

# 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

Directory Structure

├── 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-specialist/
│   │   ├── 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)

Best Practices

Do's Copy Section

• 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'ts Copy Section

• 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

Troubleshooting

Feature Not Loading Copy Section

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

MCP Connection Failed Copy Section

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

Subagent Not Delegating Copy Section

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

Testing

This project includes comprehensive automated testing:

• 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/develop and every PR to main. See TESTING.md for detailed information.

EPUB Generation

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.

Contributing

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

Reporting Security Issues Copy Section

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

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.

Additional Resources

• Claude Code Documentation
• MCP Protocol Specification
• Skills Repository - Collection of ready-to-use skills
• Anthropic Cookbook
• 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.

Contributing Copy Chapter

We welcome contributions! Please see our Contributing Guide for details on how to get started.

License Copy Chapter

MIT License - see LICENSE. Free to use, modify, and distribute. The only requirement is including the license notice.

Last Updated: August 19, 2026
Claude Code Version: 2.1.235
Sources:

• https://code.claude.com/docs/en/hooks
• https://code.claude.com/docs/en/overview
• https://code.claude.com/docs/en/changelog
• https://code.claude.com/docs/en/permission-modes
• https://platform.claude.com/docs/en/about-claude/models/overview
• https://github.com/anthropics/claude-code/releases
• https://github.com/anthropics/claude-code/releases/tag/v2.1.154
• https://code.claude.com/docs/en/model-config
• https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md
  Compatible Models: Claude Fable 5, Claude Opus 5, Claude Sonnet 5, Claude Sonnet 4.6, Claude Opus 4.8, Claude Haiku 4.5

File: 01-slash-commands/README.md Copy Chapter

Slash Commands

Overview Copy Chapter

Slash commands are shortcuts that control Claude's behavior during an interactive session. They come in several types:

• Built-in commands: Provided by Claude Code (/help, /clear, /model)
• Skills: User-defined commands created as SKILL.md files (/optimize, /pr)
• Plugin commands: Commands from installed plugins (/frontend-design:frontend-design)
• MCP prompts: Commands from MCP servers (/mcp__github__list_prs)

Note: Custom slash commands have been merged into skills. Files in .claude/commands/ still work, but skills (.claude/skills/) are now the recommended approach. Both create /command-name shortcuts. See the Skills Guide for the full reference.

Built-in Commands Reference Copy Chapter

Built-in commands are shortcuts for common actions. There are 60+ built-in commands and 10 bundled skills available. Type / in Claude Code to see the full list, or type / followed by any letters to filter.

Why /cd matters: changing directories used to lose cache warmth (making the next turn slower and costlier); /cd preserves the prompt cache across the switch.

Bundled Skills Copy Section

These skills ship with Claude Code and are invoked like slash commands:

Deprecated Commands Copy Section

Recent Changes Copy Section

• /fork and /subtask swapped roles in v2.1.212. /fork now copies the conversation into a new independent background session; the forked-subagent behavior it used to have moved to the new /subtask command. History: /fork was an alias for /branch from v2.1.77 to v2.1.161; from v2.1.161 to v2.1.211 it started a forked subagent (what /subtask does now). When agent view is turned off, /subtask is unavailable and /fork keeps the forked-subagent behavior
• /resume (no arguments) opens a picker of past sessions — including ones removed from the visible list — and resumes the chosen one as a background session (v2.1.212)
• /output-style deprecated (v2.1.73) and removed (v2.1.91) — output styles are still available via /config → Output style or the outputStyle setting; the built-ins are Default, Proactive, Explanatory, and Learning
• /review became a full alias of /code-review — same targets, effort levels, and flags (v2.1.223). History: it first moved onto the /code-review medium engine in v2.1.186 while remaining PR-only
• /effort command added; max level available on Opus 4.6+ (originally Opus 4.6-only)
• /voice command added for push-to-talk voice dictation
• /schedule command added for creating/managing scheduled tasks
• /color command added for prompt bar customization
• /pr-comments removed in v2.1.91 — ask Claude directly to view PR comments
• /vim removed in v2.1.92 — use /config → Editor mode instead
• /ultraplan was removed in v2.1.222 — use plan mode instead
• /powerup added for interactive feature lessons
• /sandbox added for toggling sandbox mode
• /model picker now shows human-readable labels (e.g., "Sonnet 4.6") instead of raw model IDs
• /resume supports /continue alias
• MCP prompts are available as /mcp__<server>__ commands (see MCP Prompts as Commands)
• /team-onboarding added for auto-generating teammate ramp-up guides (v2.1.101)
• /tui command added for flicker-free fullscreen TUI rendering (v2.1.110)
• /focus command added for focus view toggle; Ctrl+O now only toggles verbose transcript (v2.1.110)
• /recap command added to manually trigger session context recap (v2.1.108)
• /undo added as alias for /rewind (v2.1.108)
• /proactive added as alias for /loop (v2.1.105)
• /effort gained interactive arrow-key slider and new xhigh level between high and max; default effort raised to xhigh for Opus 4.7 plans (v2.1.111). On Opus 4.8 the default is high (v2.1.154); Opus 5 also defaults to high (v2.1.219)
• /ultrareview added for comprehensive cloud-based multi-agent code review (v2.1.111)
• /fewer-permission-prompts added to analyze Bash/MCP tool calls and reduce permission prompts via an allowlist in .claude/settings.json (v2.1.111)
• Auto mode no longer requires the --enable-auto-mode flag for Max subscribers on Opus 4.7 (v2.1.112)
• /goal added — session-level completion condition that Claude works toward across turns; live overlay shows elapsed time, turn count, and token usage (v2.1.139)
• /scroll-speed added — tune mouse-wheel scroll speed of the TUI live-preview pane; persists per-machine (v2.1.139)
• /reload-skills added — re-scan skill directories without restarting the session (v2.1.152)
• /model now saves the selected model as the default for new sessions; press s for session-only (keybinding modelPicker:setAsDefault → modelPicker:thisSessionOnly) (v2.1.153)
• /workflows added — view running and completed dynamic workflow runs (v2.1.154)
• /simplify returned as a distinct cleanup-only review command (reuse / simplification / efficiency / altitude), separate from /code-review's bug hunt (v2.1.154)
• /status gained a Session kind row distinguishing attached and unattended background jobs from interactive sessions (v2.1.221)
• Plugin installs now activate immediately when it is safe to do so; /reload-plugins is only needed when the install summary asks for it (v2.1.221)
• /ultraplan removed — use plan mode (v2.1.222)
• /code-review and /review remember the last effort level you typed when you omit one (v2.1.223)
• /code-review ultra became the preferred entry point for cloud multi-agent review; /ultrareview stays as an alias (v2.1.223)
• /code-review at high, xhigh, and max effort now runs in a background agent like the other levels (v2.1.232)
• The startup tip suggesting you create custom subagents, and the matching nudge in the /powerup tour, were removed (v2.1.232)
• /permissions can now be opened while Claude is working — rule changes apply to the rest of the current turn (v2.1.234)
• /add-dir can now be used while Claude is working; the /add-dir, /autocompact, /theme, /help, /config, and /advisor dialogs open mid-turn in the fullscreen TUI, instead of queuing until Claude finishes responding (/bug already opened immediately, since v2.1.232) (v2.1.234)

`/goal` — Session-Level Completion Condition Copy Section

New in v2.1.139

Use /goal to register a completion condition for the current session. Claude works toward it across turns, and an overlay panel shows elapsed time, turn count, and tokens used. Clear it with /goal clear. Works in interactive mode, claude -p, and Remote Control.

User: /goal Migrate the payments service from REST to gRPC and get the integration tests passing.
Claude: Goal registered. I'll work toward this until you clear it.
[Goal panel: ⏱ 0s · turns 0 · tokens 0]

User: start by listing the REST endpoints
Claude: [does the work, panel updates]

Check-in on stalled background tasks (v2.1.234): while a goal is active, if a background task makes no progress for 30+ minutes, Claude checks in with a status update instead of silently continuing. Tune the threshold (in minutes) with the CLAUDE_CODE_GOAL_CHECKIN_MINUTES environment variable, or set it to 0 to disable check-ins entirely.

`/team-onboarding` — Teammate Ramp-Up Guide Copy Section

New in v2.1.101

Use /team-onboarding to generate a teammate ramp-up guide from your project's local Claude Code usage. The command inspects your CLAUDE.md, installed skills, subagents, hooks, and recent workflows, then produces an onboarding document that helps new developers become productive quickly.

It's a built-in command — nothing to install.

Usage:

claude /team-onboarding

The generated guide summarizes:

• Project purpose and key conventions from CLAUDE.md
• Available skills and when they are auto-invoked
• Configured subagents and their responsibilities
• Hooks that run on common events
• Common workflows newcomers should know about

Availability: Shipped in Claude Code v2.1.101 (April 11, 2026).

Custom Commands (Now Skills) Copy Chapter

Custom slash commands have been merged into skills. Both approaches create commands you can invoke with /command-name:

If a skill and a command share the same name, the skill takes precedence. For example, when both .claude/commands/review.md and .claude/skills/review/SKILL.md exist, the skill version is used.

Migration Path Copy Section

Your existing .claude/commands/ files continue to work without changes. To migrate to skills:

Before (Command):

.claude/commands/optimize.md

After (Skill):

.claude/skills/optimize/SKILL.md

Why Skills? Copy Section

Skills offer additional features over legacy commands:

• Directory structure: Bundle scripts, templates, and reference files
• Auto-invocation: Claude can trigger skills automatically when relevant
• Invocation control: Choose whether users, Claude, or both can invoke
• Subagent execution: Run skills in isolated contexts with context: fork
• Progressive disclosure: Load additional files only when needed

Creating a Custom Command as a Skill Copy Section

Create a directory with a SKILL.md file:

mkdir -p .claude/skills/my-command

File: .claude/skills/my-command/SKILL.md

---
name: my-command
---

# My Command

Instructions for Claude to follow when this command is invoked.

1. First step
2. Second step
3. Third step

Frontmatter Reference Copy Section

Arguments Copy Section

Commands can receive arguments:

All arguments with $ARGUMENTS:

---
name: fix-issue
---

Fix issue #$ARGUMENTS following our coding standards

Usage: /fix-issue 123 → $ARGUMENTS becomes "123"

Individual arguments with $0, $1, etc.:

---
name: review-pr
---

Review PR #$0 with priority $1

Usage: /review-pr 456 high → $0="456", $1="high"

${CLAUDE_PROJECT_DIR} resolves to the absolute path of the project root (v2.1.196).

Dynamic Context with Shell Commands Copy Section

Execute bash commands before the prompt using !`command`:

---
name: commit
allowed-tools: Bash(git *)
---

## Context

- Current git status: !`git status`
- Current git diff: !`git diff HEAD`
- Current branch: !`git branch --show-current`
- Recent commits: !`git log --oneline -5`

## Your task

Based on the above changes, create a single git commit.

File References Copy Section

Include file contents using @:

Review the implementation in @src/utils/helpers.js
Compare @src/old-version.js with @src/new-version.js

Plugin Commands Copy Chapter

Plugins can provide custom commands:

/plugin-name:command-name

Or simply /command-name when there are no naming conflicts.

Examples:

/frontend-design:frontend-design
/commit-commands:commit

MCP Prompts as Commands Copy Chapter

MCP servers can expose prompts as slash commands:

/mcp__<server-name>__ [arguments]

Examples:

/mcp__github__list_prs
/mcp__github__pr_review 456
/mcp__jira__create_issue "Bug title" high

MCP Permission Syntax Copy Section

Control MCP server access in permissions:

• mcp__github - Access entire GitHub MCP server
• mcp__github__* - Wildcard access to all tools
• mcp__github__get_issue - Specific tool access

Command Architecture Copy Chapter

graph TD
    A["User Input: /command-name"] --> B{"Command Type?"}
    B -->|Built-in| C["Execute Built-in"]
    B -->|Skill| D["Load SKILL.md"]
    B -->|Plugin| E["Load Plugin Command"]
    B -->|MCP| F["Execute MCP Prompt"]

    D --> G["Parse Frontmatter"]
    G --> H["Substitute Variables"]
    H --> I["Execute Shell Commands"]
    I --> J["Send to Claude"]
    J --> K["Return Results"]

Command Lifecycle Copy Chapter

sequenceDiagram
    participant User
    participant Claude as Claude Code
    participant FS as File System
    participant CLI as Shell/Bash

    User->>Claude: Types /optimize
    Claude->>FS: Searches .claude/skills/ and .claude/commands/
    FS-->>Claude: Returns optimize/SKILL.md
    Claude->>Claude: Parses frontmatter
    Claude->>CLI: Executes !`command` substitutions
    CLI-->>Claude: Command outputs
    Claude->>Claude: Substitutes $ARGUMENTS
    Claude->>User: Processes prompt
    Claude->>User: Returns results

Available Commands in This Folder Copy Chapter

These example commands can be installed as skills or legacy commands.

1. `/optimize` - Code Optimization Copy Section

Analyzes code for performance issues, memory leaks, and optimization opportunities.

Usage:

/optimize
[Paste your code]

2. `/pr` - Pull Request Preparation Copy Section

Guides through PR preparation checklist including linting, testing, and commit formatting.

Usage:

/pr

Screenshot:

3. `/generate-api-docs` - API Documentation Generator Copy Section

Generates comprehensive API documentation from source code.

Usage:

/generate-api-docs

4. `/commit` - Git Commit with Context Copy Section

Creates a git commit with dynamic context from your repository.

Usage:

/commit [optional message]

5. `/push-all` - Stage, Commit, and Push Copy Section

Stages all changes, creates a commit, and pushes to remote with safety checks.

Usage:

/push-all

Safety Checks:

• Secrets: .env*, *.key, *.pem, credentials.json
• API Keys: Detects real keys vs. placeholders
• Large files: >10MB without Git LFS
• Build artifacts: node_modules/, dist/, __pycache__/

6. `/doc-refactor` - Documentation Restructuring Copy Section

Restructures project documentation for clarity and accessibility.

Usage:

/doc-refactor

7. `/setup-ci-cd` - CI/CD Pipeline Setup Copy Section

Implements pre-commit hooks and GitHub Actions for quality assurance.

Usage:

/setup-ci-cd

8. `/unit-test-expand` - Test Coverage Expansion Copy Section

Increases test coverage by targeting untested branches and edge cases.

Usage:

/unit-test-expand

Installation Copy Chapter

As Skills (Recommended) Copy Section

Copy to your skills directory:

# Create skills directory
mkdir -p .claude/skills

# For each command file, create a skill directory
for cmd in optimize pr commit; do
  mkdir -p .claude/skills/$cmd
  cp 01-slash-commands/$cmd.md .claude/skills/$cmd/SKILL.md
done

As Legacy Commands Copy Section

Copy to your commands directory:

# Project-wide (team)
mkdir -p .claude/commands
cp 01-slash-commands/*.md .claude/commands/

# Personal use
mkdir -p ~/.claude/commands
cp 01-slash-commands/*.md ~/.claude/commands/

Creating Your Own Commands Copy Chapter

Skill Template (Recommended) Copy Section

Create .claude/skills/my-command/SKILL.md:

---
name: my-command
argument-hint: [optional-args]
allowed-tools: Bash(npm *), Read, Grep
---

# Command Title

## Context

- Current branch: !`git branch --show-current`
- Related files: @package.json

## Instructions

1. First step
2. Second step with argument: $ARGUMENTS
3. Third step

## Output Format

- How to format the response
- What to include

User-Only Command (No Auto-Invocation) Copy Section

For commands with side effects that Claude shouldn't trigger automatically:

---
name: deploy
disable-model-invocation: true
allowed-tools: Bash(npm *), Bash(git *)
---

Deploy the application to production:

1. Run tests
2. Build application
3. Push to deployment target
4. Verify deployment

Best Practices Copy Chapter

Troubleshooting Copy Chapter

Command Not Found Copy Section

Solutions:

• Check file is in .claude/skills/<name>/SKILL.md or .claude/commands/<name>.md
• Verify the name field in frontmatter matches expected command name
• Restart Claude Code session
• Run /help to see available commands

Command Not Executing as Expected Copy Section

Solutions:

• Add more specific instructions
• Include examples in the skill file
• Check allowed-tools if using bash commands
• Test with simple inputs first

Skill vs Command Conflict Copy Section

If both exist with the same name, the skill takes precedence. Remove one or rename it.

Related Guides Copy Chapter

• Skills - Full reference for skills (auto-invoked capabilities)
• Memory - Persistent context with CLAUDE.md
• Subagents - Delegated AI agents
• Plugins - Bundled command collections
• Hooks - Event-driven automation

Additional Resources Copy Chapter

• Official Interactive Mode Documentation - Built-in commands reference
• Official Skills Documentation - Complete skills reference
• CLI Reference - Command-line options

Last Updated: August 19, 2026
Claude Code Version: 2.1.235
Sources:

• https://code.claude.com/docs/en/skills
• https://code.claude.com/docs/en/interactive-mode
• https://code.claude.com/docs/en/changelog
• https://code.claude.com/docs/en/commands
• https://code.claude.com/docs/en/model-config
• https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md
• https://github.com/anthropics/claude-code/releases/tag/v2.1.139
• https://github.com/anthropics/claude-code/releases/tag/v2.1.144
• https://github.com/anthropics/claude-code/releases/tag/v2.1.152
• https://github.com/anthropics/claude-code/releases/tag/v2.1.153
• https://github.com/anthropics/claude-code/releases/tag/v2.1.154
  Compatible Models: Claude Fable 5, Claude Opus 5, Claude Sonnet 5, Claude Sonnet 4.6, Claude Opus 4.8, Claude Haiku 4.5

Part of the Claude How To guide series

File: 02-memory/README.md Copy Chapter

Memory Guide

Memory enables Claude to retain context across sessions and conversations. It exists in two forms: automatic synthesis in claude.ai, and filesystem-based CLAUDE.md in Claude Code.

Overview Copy Chapter

Memory in Claude Code provides persistent context that carries across multiple sessions and conversations. Unlike temporary context windows, memory files allow you to:

• Share project standards across your team
• Store personal development preferences
• Maintain directory-specific rules and configurations
• Import external documentation
• Version control memory as part of your project

The memory system operates at multiple levels, from global personal preferences down to specific subdirectories, allowing for fine-grained control over what Claude remembers and how it applies that knowledge.

Memory Commands Quick Reference Copy Chapter

Quick Start: Initializing Memory Copy Chapter

The `/init` Command Copy Section

The /init command is the fastest way to set up project memory in Claude Code. It initializes a CLAUDE.md file with foundational project documentation.

Usage:

/init

What it does:

• Creates a new CLAUDE.md file in your project (typically at ./CLAUDE.md or ./.claude/CLAUDE.md)
• Establishes project conventions and guidelines
• Sets up the foundation for context persistence across sessions
• Provides a template structure for documenting your project standards

Enhanced interactive mode: Set CLAUDE_CODE_NEW_INIT=1 to enable a multi-phase interactive flow that walks you through project setup step by step:

CLAUDE_CODE_NEW_INIT=1 claude
/init

When to use /init:

• Starting a new project with Claude Code
• Establishing team coding standards and conventions
• Creating documentation about your codebase structure
• Setting up memory hierarchy for collaborative development

Example workflow:

# In your project directory
/init

# Claude creates CLAUDE.md with structure like:
# Project Configuration
## Project Overview
- Name: Your Project
- Tech Stack: [Your technologies]
- Team Size: [Number of developers]

## Development Standards
- Code style preferences
- Testing requirements
- Git workflow conventions

Quick Memory Updates Copy Section

Note: The # shortcut for inline memory was discontinued. Use /memory to edit memory files directly, or ask Claude conversationally to remember something (e.g., "remember that we always use TypeScript strict mode").

The recommended ways to add information to memory are:

Option 1: Use /memory command

/memory

Opens your memory files in your system editor for direct editing.

Option 2: Ask conversationally

Remember that we always use TypeScript strict mode in this project.
Please add to memory: prefer async/await over promise chains.

Claude will update the appropriate CLAUDE.md file based on your request.

Historical reference (no longer functional):

The # prefix shortcut previously allowed adding rules inline:

# Always use TypeScript strict mode in this project  ← no longer works

If you relied on this pattern, switch to the /memory command or conversational requests.

The `/memory` Command Copy Section

The /memory command provides direct access to edit your CLAUDE.md memory files within Claude Code sessions. It opens your memory files in your system editor for comprehensive editing. When the file opens in a GUI editor, the session no longer blocks while the file stays open, so you can keep working in parallel (v2.1.216); terminal editors like Vim still take over the terminal until you exit.

Usage:

/memory

What it does:

• Opens your memory files in your system's default editor
• Allows you to make extensive additions, modifications, and reorganizations
• Provides direct access to all memory files in the hierarchy
• Enables you to manage persistent context across sessions

When to use /memory:

• Reviewing existing memory content
• Making extensive updates to project standards
• Reorganizing memory structure
• Adding detailed documentation or guidelines
• Maintaining and updating memory as your project evolves

Comparison: /memory vs /init

Example workflow:

# Open memory for editing
/memory

# Claude presents options:
# 1. Managed Policy Memory
# 2. Project Memory (./CLAUDE.md)
# 3. User Memory (~/.claude/CLAUDE.md)
# 4. Local Project Memory

# Choose option 2 (Project Memory)
# Your default editor opens with ./CLAUDE.md content

# Make changes, save, and close editor
# Claude automatically reloads the updated memory

Using Memory Imports:

CLAUDE.md files support the @path/to/file syntax to include external content:

# Project Documentation
See @README.md for project overview
See @package.json for available npm commands
See @docs/architecture.md for system design

# Import from home directory using absolute path
@~/.claude/my-project-instructions.md

Import features:

• Both relative and absolute paths are supported (e.g., @docs/api.md or @~/.claude/my-project-instructions.md)
• Recursive imports are supported with a maximum depth of 4 hops
• First-time imports from external locations trigger an approval dialog for security
• Import directives are not evaluated inside markdown code spans or code blocks (so documenting them in examples is safe)
• Helps avoid duplication by referencing existing documentation
• Automatically includes referenced content in Claude's context

Memory Architecture Copy Chapter

Memory in Claude Code follows a hierarchical system where different scopes serve different purposes. Unlike Claude Web/Desktop's 24-hour synthesis cycle (see Memory in Claude Web/Desktop below), Claude Code has two memory systems that both load at the start of every session and update continuously, not on a timer:

graph TB
    A["Session Start"]
    B["CLAUDE.md Files(you write)"]
    C["Auto Memory(Claude writes)"]
    D["Claude Session"]
    E["Your Correction /Preference"]

    B -->|loaded in full| A
    C -->|MEMORY.md loaded| A
    A --> D
    D -->|"Remember that..."| E
    E -->|writes during session| C
    D -->|"add this to CLAUDE.md"| B

Memory Hierarchy in Claude Code Copy Chapter

Claude Code has two complementary memory systems, both loaded at the start of every conversation: CLAUDE.md files (instructions you write) and auto memory (notes Claude writes itself). CLAUDE.md files are concatenated into context rather than overriding each other — this is not a strict precedence chain where a higher tier replaces a lower one. .claude/rules/*.md files are a separate, related mechanism for topic- or path-scoped instructions.

CLAUDE.md file locations, in load order (broadest scope to most specific):

Within the directory tree, Claude Code walks up from your working directory: foo/CLAUDE.md loads before foo/bar/CLAUDE.md if you launch from foo/bar/, so instructions closer to where you launched are read last — not "highest priority" in an override sense, just most recent in context. Within each directory, CLAUDE.local.md is appended after CLAUDE.md. CLAUDE.md and CLAUDE.local.md files in subdirectories under your working directory load on demand, when Claude reads files in those subdirectories, rather than at launch.

Organizations can also put managed CLAUDE.md content directly inside managed-settings.json via the claudeMd key, instead of deploying a separate file. This is honored only in managed/policy settings — setting claudeMd in user or project settings has no effect.

.claude/rules/*.md — modular, topic-specific instructions, optionally scoped to file paths via paths frontmatter. Rules without a paths field load unconditionally with the same priority as .claude/CLAUDE.md; path-scoped rules load on demand when Claude reads a matching file. User-level rules (~/.claude/rules/) load before project rules.

Auto memory (~/.claude/projects//memory/) is a separate system: Claude's own notes, not CLAUDE.md content, and not part of the concatenation order above. See Auto Memory below.

Note: CLAUDE.local.md is fully supported and documented in the official documentation. It provides personal project-specific preferences that are not committed to version control. Add CLAUDE.local.md to your .gitignore.

Memory Discovery Behavior:

graph TD
    A["Managed Policy/Library/.../ClaudeCode/CLAUDE.md"] -->|loads first| B["User Instructions~/.claude/CLAUDE.md"]
    B --> C["Project Instructions./CLAUDE.md or ./.claude/CLAUDE.md"]
    C --> D["Local Instructions./CLAUDE.local.md"]

    C -->|imports| H["@docs/architecture.md"]
    H -->|imports| I["@docs/api-standards.md"]

    style A fill:#fce4ec,stroke:#333,color:#333
    style B fill:#f3e5f5,stroke:#333,color:#333
    style C fill:#e1f5fe,stroke:#333,color:#333
    style D fill:#e8f5e9,stroke:#333,color:#333
    style H fill:#e1f5fe,stroke:#333,color:#333
    style I fill:#e1f5fe,stroke:#333,color:#333

All files shown are concatenated into one context, not selected by override — later boxes appear later in context, not "instead of" earlier ones.

Excluding CLAUDE.md Files with `claudeMdExcludes` Copy Chapter

In large monorepos, some CLAUDE.md files may be irrelevant to your current work. The claudeMdExcludes setting lets you skip specific CLAUDE.md files so they are not loaded into context:

// In ~/.claude/settings.json or .claude/settings.json
{
  "claudeMdExcludes": [
    "packages/legacy-app/CLAUDE.md",
    "vendors/**/CLAUDE.md"
  ]
}

Patterns are matched against paths relative to the project root. This is particularly useful for:

• Monorepos with many sub-projects, where only some are relevant
• Repositories that contain vendored or third-party CLAUDE.md files
• Reducing noise in Claude's context window by excluding stale or unrelated instructions

Settings File Hierarchy Copy Chapter

Claude Code settings (including autoMemoryDirectory, claudeMdExcludes, and other configuration) resolve by precedence — unlike CLAUDE.md files above, settings genuinely override rather than concatenate. When the same setting appears in multiple scopes, the higher level wins:

Managed settings also support a drop-in directory, managed-settings.d/, alongside managed-settings.json: the base file merges first, then *.json files in the drop-in directory merge on top in alphabetical order (scalars override, arrays concatenate and de-duplicate, objects deep-merge). This lets separate teams deploy independent policy fragments without editing a shared file. Note this is a settings.json mechanism, not a CLAUDE.md one — it doesn't apply to the CLAUDE.md file locations described above.

Permission rules (allow/ask/deny) behave differently from other settings: they merge across scopes instead of the higher level replacing the lower one.

Platform-specific configuration (v2.1.51+):

Settings can also be configured via:

• macOS: Property list (plist) files
• Windows: Windows Registry

These platform-native mechanisms are read alongside JSON settings files and follow the same precedence rules.

Note (v2.1.119): /config changes now persist to ~/.claude/settings.json. Values written via /config participate in the normal policy/local/project precedence chain described above — they are no longer session-only. Use /config for interactive edits and edit settings.json files directly for scripted or managed configuration.

Retention and Cleanup Settings Copy Section

// ~/.claude/settings.json
{
  "cleanupPeriodDays": 14
}

Attribution, Voice, and PR URL Settings Copy Section

// ~/.claude/settings.json
{
  "attribution": {
    "commit": false,
    "pr": true
  },
  "voice": {
    "enabled": true
  },
  "prUrlTemplate": "https://gitlab.internal/{{owner}}/{{repo}}/-/merge_requests/{{number}}"
}

Deprecated setting names

The following legacy setting keys still work but are deprecated. Prefer the replacements above.

Modular Rules System Copy Chapter

Create organized, path-specific rules using the .claude/rules/ directory structure. Rules can be defined at both the project level and user level:

your-project/
├── .claude/
│   ├── CLAUDE.md
│   └── rules/
│       ├── code-style.md
│       ├── testing.md
│       ├── security.md
│       └── api/                  # Subdirectories supported
│           ├── conventions.md
│           └── validation.md

~/.claude/
├── CLAUDE.md
└── rules/                        # User-level rules (all projects)
    ├── personal-style.md
    └── preferred-patterns.md

Rules are discovered recursively within the rules/ directory, including any subdirectories. User-level rules at ~/.claude/rules/ are loaded before project-level rules, allowing personal defaults that projects can override.

Path-Specific Rules with YAML Frontmatter Copy Section

Define rules that apply only to specific file paths:

---
paths: src/api/**/*.ts
---

# API Development Rules

- All API endpoints must include input validation
- Use Zod for schema validation
- Document all parameters and response types
- Include error handling for all operations

Glob Pattern Examples:

• **/*.ts - All TypeScript files
• src/**/* - All files under src/
• src/**/*.{ts,tsx} - Multiple extensions
• {src,lib}/**/*.ts, tests/**/*.test.ts - Multiple patterns

Subdirectories and Symlinks Copy Section

Rules in .claude/rules/ support two organizational features:

• Subdirectories: Rules are discovered recursively, so you can organize them into topic-based folders (e.g., rules/api/, rules/testing/, rules/security/)
• Symlinks: Symlinks are supported for sharing rules across multiple projects. For example, you can symlink a shared rule file from a central location into each project's .claude/rules/ directory

Memory Locations Table Copy Chapter

CLAUDE.md files and rules are concatenated into context, not selected by strict override — "Load order" below means where in context it appears, not which one wins. Auto memory is a separate mechanism with its own storage location.

Memory Update Lifecycle Copy Chapter

Here's how memory updates flow through your Claude Code sessions:

sequenceDiagram
    participant User
    participant Claude as Claude Code
    participant Editor as File System
    participant Memory as CLAUDE.md

    User->>Claude: "Remember: use async/await"
    Claude->>User: "Which memory file?"
    User->>Claude: "Project memory"
    Claude->>Editor: Open ~/.claude/settings.json
    Claude->>Memory: Write to ./CLAUDE.md
    Memory-->>Claude: File saved
    Claude->>Claude: Load updated memory
    Claude-->>User: "Memory saved!"

Auto Memory Copy Chapter

Auto memory is a persistent directory where Claude automatically records learnings, patterns, and insights as it works with your project. Unlike CLAUDE.md files which you write and maintain manually, auto memory is written by Claude itself during sessions.

How Auto Memory Works Copy Section

• Location: ~/.claude/projects//memory/
• Entrypoint: MEMORY.md serves as the main file in the auto memory directory
• Topic files: Optional additional files for specific subjects (e.g., debugging.md, api-conventions.md)
• Loading behavior: The first 200 lines of MEMORY.md (or first 25KB, whichever comes first) are loaded into context at session start. Topic files are loaded on demand, not at startup.
• Read/write: Claude reads and writes memory files during sessions as it discovers patterns and project-specific knowledge
• Frontmatter: Files that begin with YAML frontmatter get a modified field — an ISO 8601 timestamp Claude Code records each time it writes the file (v2.1.214)

Auto Memory Architecture Copy Section

graph TD
    A["Claude Session Starts"] --> B["Load MEMORY.md(first 200 lines / 25KB)"]
    B --> C["Session Active"]
    C --> D["Claude discoverspatterns & insights"]
    D --> E{"Write toauto memory"}
    E -->|General notes| F["MEMORY.md"]
    E -->|Topic-specific| G["debugging.md"]
    E -->|Topic-specific| H["api-conventions.md"]
    C --> I["On-demand loadtopic files"]
    I --> C

    style A fill:#e1f5fe,stroke:#333,color:#333
    style B fill:#e1f5fe,stroke:#333,color:#333
    style C fill:#e8f5e9,stroke:#333,color:#333
    style D fill:#f3e5f5,stroke:#333,color:#333
    style E fill:#fff3e0,stroke:#333,color:#333
    style F fill:#fce4ec,stroke:#333,color:#333
    style G fill:#fce4ec,stroke:#333,color:#333
    style H fill:#fce4ec,stroke:#333,color:#333
    style I fill:#f3e5f5,stroke:#333,color:#333

Auto Memory Directory Structure Copy Section

~/.claude/projects//memory/
├── MEMORY.md              # Entrypoint (first 200 lines / 25KB loaded at startup)
├── debugging.md           # Topic file (loaded on demand)
├── api-conventions.md     # Topic file (loaded on demand)
└── testing-patterns.md    # Topic file (loaded on demand)

Version Requirement Copy Section

Auto memory requires Claude Code v2.1.59 or later. If you are on an older version, upgrade first:

npm install @anthropic-ai/claude-code@latest

Turning Auto Memory On or Off Copy Section

Auto memory is on by default. The autoMemoryEnabled setting (default true) controls it; when false, Claude neither reads from nor writes to the auto memory directory. You can also toggle it with /memory during a session.

{
  "autoMemoryEnabled": false
}

To disable it via environment instead, set CLAUDE_CODE_DISABLE_AUTO_MEMORY=1. Setting it to 0 forces auto memory on even when --bare mode or autoMemoryEnabled: false would otherwise disable it.

Custom Auto Memory Directory Copy Section

By default, auto memory is stored in ~/.claude/projects//memory/. You can change this location using the autoMemoryDirectory setting (available since v2.1.74):

// In ~/.claude/settings.json or .claude/settings.local.json (user/local settings only)
{
  "autoMemoryDirectory": "/path/to/custom/memory/directory"
}

Note: autoMemoryDirectory can only be set in user-level (~/.claude/settings.json) or local settings (.claude/settings.local.json), not in project or managed policy settings.

This is useful when you want to:

• Store auto memory in a shared or synced location
• Separate auto memory from the default Claude configuration directory
• Use a project-specific path outside the default hierarchy

Worktree and Repository Sharing Copy Section

All worktrees and subdirectories within the same git repository share a single auto memory directory. This means switching between worktrees or working in different subdirectories of the same repo will read and write to the same memory files.

Subagent Memory Copy Section

Subagents (spawned via tools like Task or parallel execution) can have their own memory context. Use the memory frontmatter field in the subagent definition to specify which memory scopes to load:

memory: user      # Load user-level memory only
memory: project   # Load project-level memory only
memory: local     # Load local memory only

This allows subagents to operate with focused context rather than inheriting the full memory hierarchy.

Note: Subagents can also maintain their own auto memory. See the official subagent memory documentation for details.

Controlling Auto Memory Copy Section

Auto memory can be controlled via the CLAUDE_CODE_DISABLE_AUTO_MEMORY environment variable:

# Disable auto memory for a session
CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 claude

# Force auto memory on explicitly
CLAUDE_CODE_DISABLE_AUTO_MEMORY=0 claude

Additional Directories with `--add-dir` Copy Chapter

The --add-dir flag allows Claude Code to load CLAUDE.md files from additional directories beyond the current working directory. This is useful for monorepos or multi-project setups where context from other directories is relevant.

To enable this feature, set the environment variable:

CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1

Then launch Claude Code with the flag:

claude --add-dir /path/to/other/project

Claude will load CLAUDE.md from the specified additional directory alongside the memory files from your current working directory.

Practical Examples Copy Chapter

Example 1: Project Memory Structure Copy Section

File: ./CLAUDE.md

/* Detailed source-code truncated for AI context efficiency. */

Example 2: Directory-Specific Memory Copy Section

File: ./src/api/CLAUDE.md

# API Module Standards

This file overrides root CLAUDE.md for everything in /src/api/

## API-Specific Standards

### Request Validation
- Use Zod for schema validation
- Always validate input
- Return 400 with validation errors
- Include field-level error details

### Authentication
- All endpoints require JWT token
- Token in Authorization header
- Token expires after 24 hours
- Implement refresh token mechanism

### Response Format

All responses must follow this structure:

```json
{
  "success": true,
  "data": { /* actual data */ },
  "timestamp": "2025-11-06T10:30:00Z",
  "version": "1.0"
}
```

Error responses:
```json
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "User message",
    "details": { /* field errors */ }
  },
  "timestamp": "2025-11-06T10:30:00Z"
}
```

### Pagination
- Use cursor-based pagination (not offset)
- Include `hasMore` boolean
- Limit max page size to 100
- Default page size: 20

### Rate Limiting
- 1000 requests per hour for authenticated users
- 100 requests per hour for public endpoints
- Return 429 when exceeded
- Include retry-after header

### Caching
- Use Redis for session caching
- Cache duration: 5 minutes default
- Invalidate on write operations
- Tag cache keys with resource type

Example 3: Personal Memory Copy Section

File: ~/.claude/CLAUDE.md

# My Development Preferences

## About Me
- **Experience Level**: 8 years full-stack development
- **Preferred Languages**: TypeScript, Python
- **Communication Style**: Direct, with examples
- **Learning Style**: Visual diagrams with code

## Code Preferences

### Error Handling
I prefer explicit error handling with try-catch blocks and meaningful error messages.
Avoid generic errors. Always log errors for debugging.

### Comments
Use comments for WHY, not WHAT. Code should be self-documenting.
Comments should explain business logic or non-obvious decisions.

### Testing
I prefer TDD (test-driven development).
Write tests first, then implementation.
Focus on behavior, not implementation details.

### Architecture
I prefer modular, loosely-coupled design.
Use dependency injection for testability.
Separate concerns (Controllers, Services, Repositories).

## Debugging Preferences
- Use console.log with prefix: `[DEBUG]`
- Include context: function name, relevant variables
- Use stack traces when available
- Always include timestamps in logs

## Communication
- Explain complex concepts with diagrams
- Show concrete examples before explaining theory
- Include before/after code snippets
- Summarize key points at the end

## Project Organization
I organize my projects as:

   project/
   ├── src/
   │   ├── api/
   │   ├── services/
   │   ├── models/
   │   └── utils/
   ├── tests/
   ├── docs/
   └── docker/

## Tooling
- **IDE**: VS Code with vim keybindings
- **Terminal**: Zsh with Oh-My-Zsh
- **Format**: Prettier (100 char line length)
- **Linter**: ESLint with airbnb config
- **Test Framework**: Jest with React Testing Library

My Test
Ask Claude to save a new rule

Claude has not save the rule because I did not have any Claude.md file anywhere. Then asked Claude to confirm the location.

Example 4: Memory Update During Session Copy Section

You can add new rules to memory during an active Claude Code session by asking conversationally:

User: Remember that I prefer using React hooks instead of class components
     for all new components.

Claude: I'm adding that to your memory. Which memory file should this go in?
        1. Project memory (./CLAUDE.md)
        2. Personal memory (~/.claude/CLAUDE.md)

User: Project memory

Claude: ✅ Memory saved!

Added to ./CLAUDE.md:
---

### Component Development
- Use functional components with React Hooks
- Prefer hooks over class components
- Custom hooks for reusable logic
- Use useCallback for event handlers
- Use useMemo for expensive computations

Or use /memory to edit memory files directly for extensive updates or reorganization.

Tips for Adding Memory

• Be specific and actionable in your rules
• Group related rules together under a section header
• Update existing sections instead of duplicating content
• Choose the appropriate memory scope (project vs. personal)

Memory Features Comparison Copy Chapter

Memory in Claude Web/Desktop Copy Section

Memory Synthesis Timeline

graph LR
    A["Day 1: UserConversations"] -->|24 hours| B["Day 2: MemorySynthesis"]
    B -->|Automatic| C["Memory UpdatedSummarized"]
    C -->|Loaded in| D["Day 2-N:New Conversations"]
    D -->|Add to| E["Memory"]
    E -->|24 hours later| F["Memory Refreshed"]

Example Memory Summary:

## Claude's Memory of User

### Professional Background
- Senior full-stack developer with 8 years experience
- Focus on TypeScript/Node.js backends and React frontends
- Active open source contributor
- Interested in AI and machine learning

### Project Context
- Currently building e-commerce platform
- Tech stack: Node.js, PostgreSQL, React 18, Docker
- Working with team of 5 developers
- Using CI/CD and blue-green deployments

### Communication Preferences
- Prefers direct, concise explanations
- Likes visual diagrams and examples
- Appreciates code snippets
- Explains business logic in comments

### Current Goals
- Improve API performance
- Increase test coverage to 90%
- Implement caching strategy
- Document architecture

Best Practices Copy Chapter

Do's - What To Include Copy Section

• Be specific and detailed: Use clear, detailed instructions rather than vague guidance

  • ✅ Good: "Use 2-space indentation for all JavaScript files"
  • ❌ Avoid: "Follow best practices"

• Keep organized: Structure memory files with clear markdown sections and headings

• Use appropriate hierarchy levels:

  • Managed policy: Company-wide policies, security standards, compliance requirements
  • Project memory: Team standards, architecture, coding conventions (commit to git)
  • User memory: Personal preferences, communication style, tooling choices
  • Directory memory: Module-specific rules and overrides

• Leverage imports: Use @path/to/file syntax to reference existing documentation

  • Supports a maximum depth of 4 hops for recursive imports
  • Avoids duplication across memory files
  • Example: See @README.md for project overview

• Document frequent commands: Include commands you use repeatedly to save time

• Version control project memory: Commit project-level CLAUDE.md files to git for team benefit

• Review periodically: Update memory regularly as projects evolve and requirements change

• Provide concrete examples: Include code snippets and specific scenarios

Don'ts - What To Avoid Copy Section

• Don't store secrets: Never include API keys, passwords, tokens, or credentials

• Don't include sensitive data: No PII, private information, or proprietary secrets

• Don't duplicate content: Use imports (@path) to reference existing documentation instead

• Don't be vague: Avoid generic statements like "follow best practices" or "write good code"

• Don't make it too long: Target under 200 lines per CLAUDE.md. Longer files still load in full, but adherence drops — see Keeping CLAUDE.md small below

• Don't over-organize: Use hierarchy strategically; don't create excessive subdirectory overrides

• Don't forget to update: Stale memory can cause confusion and outdated practices

• Don't exceed nesting limits: Memory imports support a maximum depth of 4 hops

Keeping CLAUDE.md Small Copy Section

Anthropic's current guidance is the opposite of "put everything in CLAUDE.md". The file loads into every session, so every line you add is a line that competes for attention on tasks it has nothing to do with.

Rule of thumb: keep CLAUDE.md under 200 lines. Longer files still load in full, but instruction adherence degrades as the file grows.

When it starts growing, move content out rather than trimming prose:

Note: @path imports organize a large CLAUDE.md but do not save context — imported files are pulled in at load time just the same. Splitting into path-scoped rules is what actually reduces what loads.

/doctor (v2.1.206+) inspects your configuration and proposes trims when CLAUDE.md has grown past the point of usefulness.

Don't Write Verification Reminders Copy Section

Older guidance encouraged lines like "always run the tests before saying you're done" or "double-check your work". On Claude Opus 5 and Fable 5 these now cause over-verification — Claude re-checks work that was already correct, burning turns and tokens.

Anthropic removed more than 80% of Claude Code's own system prompt for the Claude 5 generation with no measured regression. The same principle applies to your CLAUDE.md: prefer stating the goal and letting Claude exercise judgment over enumerating the checks it should perform.

Delete verification reminders from existing CLAUDE.md files targeting Opus 5 or Fable 5. Keep genuinely non-obvious project requirements — "integration tests need Docker running" is information, not a reminder.

Memory Management Tips Copy Section

Choose the right memory level:

Quick update workflow:

1. For single rules: Use /memory to open editor, or ask conversationally
2. For multiple changes: Use /memory to open editor
3. For initial setup: Use /init to create template

Import best practices:

# Good: Reference existing docs
@README.md
@docs/architecture.md
@package.json

# Avoid: Copying content that exists elsewhere
# Instead of copying README content into CLAUDE.md, just import it

Installation Instructions Copy Chapter

Setup Project Memory Copy Section

Method 1: Using `/init` Command (Recommended)

The fastest way to set up project memory:

1. Navigate to your project directory:

   bash Copy

   cd /path/to/your/project

2. Run the init command in Claude Code:

   bash Copy

   /init

3. Claude will create and populate CLAUDE.md with a template structure

4. Customize the generated file to match your project needs

5. Commit to git:

   bash Copy

   git add CLAUDE.md
   git commit -m "Initialize project memory with /init"

Method 2: Manual Creation

If you prefer manual setup:

1. Create a CLAUDE.md in your project root:

   bash Copy

   cd /path/to/your/project
   touch CLAUDE.md

2. Add project standards:

   bash Copy

   cat > CLAUDE.md << 'EOF'
   # Project Configuration
   
   ## Project Overview
   - **Name**: Your Project Name
   - **Tech Stack**: List your technologies
   - **Team Size**: Number of developers
   
   ## Development Standards
   - Your coding standards
   - Naming conventions
   - Testing requirements
   EOF

3. Commit to git:

   bash Copy

   git add CLAUDE.md
   git commit -m "Add project memory configuration"

Setup Personal Memory Copy Section

1. Create ~/.claude directory:

   bash Copy

   mkdir -p ~/.claude

2. Create personal CLAUDE.md:

   bash Copy

   touch ~/.claude/CLAUDE.md

3. Add your preferences:

   bash Copy

   cat > ~/.claude/CLAUDE.md << 'EOF'
   # My Development Preferences
   
   ## About Me
   - Experience Level: [Your level]
   - Preferred Languages: [Your languages]
   - Communication Style: [Your style]
   
   ## Code Preferences
   - [Your preferences]
   EOF

Setup Directory-Specific Memory Copy Section

1. Create memory for specific directories:

   bash Copy

   mkdir -p /path/to/directory/.claude
   touch /path/to/directory/CLAUDE.md

2. Add directory-specific rules:

   bash Copy

   cat > /path/to/directory/CLAUDE.md << 'EOF'
   # [Directory Name] Standards
   
   This file overrides root CLAUDE.md for this directory.
   
   ## [Specific Standards]
   EOF

3. Commit to version control:

   bash Copy

   git add /path/to/directory/CLAUDE.md
   git commit -m "Add [directory] memory configuration"

Verify Setup Copy Section

1. Check memory locations:

   bash Copy

   # Project root memory
   ls -la ./CLAUDE.md
   
   # Personal memory
   ls -la ~/.claude/CLAUDE.md

2. Claude Code will automatically load these files when starting a session

3. Test with Claude Code by starting a new session in your project

Official Documentation Copy Chapter

For the most up-to-date information, refer to the official Claude Code documentation:

• Memory Documentation - Complete memory system reference
• Slash Commands Reference - All built-in commands including /init and /memory
• CLI Reference - Command-line interface documentation

Key Technical Details from Official Docs Copy Section

Memory Loading:

• All memory files are automatically loaded when Claude Code launches
• Claude traverses upward from the current working directory to discover CLAUDE.md files
• Subtree files are discovered and loaded contextually when accessing those directories

Import Syntax:

• Use @path/to/file to include external content (e.g., @~/.claude/my-project-instructions.md)
• Supports both relative and absolute paths (relative paths resolve relative to the file containing the import, not the working directory)
• Recursive imports supported with a maximum depth of 4 hops
• First-time external imports trigger an approval dialog
• Not evaluated inside markdown code spans or code blocks
• Automatically includes referenced content in Claude's context

CLAUDE.md Load Order (concatenated into context, not strict override — see Memory Hierarchy in Claude Code above):

1. Managed Policy (loads first)
2. User-Level Rules (~/.claude/rules/)
3. User Memory
4. Project Rules (.claude/rules/)
5. Project Memory
6. Local Project Memory (loads last)

Auto Memory is a separate mechanism (~/.claude/projects//memory/), not part of this concatenation order.

Related Concepts Links Copy Chapter

Integration Points Copy Section

• MCP Protocol - Live data access alongside memory
• Slash Commands - Session-specific shortcuts
• Skills - Automated workflows with memory context

Related Claude Features Copy Section

• Claude Web Memory - Automatic synthesis
• Official Memory Docs - Anthropic documentation

Last Updated: August 4, 2026
Claude Code Version: 2.1.220
Sources:

• https://code.claude.com/docs/en/memory
  Compatible Models: Claude Fable 5, Claude Opus 5, Claude Sonnet 5, Claude Sonnet 4.6, Claude Opus 4.8, Claude Haiku 4.5

File: 03-skills/README.md Copy Chapter

Agent Skills Guide

Agent Skills are reusable, filesystem-based capabilities that extend Claude's functionality. They package domain-specific expertise, workflows, and best practices into discoverable components that Claude automatically uses when relevant.

Overview Copy Chapter

Agent Skills are modular capabilities that transform general-purpose agents into specialists. Unlike prompts (conversation-level instructions for one-off tasks), Skills load on-demand and eliminate the need to repeatedly provide the same guidance across multiple conversations.

Key Benefits Copy Section

• Specialize Claude: Tailor capabilities for domain-specific tasks
• Reduce repetition: Create once, use automatically across conversations
• Compose capabilities: Combine Skills to build complex workflows
• Scale workflows: Reuse skills across multiple projects and teams
• Maintain quality: Embed best practices directly into your workflow

Skills follow the Agent Skills open standard, which works across multiple AI tools. Claude Code extends the standard with additional features like invocation control, subagent execution, and dynamic context injection.

Note: Custom slash commands have been merged into skills. .claude/commands/ files still work and support the same frontmatter fields. Skills are recommended for new development. When both exist at the same path (e.g., .claude/commands/review.md and .claude/skills/review/SKILL.md), the skill takes precedence.

How Skills Work: Progressive Disclosure Copy Chapter

Skills leverage a progressive disclosure architecture—Claude loads information in stages as needed, rather than consuming context upfront. This enables efficient context management while maintaining unlimited scalability.

Three Levels of Loading Copy Section

graph TB
    subgraph "Level 1: Metadata (Always Loaded)"
        A["YAML Frontmatter"]
        A1["~100 tokens per skill"]
        A2["name + description"]
    end

    subgraph "Level 2: Instructions (When Triggered)"
        B["SKILL.md Body"]
        B1["Under 5k tokens"]
        B2["Workflows & guidance"]
    end

    subgraph "Level 3: Resources (As Needed)"
        C["Bundled Files"]
        C1["Effectively unlimited"]
        C2["Scripts, templates, docs"]
    end

    A --> B
    B --> C

This means you can install many Skills without context penalty—Claude only knows each Skill exists and when to use it until actually triggered.

Skill Loading Process Copy Chapter

sequenceDiagram
    participant User
    participant Claude
    participant System
    participant SkillInst as Skill Instructions
    participant SkillRes as Skill Resources

    User->>Claude: "Review this code for security issues"
    Claude->>System: Check available skills (metadata)
    System-->>Claude: Skill descriptions loaded at startup
    Claude->>Claude: Match request to skill description
    Claude->>SkillInst: Read code-review-specialist/SKILL.md
    SkillInst-->>Claude: Level 2: Instructions loaded
    Claude->>Claude: Determine: Need templates?
    Claude->>SkillRes: Read templates/checklist.md
    SkillRes-->>Claude: Level 3: Template loaded
    Claude->>Claude: Execute skill instructions
    Claude->>User: Comprehensive code review

Skill Types & Locations Copy Chapter

When skills share the same name across levels, higher-priority locations win: enterprise > project > personal. Project skills override personal ones by default; the skillOverrides setting (v2.1.129+) tunes that behavior — see Controlling Skill Override Behavior. Plugin skills use a plugin-name:skill-name namespace, so they cannot conflict.

Subagent skill discovery (v2.1.133+): Subagents now discover project, user, and plugin skills via the Skill tool the same way the main session does. Earlier versions limited subagents to their own embedded set, which meant skill+subagent workflows quietly degraded; from v2.1.133 the same skill catalog is visible to both.

Automatic Discovery Copy Section

Nested directories: When you work with files in subdirectories, Claude Code automatically discovers skills from nested .claude/skills/ directories. For example, if you're editing a file in packages/frontend/, Claude Code also looks for skills in packages/frontend/.claude/skills/. This supports monorepo setups where packages have their own skills. As of v2.1.178, when a skill name collides across nested .claude/skills/ directories, the directory closest to your current working directory wins — a package-level skill overrides a repo-root skill of the same name.

--add-dir directories: Skills from directories added via --add-dir are loaded automatically with live change detection. Any edits to skill files in those directories take effect immediately without restarting Claude Code.

Reloading skills: The /reload-skills command (added v2.1.152) re-scans all skill directories without restarting the session — useful after adding or editing a skill that isn't picked up by live detection. A SessionStart hook can trigger the same re-scan by returning reloadSkills: true (see Hooks).

Description budget: Skill descriptions (Level 1 metadata) are capped at 1% of the context window (fallback: 8,000 characters). If you have many skills installed, descriptions may be shortened. All skill names are always included, but descriptions are trimmed to fit. Front-load the key use case in descriptions. Override the budget with the SLASH_COMMAND_TOOL_CHAR_BUDGET environment variable.

Creating Custom Skills Copy Chapter

Basic Directory Structure Copy Section

my-skill/
├── SKILL.md           # Main instructions (required)
├── template.md        # Template for Claude to fill in
├── examples/
│   └── sample.md      # Example output showing expected format
└── scripts/
    └── validate.sh    # Script Claude can execute

SKILL.md Format Copy Section

---
name: your-skill-name
---

# Your Skill Name

## Instructions
Provide clear, step-by-step guidance for Claude.

## Examples
Show concrete examples of using this Skill.

Required Fields Copy Section

• name: lowercase letters, numbers, hyphens only (max 64 characters). Cannot contain "anthropic" or "claude".
• description: what the Skill does AND when to use it (max 1024 characters). This is critical for Claude to know when to activate the skill.

Optional Frontmatter Fields Copy Section

---
name: my-skill
argument-hint: "[filename] [format]"        # Hint for autocomplete
disable-model-invocation: true              # Only user can invoke
user-invocable: false                       # Hide from slash menu
allowed-tools: Read, Grep, Glob             # Restrict tool access
disallowed-tools: Write, Edit               # Remove specific tools while active (v2.1.152)
model: opus                                 # Specific model to use
effort: high                                # Effort level override (low, medium, high, xhigh, max)
context: fork                               # Run in isolated subagent
agent: Explore                              # Which agent type (with context: fork)
background: false                           # Fork skills run in background (default true); false = foreground
shell: bash                                 # Shell for commands: bash (default) or powershell
hooks:                                      # Skill-scoped hooks
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate.sh"
paths: "src/api/**/*.ts"               # Glob patterns limiting when skill activates
---

Since v2.1.218, boolean frontmatter fields also accept yes/no, on/off, and 1/0 (case-insensitive) in addition to true/false.

Skill Content Types Copy Chapter

Skills can contain two types of content, each suited for different purposes:

Reference Content Copy Section

Adds knowledge Claude applies to your current work—conventions, patterns, style guides, domain knowledge. Runs inline with your conversation context.

---
name: api-conventions
---

When writing API endpoints:
- Use RESTful naming conventions
- Return consistent error formats
- Include request validation

Task Content Copy Section

Step-by-step instructions for specific actions. Often invoked directly with /skill-name.

---
name: deploy
context: fork
disable-model-invocation: true
---

Deploy the application:
1. Run the test suite
2. Build the application
3. Push to the deployment target

Controlling Skill Invocation Copy Chapter

By default, both you and Claude can invoke any skill. Two frontmatter fields control the three invocation modes:

Use disable-model-invocation: true for workflows with side effects: /commit, /deploy, /send-slack-message. You don't want Claude deciding to deploy because your code looks ready.

Use user-invocable: false for background knowledge that isn't actionable as a command. A legacy-system-context skill explains how an old system works—useful for Claude, but not a meaningful action for users.

String Substitutions Copy Chapter

Skills support dynamic values that are resolved before the skill content reaches Claude:

Example:

---
name: fix-issue
---

Fix GitHub issue $ARGUMENTS following our coding standards.
1. Read the issue description
2. Implement the fix
3. Write tests
4. Create a commit

Running /fix-issue 123 replaces $ARGUMENTS with 123.

Stacking Skills Copy Section

You can stack slash-skills in a single invocation, like /code-review /fix-issue 123. As of v2.1.199, this loads ALL leading skills — the first plus up to 5 more — and passes the trailing arguments (123) to each; previously only the first skill loaded. If the same skill is invoked more than once, its identical content is de-duplicated (v2.1.202) rather than appended twice.

Injecting Dynamic Context Copy Chapter

The !`command` syntax runs shell commands before the skill content is sent to Claude:

---
name: pr-summary
context: fork
agent: Explore
---

## Pull request context
- PR diff: !`gh pr diff`
- PR comments: !`gh pr view --comments`
- Changed files: !`gh pr diff --name-only`

## Your task
Summarize this pull request...

Commands execute immediately; Claude only sees the final output. By default, commands run in bash. Set shell: powershell in frontmatter to use PowerShell instead.

Running Skills in Subagents Copy Chapter

Add context: fork to run a skill in an isolated subagent context. The skill content becomes the task for a dedicated subagent with its own context window, keeping the main conversation uncluttered. As of v2.1.218, background defaults to true for context: fork skills, so they run in the background; set background: false in the frontmatter to run a fork skill in the foreground instead.

v2.1.145 fix: A skill using context: fork could previously trigger an infinite re-invocation loop in rare cases. Upgrade to v2.1.145+ if you author or rely on forking skills.

The agent field specifies which agent type to use:

Example frontmatter:

---
context: fork
agent: Explore
---

Full skill example:

---
name: topic-research
context: fork
agent: Explore
---

Research $ARGUMENTS thoroughly:
1. Find relevant files using Glob and Grep
2. Read and analyze the code
3. Summarize findings with specific file references

Practical Examples Copy Chapter

Example 1: Code Review Skill Copy Section

Directory Structure:

~/.claude/skills/code-review-specialist/
├── SKILL.md
├── templates/
│   ├── review-checklist.md
│   └── finding-template.md
└── scripts/
    ├── analyze-metrics.py
    └── compare-complexity.py

File: ~/.claude/skills/code-review-specialist/SKILL.md

---
name: code-review-specialist
---

# Code Review Skill

This skill provides comprehensive code review capabilities focusing on:

1. **Security Analysis**
   - Authentication/authorization issues
   - Data exposure risks
   - Injection vulnerabilities
   - Cryptographic weaknesses

2. **Performance Review**
   - Algorithm efficiency (Big O analysis)
   - Memory optimization
   - Database query optimization
   - Caching opportunities

3. **Code Quality**
   - SOLID principles
   - Design patterns
   - Naming conventions
   - Test coverage

4. **Maintainability**
   - Code readability
   - Function size (should be < 50 lines)
   - Cyclomatic complexity
   - Type safety

## Review Template

For each piece of code reviewed, provide:

### Summary
- Overall quality assessment (1-5)
- Key findings count
- Recommended priority areas

### Critical Issues (if any)
- **Issue**: Clear description
- **Location**: File and line number
- **Impact**: Why this matters
- **Severity**: Critical/High/Medium
- **Fix**: Code example

For detailed checklists, see [templates/review-checklist.md](templates/review-checklist.md).

Example 2: Codebase Visualizer Skill Copy Section

A skill that generates interactive HTML visualizations:

Directory Structure:

~/.claude/skills/codebase-visualizer/
├── SKILL.md
└── scripts/
    └── visualize.py

File: ~/.claude/skills/codebase-visualizer/SKILL.md

---
name: codebase-visualizer
allowed-tools: Bash(python *)
---

# Codebase Visualizer

Generate an interactive HTML tree view showing your project's file structure.

## Usage

Run the visualization script from your project root:

```bash
python ~/.claude/skills/codebase-visualizer/scripts/visualize.py .
```

This creates `codebase-map.html` and opens it in your default browser.

## What the visualization shows

- **Collapsible directories**: Click folders to expand/collapse
- **File sizes**: Displayed next to each file
- **Colors**: Different colors for different file types
- **Directory totals**: Shows aggregate size of each folder

The bundled Python script does the heavy lifting while Claude handles orchestration.

Example 3: Deploy Skill (User-Invoked Only) Copy Section

---
name: deploy
disable-model-invocation: true
allowed-tools: Bash(npm *), Bash(git *)
---

Deploy $ARGUMENTS to production:

1. Run the test suite: `npm test`
2. Build the application: `npm run build`
3. Push to the deployment target
4. Verify the deployment succeeded
5. Report deployment status

Example 4: Brand Voice Skill (Background Knowledge) Copy Section

---
name: brand-voice
user-invocable: false
---

## Tone of Voice
- **Friendly but professional** - approachable without being casual
- **Clear and concise** - avoid jargon
- **Confident** - we know what we're doing
- **Empathetic** - understand user needs

## Writing Guidelines
- Use "you" when addressing readers
- Use active voice
- Keep sentences under 20 words
- Start with value proposition

For templates, see [templates/](templates/).

Example 5: CLAUDE.md Generator Skill Copy Section

---
name: claude-md
---

## Core Principles

**LLMs are stateless**: CLAUDE.md is the only file automatically included in every conversation.

### The Golden Rules

1. **Less is More**: Keep under 300 lines (ideally under 100)
2. **Universal Applicability**: Only include information relevant to EVERY session
3. **Don't Use Claude as a Linter**: Use deterministic tools instead
4. **Never Auto-Generate**: Craft it manually with careful consideration

## Essential Sections

- **Project Name**: Brief one-line description
- **Tech Stack**: Primary language, frameworks, database
- **Development Commands**: Install, test, build commands
- **Critical Conventions**: Only non-obvious, high-impact conventions
- **Known Issues / Gotchas**: Things that trip up developers

Example 6: Refactoring Skill with Scripts Copy Section

Directory Structure:

refactor/
├── SKILL.md
├── references/
│   ├── code-smells.md
│   └── refactoring-catalog.md
├── templates/
│   └── refactoring-plan.md
└── scripts/
    ├── analyze-complexity.py
    └── detect-smells.py

File: refactor/SKILL.md

---
name: refactor
---

# Code Refactoring Skill

A phased approach emphasizing safe, incremental changes backed by tests.

## Workflow

Phase 1: Research & Analysis → Phase 2: Test Coverage Assessment →
Phase 3: Code Smell Identification → Phase 4: Refactoring Plan Creation →
Phase 5: Incremental Implementation → Phase 6: Review & Iteration

## Core Principles

1. **Behavior Preservation**: External behavior must remain unchanged
2. **Small Steps**: Make tiny, testable changes
3. **Test-Driven**: Tests are the safety net
4. **Continuous**: Refactoring is ongoing, not a one-time event

For code smell catalog, see [references/code-smells.md](references/code-smells.md).
For refactoring techniques, see [references/refactoring-catalog.md](references/refactoring-catalog.md).

Supporting Files Copy Chapter

Skills can include multiple files in their directory beyond SKILL.md. These supporting files (templates, examples, scripts, reference documents) let you keep the main skill file focused while providing Claude with additional resources it can load as needed.

my-skill/
├── SKILL.md              # Main instructions (required, keep under 500 lines)
├── templates/            # Templates for Claude to fill in
│   └── output-format.md
├── examples/             # Example outputs showing expected format
│   └── sample-output.md
├── references/           # Domain knowledge and specifications
│   └── api-spec.md
└── scripts/              # Scripts Claude can execute
    └── validate.sh

Guidelines for supporting files:

• Keep SKILL.md under 500 lines. Move detailed reference material, large examples, and specifications to separate files.
• Reference additional files from SKILL.md using relative paths (e.g., [API reference](references/api-spec.md)).
• Supporting files are loaded at Level 3 (as needed), so they do not consume context until Claude actually reads them.

Managing Skills Copy Chapter

Viewing Available Skills Copy Section

Ask Claude directly:

What Skills are available?

Or check the filesystem:

# List personal Skills
ls ~/.claude/skills/

# List project Skills
ls .claude/skills/

Tip (v2.1.121+): Type to filter the /skills interactive menu — useful when many skills are installed.

Testing a Skill Copy Section

Two ways to test:

Let Claude invoke it automatically by asking something that matches the description:

Can you help me review this code for security issues?

Or invoke it directly with the skill name:

/code-review-specialist src/auth/login.ts

Note: This local skill is installed as code-review-specialist so it does not collide with the built-in /code-review command (the renamed /simplify, shipped in Claude Code v2.1.146). If you copy it to ~/.claude/skills/code-review/ instead, it will shadow the built-in — keep the -specialist suffix to avoid that.

Updating a Skill Copy Section

Edit the SKILL.md file directly. Changes take effect on next Claude Code startup.

# Personal Skill
code ~/.claude/skills/my-skill/SKILL.md

# Project Skill
code .claude/skills/my-skill/SKILL.md

Restricting Claude's Skill Access Copy Section

Three ways to control which skills Claude can invoke:

Disable all skills in /permissions:

# Add to deny rules:
Skill

Allow or deny specific skills:

# Allow only specific skills
Skill(commit)
Skill(review-pr *)

# Deny specific skills
Skill(deploy *)

Hide individual skills by adding disable-model-invocation: true to their frontmatter.

Controlling Skill Override Behavior (`skillOverrides`) Copy Section

When a project skill and a user skill share the same name, project wins by default. The skillOverrides setting (v2.1.129+) lets you tune this. Add it to ~/.claude/settings.json or project .claude/settings.json:

{
  "skillOverrides": "name-only"
}

Accepted values:

Useful when team policy says "user-defined skills must always take precedence" ("off") or "only allow narrow name-based overrides" ("name-only").

Best Practices Copy Chapter

1. Make Descriptions Specific Copy Section

• Bad (Vague): "Helps with documents"
• Good (Specific): "Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction."

2. Keep Skills Focused Copy Section

• One Skill = one capability
• ✅ "PDF form filling"
• ❌ "Document processing" (too broad)

3. Include Trigger Terms Copy Section

Add keywords in descriptions that match user requests:

4. Keep SKILL.md Under 500 Lines Copy Section

Move detailed reference material to separate files that Claude loads as needed.

5. Reference Supporting Files Copy Section

## Additional resources

- For complete API details, see [reference.md](reference.md)
- For usage examples, see [examples.md](examples.md)

Do's Copy Section

• Use clear, descriptive names
• Include comprehensive instructions
• Add concrete examples
• Package related scripts and templates
• Test with real scenarios
• Document dependencies

Don'ts Copy Section

• Don't create skills for one-time tasks
• Don't duplicate existing functionality
• Don't make skills too broad
• Don't skip the description field
• Don't install skills from untrusted sources without auditing

Troubleshooting Copy Chapter

Quick Reference Copy Section

Skill Not Triggering Copy Section

If Claude doesn't use your skill when expected:

1. Check the description includes keywords users would naturally say
2. Verify the skill appears when asking "What skills are available?"
3. Try rephrasing your request to match the description
4. Invoke directly with /skill-name to test

Skill Triggers Too Often Copy Section

If Claude uses your skill when you don't want it:

1. Make the description more specific
2. Add disable-model-invocation: true for manual-only invocation

Claude Doesn't See All Skills Copy Section

Skill descriptions are loaded at 1% of the context window (fallback: 8,000 characters). Each entry is capped at 250 characters regardless of budget. Run /context to check for warnings about excluded skills. Override the budget with the SLASH_COMMAND_TOOL_CHAR_BUDGET environment variable.

Security Considerations Copy Chapter

Only use Skills from trusted sources. Skills provide Claude with capabilities through instructions and code—a malicious Skill can direct Claude to invoke tools or execute code in harmful ways.

Key security considerations:

• Audit thoroughly: Review all files in the Skill directory
• External sources are risky: Skills that fetch from external URLs can be compromised
• Tool misuse: Malicious Skills can invoke tools in harmful ways
• Treat like installing software: Only use Skills from trusted sources

Disabling shell substitution in skills Copy Section

Skills support the !`command` syntax to inject the output of shell commands into the prompt before Claude sees it. In security-sensitive environments (shared enterprise deployments, locked-down CI runners) you can disable this substitution entirely via the disableSkillShellExecution setting (added in v2.1.91):

// ~/.claude/settings.json or managed policy
{
  "disableSkillShellExecution": true
}

When disableSkillShellExecution is true, any !`command` markers in a skill are left as literal text instead of being executed — removing the skill-level shell-injection attack surface without disabling skills themselves. Consider combining this with an allowedTools allowlist for defense in depth.

Hiding bundled skills (`disableBundledSkills`) Copy Section

The disableBundledSkills setting (added in v2.1.169) hides the bundled skills, workflows, and commands that ship with Claude Code from the model. Use it when the built-in skills are noise for a given project, or to reduce the model's skill surface:

// ~/.claude/settings.json or project .claude/settings.json
{
  "disableBundledSkills": true
}

The equivalent environment-variable form is:

export CLAUDE_CODE_DISABLE_BUNDLED_SKILLS=1

Skills vs Other Features Copy Chapter

Bundled Skills Copy Chapter

Claude Code ships with a set of built-in skills that are always available without installation (the most useful ones are listed below; see the commands reference for the full set):

These skills are available out-of-the-box and do not need to be installed or configured. They follow the same SKILL.md format as custom skills.

Sharing Skills Copy Chapter

Project Skills (Team Sharing) Copy Section

1. Create Skill in .claude/skills/
2. Commit to git
3. Team members pull changes — Skills available immediately

Personal Skills Copy Section

# Copy to personal directory
cp -r my-skill ~/.claude/skills/

# Make scripts executable
chmod +x ~/.claude/skills/my-skill/scripts/*.py

Plugin Distribution Copy Section

Package skills in a plugin's skills/ directory for broader distribution.

Going Further: A Skill Collection and a Skill Manager Copy Chapter

Once you start building skills seriously, two things become essential: a library of proven skills and a tool to manage them.

luongnv89/skills — A collection of skills I use daily across almost all my projects. Highlights include logo-designer (generates project logos on the fly) and ollama-optimizer (tunes local LLM performance for your hardware). Great starting point if you want ready-to-use skills.

luongnv89/asm — Agent Skill Manager. Handles skill development, duplicate detection, and testing. The asm link command lets you test a skill in any project without copying files around — essential once you have more than a handful of skills.

Additional Resources Copy Chapter

• Official Skills Documentation
• Agent Skills Architecture Blog
• Skills Repository - Collection of ready-to-use skills
• Slash Commands Guide - User-initiated shortcuts
• Subagents Guide - Delegated AI agents
• Memory Guide - Persistent context
• MCP (Model Context Protocol) - Real-time external data
• Hooks Guide - Event-driven automation

Last Updated: August 4, 2026
Claude Code Version: 2.1.220
Sources:

• https://code.claude.com/docs/en/skills
• https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md
• https://code.claude.com/docs/en/model-config
  Compatible Models: Claude Fable 5, Claude Opus 5, Claude Sonnet 5, Claude Sonnet 4.6, Claude Opus 4.8, Claude Haiku 4.5

File: 04-subagents/README.md Copy Chapter

Subagents - Complete Reference Guide

Subagents are specialized AI assistants that Claude Code can delegate tasks to. Each subagent has a specific purpose, uses its own context window separate from the main conversation, and can be configured with specific tools and a custom system prompt.

Table of Contents Copy Chapter

1. Overview
2. Key Benefits
3. File Locations
4. Configuration
5. Built-in Subagents
6. Managing Subagents
7. Using Subagents
8. Resumable Agents
9. Chaining Subagents
10. Persistent Memory for Subagents
11. Background Subagents
12. Worktree Isolation
13. Forked Subagents
14. Restrict Spawnable Subagents
15. claude agents CLI Command
16. Agent Teams (Experimental)
17. Plugin Subagent Security
18. Architecture
19. Context Management
20. When to Use Subagents
21. Best Practices
22. Example Subagents in This Folder
23. Installation Instructions
24. File Structure
25. Related Concepts
26. Observability
27. Additional Resources

Overview Copy Chapter

Subagents enable delegated task execution in Claude Code by:

• Creating isolated AI assistants with separate context windows
• Providing customized system prompts for specialized expertise
• Enforcing tool access control to limit capabilities
• Preventing context pollution from complex tasks
• Enabling parallel execution of multiple specialized tasks

Each subagent operates independently with a clean slate, receiving only the specific context necessary for their task, then returning results to the main agent for synthesis.

Quick Start: Ask Claude to create a subagent for you ("create a subagent that reviews security"), or add a .claude/agents/<name>.md file directly — see Managing Subagents below.

Note: As of v2.1.198, the /agents command no longer opens an interactive creation wizard. Create and manage subagents by asking Claude or editing .claude/agents/ files directly.

Key Benefits Copy Chapter

File Locations Copy Chapter

Subagent files can be stored in multiple locations with different scopes:

When duplicate names exist, higher-priority sources take precedence.

Nested .claude/ precedence (v2.1.178): When the same agent name is defined in multiple nested .claude/agents/ directories (for example, a monorepo with package-level .claude/ folders), the definition closest to your current working directory wins. The same closest-wins rule applies to nested workflow and output-style definitions.

Configuration Copy Chapter

File Format Copy Section

Subagents are defined in YAML frontmatter followed by the system prompt in markdown:

---
name: your-sub-agent-name
tools: tool1, tool2, tool3  # Optional - inherits all tools if omitted
disallowedTools: tool4  # Optional - explicitly disallowed tools
model: sonnet  # Optional - sonnet, opus, haiku, or inherit
permissionMode: default  # Optional - permission mode
maxTurns: 20  # Optional - limit agentic turns
skills: skill1, skill2  # Optional - skills to preload into context
mcpServers: server1  # Optional - MCP servers to make available
memory: user  # Optional - persistent memory scope (user, project, local)
background: false  # Optional - run as background task
effort: high  # Optional - reasoning effort (low, medium, high, xhigh, max)
isolation: worktree  # Optional - git worktree isolation
initialPrompt: "Start by analyzing the codebase"  # Optional - auto-submitted first turn
hooks:  # Optional - component-scoped hooks
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/security-check.sh"
---

Your subagent's system prompt goes here. This can be multiple paragraphs
and should clearly define the subagent's role, capabilities, and approach
to solving problems.

Configuration Fields Copy Section

Main-Thread Agent Frontmatter Honoring (v2.1.117+/v2.1.119+) Copy Section

When an agent is invoked as the main-thread agent (via claude --agent <name> or --print mode), these frontmatter fields are honored:

Example — agent with mcpServers and permissionMode:

---
name: secure-researcher
permissionMode: acceptEdits
mcpServers:
  notion:
    type: http
    url: https://mcp.notion.com/mcp
  github:
    type: http
    url: https://api.github.com/mcp
tools: Read, Grep, Glob
---

You are a research agent. You may query Notion and GitHub through the
configured MCP servers, and read local files, but you cannot write or
execute commands outside of accepted edits.

Run with:

claude --agent secure-researcher

Tool Configuration Options Copy Section

Option 1: Inherit All Tools (omit the field)

---
name: full-access-agent
---

Option 2: Specify Individual Tools

---
name: limited-agent
tools: Read, Grep, Glob, Bash
---

Note on Glob/Grep (v2.1.113+): On native macOS/Linux builds, Glob and Grep are provided as bfs/ugrep through the Bash tool rather than as separate tools. Windows and npm-JS builds still expose them as standalone tools. Authors can still reference Glob/Grep in allowedTools; the backend substitution is transparent.

Option 3: Conditional Tool Access

---
name: conditional-agent
tools: Read, Bash(npm:*), Bash(test:*)
---

CLI-Based Configuration Copy Section

Define subagents for a single session using the --agents flag with JSON format:

claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  }
}'

JSON Format for --agents flag:

{
  "agent-name": {
    "description": "Required: when to invoke this agent",
    "prompt": "Required: system prompt for the agent",
    "tools": ["Optional", "array", "of", "tools"],
    "model": "optional: sonnet|opus|haiku"
  }
}

Priority of Agent Definitions:

Agent definitions are loaded with this priority order (first match wins):

1. CLI-defined - --agents flag (session only, JSON)
2. Project-level - .claude/agents/ (current project)
3. User-level - ~/.claude/agents/ (all projects)
4. Plugin-level - Plugin agents/ directory

This allows CLI definitions to override all other sources for a single session.

Built-in Subagents Copy Chapter

Claude Code includes several built-in subagents that are always available:

General-Purpose Subagent Copy Section

When used: Tasks requiring both exploration and modification with complex reasoning.

Plan Subagent Copy Section

When used: When Claude needs to understand the codebase before presenting a plan.

Explore Subagent Copy Section

When used: When searching/understanding code without making changes.

Thoroughness Levels - Specify the depth of exploration:

• "quick" - Fast searches with minimal exploration, good for finding specific patterns
• "medium" - Moderate exploration, balanced speed and thoroughness, default approach
• "very thorough" - Comprehensive analysis across multiple locations and naming conventions, may take longer

Bash Subagent Copy Section

When used: When running shell commands that benefit from isolated context.

Statusline Setup Subagent Copy Section

When used: When setting up or customizing the status line.

Claude Code Guide Subagent Copy Section

When used: When users ask questions about how Claude Code works or how to use specific features.

Managing Subagents Copy Chapter

Ask Claude (Recommended) Copy Section

The simplest way to create or manage a subagent is to ask Claude directly:

Create a subagent that reviews code for security vulnerabilities.

Claude writes the .claude/agents/<name>.md file for you, choosing sensible frontmatter (tools, model, description). You can then refine the file by hand or ask Claude to adjust it.

Note: The /agents command no longer opens an interactive creation wizard (removed in v2.1.198). It now points you to ask Claude or edit .claude/agents/ files directly.

Direct File Management Copy Section

# Create a project subagent
mkdir -p .claude/agents
cat > .claude/agents/test-runner.md << 'EOF'
---
name: test-runner
---

You are a test automation expert. When you see code changes, proactively
run the appropriate tests. If tests fail, analyze the failures and fix
them while preserving the original test intent.
EOF

# Create a user subagent (available in all projects)
mkdir -p ~/.claude/agents

Using Subagents Copy Chapter

Automatic Delegation Copy Section

Claude proactively delegates tasks based on:

• Task description in your request
• The description field in subagent configurations
• Current context and available tools

To encourage proactive use, include "use PROACTIVELY" or "MUST BE USED" in your description field:

---
name: code-reviewer
---

Explicit Invocation Copy Section

You can explicitly request a specific subagent:

> Use the test-runner subagent to fix failing tests
> Have the code-reviewer subagent look at my recent changes
> Ask the debugger subagent to investigate this error

Case- and separator-insensitive subagent_type matching (v2.1.140): subagent_type (in Agent tool calls or --agent flags) is matched case-insensitively and ignores separator style — code-reviewer, Code Reviewer, and code_reviewer all resolve to the same agent. This removes a long-standing footgun where minor capitalization differences silently fell back to the default agent.

@-Mention Invocation Copy Section

Use the @ prefix to guarantee a specific subagent is invoked (bypasses automatic delegation heuristics):

> @"code-reviewer (agent)" review the auth module

Session-Wide Agent Copy Section

Run an entire session using a specific agent as the main agent:

# Via CLI flag
claude --agent code-reviewer

# Via settings.json
{
  "agent": "code-reviewer"
}

Listing Available Agents Copy Section

Use the claude agents command to list all configured agents from all sources:

claude agents

Resumable Agents Copy Chapter

Subagents can continue previous conversations with full context preserved:

# Initial invocation
> Use the code-analyzer agent to start reviewing the authentication module
# Returns agentId: "abc123"

# Resume the agent later
> Resume agent abc123 and now analyze the authorization logic as well

Use cases:

• Long-running research across multiple sessions
• Iterative refinement without losing context
• Multi-step workflows maintaining context

Chaining Subagents Copy Chapter

Execute multiple subagents in sequence:

> First use the code-analyzer subagent to find performance issues,
  then use the optimizer subagent to fix them

This enables complex workflows where the output of one subagent feeds into another.

Persistent Memory for Subagents Copy Chapter

The memory field gives subagents a persistent directory that survives across conversations. This allows subagents to build up knowledge over time, storing notes, findings, and context that persist between sessions.

Memory Scopes Copy Section

How It Works Copy Section

• The first 200 lines of MEMORY.md in the memory directory are automatically loaded into the subagent's system prompt
• The Read, Write, and Edit tools are automatically enabled for the subagent to manage its memory files
• The subagent can create additional files in its memory directory as needed

Example Configuration Copy Section

---
name: researcher
memory: user
---

You are a research assistant. Use your memory directory to store findings,
track progress across sessions, and build up knowledge over time.

Check your MEMORY.md file at the start of each session to recall previous context.

graph LR
    A["SubagentSession 1"] -->|writes| M["MEMORY.md(persistent)"]
    M -->|loads into| B["SubagentSession 2"]
    B -->|updates| M
    M -->|loads into| C["SubagentSession 3"]

    style A fill:#e1f5fe,stroke:#333,color:#333
    style B fill:#e1f5fe,stroke:#333,color:#333
    style C fill:#e1f5fe,stroke:#333,color:#333
    style M fill:#f3e5f5,stroke:#333,color:#333

Background Subagents Copy Chapter

Subagents run in the background by default (v2.1.198). Claude keeps working on the main conversation while a subagent runs and is notified when it finishes, so you no longer wait on a subagent to return before continuing.

Configuration Copy Section

Because background is already the default, background: true in the frontmatter forces the subagent to always run in the background and prevents it from running inline:

---
name: long-runner
background: true
---

Keyboard Shortcuts Copy Section

Disabling Background Tasks Copy Section

Set the environment variable to disable background task support entirely:

export CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1

Worktree Isolation Copy Chapter

The isolation: worktree setting gives a subagent its own git worktree, allowing it to make changes independently without affecting the main working tree.

Configuration Copy Section

---
name: feature-builder
isolation: worktree
tools: Read, Write, Edit, Bash, Grep, Glob
---

How It Works Copy Section

graph TB
    Main["Main Working Tree"] -->|spawns| Sub["Subagent withIsolated Worktree"]
    Sub -->|makes changes in| WT["Separate GitWorktree + Branch"]
    WT -->|no changes| Clean["Auto-cleaned"]
    WT -->|has changes| Return["Returns worktreepath and branch"]

    style Main fill:#e1f5fe,stroke:#333,color:#333
    style Sub fill:#f3e5f5,stroke:#333,color:#333
    style WT fill:#e8f5e9,stroke:#333,color:#333
    style Clean fill:#fff3e0,stroke:#333,color:#333
    style Return fill:#fff3e0,stroke:#333,color:#333

• The subagent operates in its own git worktree on a separate branch
• If the subagent makes no changes, the worktree is automatically cleaned up
• If changes exist, the worktree path and branch name are returned to the main agent for review or merging

Forked Subagents Copy Chapter

Forked subagents (context: fork) inherit the parent agent's full conversation context at the moment of forking, rather than starting with a clean slate. This is useful for exploring alternative paths without losing the work done so far.

Availability: GA in v2.1.117. Since v2.1.232, fork mode is on by default in interactive sessions — on every build, first-party or not. It stays off by default in non-interactive mode (claude -p) and in the Agent SDK. On Claude Code older than v2.1.232, or to turn it on where it is off by default, set CLAUDE_CODE_FORK_SUBAGENT=1.

Fork-mode subagents run in the background. Where fork mode is on — as it is by default in an interactive session — Claude Code runs the subagent in the background, forked and non-forked subagents alike.

Configuration Copy Section

---
name: alternative-explorer
context: fork
tools: Read, Edit, Bash, Grep, Glob
---

You are a forked subagent. You inherit the parent's full conversation and
may explore an alternative approach. Return your findings and the parent
will decide whether to adopt them.

Enabling Fork Mode Explicitly Copy Section

Interactive sessions on v2.1.232+ need no flag. Use this on older versions, in headless
runs, or in the Agent SDK:

export CLAUDE_CODE_FORK_SUBAGENT=1
claude

When to Use Fork vs Clean Context Copy Section

Restrict Spawnable Subagents Copy Chapter

You can control which subagents a given subagent is allowed to spawn by using the Agent(agent_type) syntax in the tools field. This provides a way to allowlist specific subagents for delegation.

Note: In v2.1.63, the Task tool was renamed to Agent. Existing Task(...) references still work as aliases.

Example Copy Section

---
name: coordinator
tools: Agent(worker, researcher), Read, Bash
---

You are a coordinator agent. You can delegate work to the "worker" and
"researcher" subagents only. Use Read and Bash for your own exploration.

In this example, the coordinator subagent can only spawn the worker and researcher subagents. It cannot spawn any other subagents, even if they are defined elsewhere.

`claude agents` CLI Command Copy Chapter

The claude agents command lists all configured agents grouped by source (built-in, user-level, project-level):

claude agents

This command:

• Shows all available agents from all sources
• Groups agents by their source location
• Indicates overrides when an agent at a higher priority level shadows one at a lower level (e.g., a project-level agent with the same name as a user-level agent)

Agent Teams (Experimental) Copy Chapter

Agent Teams coordinate multiple Claude Code instances working together on complex tasks. Unlike subagents (which are delegated subtasks returning results), teammates work independently with their own context windows and can message each other directly through a shared mailbox system.

Official Documentation: code.claude.com/docs/en/agent-teams

Note: Agent Teams is experimental and disabled by default. Requires Claude Code v2.1.32+. Enable it before use.

Subagents vs Agent Teams Copy Section

Enabling Agent Teams Copy Section

Set the environment variable or add it to your settings.json:

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Or in settings.json:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Starting a team Copy Section

Once enabled, ask Claude to work with teammates in your prompt:

User: Build the authentication module. Use a team — one teammate for the API endpoints,
      one for the database schema, and one for the test suite.

Claude will create the team, assign tasks, and coordinate the work automatically.

Display modes Copy Section

Control how teammate activity is displayed:

claude --teammate-mode tmux

You can also set the display mode in settings.json:

{
  "teammateMode": "tmux"
}

Note: Split-pane mode requires tmux or iTerm2. It is not available in VS Code terminal, Windows Terminal, or Ghostty.

Navigation Copy Section

Use Shift+Down to navigate between teammates in split-pane mode.

Team Configuration Copy Section

Team configurations are stored at ~/.claude/teams/{team-name}/config.json.

Teammate Model Selection Copy Section

As of v2.1.234, the "Default teammate model" /config setting was removed. Teammates now inherit the team lead's model by default, unless the spawn call specifies a different model explicitly.

Architecture Copy Section

graph TB
    Lead["Team Lead(Coordinator)"]
    TaskList["Shared Task List(Dependencies)"]
    Mailbox["Mailbox(Messages)"]
    T1["Teammate 1(Own Context)"]
    T2["Teammate 2(Own Context)"]
    T3["Teammate 3(Own Context)"]

    Lead -->|assigns tasks| TaskList
    Lead -->|sends messages| Mailbox
    TaskList -->|picks up work| T1
    TaskList -->|picks up work| T2
    TaskList -->|picks up work| T3
    T1 -->|reads/writes| Mailbox
    T2 -->|reads/writes| Mailbox
    T3 -->|reads/writes| Mailbox
    T1 -->|updates status| TaskList
    T2 -->|updates status| TaskList
    T3 -->|updates status| TaskList

    style Lead fill:#e1f5fe,stroke:#333,color:#333
    style TaskList fill:#fff9c4,stroke:#333,color:#333
    style Mailbox fill:#f3e5f5,stroke:#333,color:#333
    style T1 fill:#e8f5e9,stroke:#333,color:#333
    style T2 fill:#e8f5e9,stroke:#333,color:#333
    style T3 fill:#e8f5e9,stroke:#333,color:#333

Key components:

• Team Lead: The main Claude Code session that creates the team, assigns tasks, and coordinates
• Shared Task List: A synchronized list of tasks with automatic dependency tracking
• Mailbox: An inter-agent messaging system for teammates to communicate status and coordinate
• Teammates: Independent Claude Code instances, each with their own context window

Task assignment and messaging Copy Section

The team lead breaks work into tasks and assigns them to teammates. The shared task list handles:

• Automatic dependency management — tasks wait for their dependencies to complete
• Status tracking — teammates update task status as they work
• Inter-agent messaging — teammates send messages via the mailbox for coordination (e.g., "Database schema is ready, you can start writing queries")

Plan approval workflow Copy Section

For complex tasks, the team lead creates an execution plan before teammates begin work. The user reviews and approves the plan, ensuring the team's approach aligns with expectations before any code changes are made.

Hook events for teams Copy Section

Agent Teams introduce two additional hook events:

Best practices Copy Section

• Team size: Keep teams at 3-5 teammates for optimal coordination
• Task sizing: Break work into tasks that take 5-15 minutes each — small enough to parallelize, large enough to be meaningful
• Avoid file conflicts: Assign different files or directories to different teammates to prevent merge conflicts
• Start simple: Use in-process mode for your first team; switch to split-panes once comfortable
• Clear task descriptions: Provide specific, actionable task descriptions so teammates can work independently

Limitations Copy Section

• Experimental: Feature behavior may change in future releases
• No session resumption: In-process teammates cannot be resumed after a session ends
• One team per session: Cannot create nested teams or multiple teams in a single session
• Fixed leadership: The team lead role cannot be transferred to a teammate
• Split-pane restrictions: tmux/iTerm2 required; not available in VS Code terminal, Windows Terminal, or Ghostty
• No cross-session teams: Teammates exist only within the current session

Warning: Agent Teams is experimental. Test with non-critical work first and monitor teammate coordination for unexpected behavior.

Plugin Subagent Security Copy Chapter

Plugin-provided subagents have restricted frontmatter capabilities for security. The following fields are not allowed in plugin subagent definitions:

• hooks - Cannot define lifecycle hooks
• mcpServers - Cannot configure MCP servers
• permissionMode - Cannot override permission settings

This prevents plugins from escalating privileges or executing arbitrary commands through subagent hooks.

Subagent Output Scanning (v2.1.210+) Copy Section

As of v2.1.210, Claude Code scans each subagent's final report for text that imitates the harness's own output format — fake <system-reminder>-style tags, fabricated Human:/Assistant: turns, or mentions of permission-bypass flags and settings-file paths. This defends against prompt injection carried in subagent output, such as a subagent that fetched a malicious web page containing fake control tokens designed to manipulate the parent session.

When the scan flags something, Claude Code neutralizes it — inserting a backslash or an inline marker such as [harness: subagent output matched instruction-shaped pattern(s): ...] naming what triggered the scan — and the parent session is expected to treat the flagged text as a finding to relay, not an instruction to follow. The scan is on by default with no documented opt-out. It errs toward flagging: a legitimate subagent report that quotes a real flag name (e.g. --dangerously-skip-permissions) verbatim can trigger a marker even though nothing malicious occurred — a false positive is preferable to a missed injection.

Subagent Concurrency and Depth Limits Copy Section

The per-session spawn cap is gone. Claude Code capped subagent spawns at 200 per session from v2.1.212, but v2.1.224 removed that cap — long-running sessions no longer refuse new agents, and the official subagents reference now states plainly that there is no limit on the total number of subagents Claude can spawn over a session. The CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION variable that overrode it is gone with it.

Two limits on subagent fan-out do still apply, both set by environment variable:

• CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS (v2.1.217) - Maximum number of subagents running concurrently at once. Default: 20.
• CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH (v2.1.217) - Maximum nesting depth for subagents spawning their own subagents. Default: 3 since v2.1.219 (was 1 in v2.1.217–v2.1.218). Set this to 1 to disable nesting (see Key Behaviors).

export CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS=20
export CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=5

Architecture Copy Chapter

High-Level Architecture Copy Section

graph TB
    User["User"]
    Main["Main Agent(Coordinator)"]
    Reviewer["Code ReviewerSubagent"]
    Tester["Test EngineerSubagent"]
    Docs["DocumentationSubagent"]

    User -->|asks| Main
    Main -->|delegates| Reviewer
    Main -->|delegates| Tester
    Main -->|delegates| Docs
    Reviewer -->|returns result| Main
    Tester -->|returns result| Main
    Docs -->|returns result| Main
    Main -->|synthesizes| User

Subagent Lifecycle Copy Section

sequenceDiagram
    participant User
    participant MainAgent as Main Agent
    participant CodeReviewer as Code ReviewerSubagent
    participant Context as SeparateContext Window

    User->>MainAgent: "Build new auth feature"
    MainAgent->>MainAgent: Analyze task
    MainAgent->>CodeReviewer: "Review this code"
    CodeReviewer->>Context: Initialize clean context
    Context->>CodeReviewer: Load reviewer instructions
    CodeReviewer->>CodeReviewer: Perform review
    CodeReviewer-->>MainAgent: Return findings
    MainAgent->>MainAgent: Incorporate results
    MainAgent-->>User: Provide synthesis

Context Management Copy Chapter

graph TB
    A["Main Agent Context50,000 tokens"]
    B["Subagent 1 Context20,000 tokens"]
    C["Subagent 2 Context20,000 tokens"]
    D["Subagent 3 Context20,000 tokens"]

    A -->|Clean slate| B
    A -->|Clean slate| C
    A -->|Clean slate| D

    B -->|Results only| A
    C -->|Results only| A
    D -->|Results only| A

    style A fill:#e1f5fe
    style B fill:#fff9c4
    style C fill:#fff9c4
    style D fill:#fff9c4

Key Points Copy Section

• Each subagent gets a fresh context window without the main conversation history
• Only the relevant context is passed to the subagent for their specific task
• Results are distilled back to the main agent
• This prevents context token exhaustion on long projects

Performance Considerations Copy Section

• Context efficiency - Agents preserve main context, enabling longer sessions
• Latency - Subagents start with clean slate and may add latency gathering initial context

Key Behaviors Copy Section

• Nested spawning on by default, depth 3 (v2.1.219) - Subagents can spawn their own subagents up to three layers below the main conversation. Set CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH to change the limit, or 1 to turn nesting off. At the depth limit, Claude Code withholds the Agent tool from every subagent except a fork. (History: v2.1.172–v2.1.216 nested by default up to 5 layers with no way to change it; v2.1.217 made nesting opt-in at depth 1; v2.1.219 set the default to 3.) Use the Agent(agent_type) restriction syntax (see Restrict Spawnable Subagents) to control which subagents a given subagent may spawn
• Background permissions - Background subagents auto-deny any permissions that are not pre-approved
• Backgrounding - Press Ctrl+B to background a currently running task
• Transcripts - Subagent transcripts are stored at ~/.claude/projects/{project}/{sessionId}/subagents/agent-{agentId}.jsonl
• Auto-compaction - Subagent context auto-compacts at ~95% capacity (override with CLAUDE_AUTOCOMPACT_PCT_OVERRIDE environment variable)
• Extended thinking inherited (v2.1.198) - Subagents and context compaction now inherit the session's extended-thinking configuration (previously always disabled). There is no per-subagent thinking field

Additional Controls Copy Section

• Disable built-in Explore/Plan agents - Set CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1 to remove the built-in Explore and Plan agents (v2.1.198)
• Append to every subagent prompt - In non-interactive / --print mode, --append-subagent-system-prompt "<text>" appends text to every subagent's system prompt (v2.1.205)

When to Use Subagents Copy Chapter

Best Practices Copy Chapter

Design Principles Copy Section

Do:

• Start with Claude-generated agents - Generate initial subagent with Claude, then iterate to customize
• Design focused subagents - Single, clear responsibilities rather than one doing everything
• Write detailed prompts - Include specific instructions, examples, and constraints
• Limit tool access - Grant only necessary tools for the subagent's purpose
• Version control - Check project subagents into version control for team collaboration

Don't:

• Create overlapping subagents with same roles
• Give subagents unnecessary tool access
• Use subagents for simple, single-step tasks
• Mix concerns in one subagent's prompt
• Forget to pass necessary context

System Prompt Best Practices Copy Section

1. Be Specific About Role

   text Copy

   You are an expert code reviewer specializing in [specific areas]

2. Define Priorities Clearly

   text Copy

   Review priorities (in order):
   1. Security Issues
   2. Performance Problems
   3. Code Quality

3. Specify Output Format

   text Copy

   For each issue provide: Severity, Category, Location, Description, Fix, Impact

4. Include Action Steps

   text Copy

   When invoked:
   1. Run git diff to see recent changes
   2. Focus on modified files
   3. Begin review immediately

Tool Access Strategy Copy Section

1. Start Restrictive: Begin with only essential tools
2. Expand Only When Needed: Add tools as requirements demand
3. Read-Only When Possible: Use Read/Grep for analysis agents
4. Sandboxed Execution: Limit Bash commands to specific patterns

Example Subagents in This Folder Copy Chapter

This folder contains ready-to-use example subagents:

1. Code Reviewer (`code-reviewer.md`) Copy Section

Purpose: Comprehensive code quality and maintainability analysis

Tools: Read, Grep, Glob, Bash

Specialization:

• Security vulnerability detection
• Performance optimization identification
• Code maintainability assessment
• Test coverage analysis

Use When: You need automated code reviews with focus on quality and security

2. Test Engineer (`test-engineer.md`) Copy Section

Purpose: Test strategy, coverage analysis, and automated testing

Tools: Read, Write, Bash, Grep

Specialization:

• Unit test creation
• Integration test design
• Edge case identification
• Coverage analysis (>80% target)

Use When: You need comprehensive test suite creation or coverage analysis

3. Documentation Writer (`documentation-writer.md`) Copy Section

Purpose: Technical documentation, API docs, and user guides

Tools: Read, Write, Grep

Specialization:

• API endpoint documentation
• User guide creation
• Architecture documentation
• Code comment improvement

Use When: You need to create or update project documentation

4. Secure Reviewer (`secure-reviewer.md`) Copy Section

Purpose: Security-focused code review with minimal permissions

Tools: Read, Grep

Specialization:

• Security vulnerability detection
• Authentication/authorization issues
• Data exposure risks
• Injection attack identification

Use When: You need security audits without modification capabilities

5. Implementation Agent (`implementation-agent.md`) Copy Section

Purpose: Full implementation capabilities for feature development

Tools: Read, Write, Edit, Bash, Grep, Glob

Specialization:

• Feature implementation
• Code generation
• Build and test execution
• Codebase modification

Use When: You need a subagent to implement features end-to-end

6. Debugger (`debugger.md`) Copy Section

Purpose: Debugging specialist for errors, test failures, and unexpected behavior

Tools: Read, Edit, Bash, Grep, Glob

Specialization:

• Root cause analysis
• Error investigation
• Test failure resolution
• Minimal fix implementation

Use When: You encounter bugs, errors, or unexpected behavior

7. Data Scientist (`data-scientist.md`) Copy Section

Purpose: Data analysis expert for SQL queries and data insights

Tools: Bash, Read, Write

Specialization:

• SQL query optimization
• BigQuery operations
• Data analysis and visualization
• Statistical insights

Use When: You need data analysis, SQL queries, or BigQuery operations

8. Clean Code Reviewer (`clean-code-reviewer.md`) Copy Section

Purpose: Readability and maintainability review against clean-code principles

Tools: Read, Grep, Glob, Bash

Specialization:

• Naming, function length, and argument count
• Duplication and dead code
• Comment quality and intent
• Structural clarity over cleverness

Use When: You want a style and maintainability pass distinct from correctness review

9. Performance Optimizer (`performance-optimizer.md`) Copy Section

Purpose: Identify and remediate performance bottlenecks

Tools: Read, Edit, Bash, Grep, Glob

Specialization:

• Algorithmic complexity and hot paths
• Memory allocation and leaks
• Caching and query optimization
• Concurrency and I/O bottlenecks

Use When: Code is measurably slow and you need targeted optimization

Installation Instructions Copy Chapter

Method 1: Ask Claude (Recommended) Copy Section

Describe the subagent you want and let Claude create the file:

Create a project-level subagent that runs tests and fixes failures.
Give it access to Bash, Read, Edit, and Grep.

Claude writes .claude/agents/<name>.md with appropriate frontmatter. Review the generated file, then use it. (The /agents interactive creation wizard was removed in v2.1.198 — ask Claude or edit the file directly instead.)

Method 2: Copy to Project Copy Section

Copy the agent files to your project's .claude/agents/ directory:

# Navigate to your project
cd /path/to/your/project

# Create agents directory if it doesn't exist
mkdir -p .claude/agents

# Copy all agent files from this folder
cp /path/to/04-subagents/*.md .claude/agents/

# Remove the README (not needed in .claude/agents)
rm .claude/agents/README.md

Method 3: Copy to User Directory Copy Section

For agents available in all your projects:

# Create user agents directory
mkdir -p ~/.claude/agents

# Copy agents
cp /path/to/04-subagents/code-reviewer.md ~/.claude/agents/
cp /path/to/04-subagents/debugger.md ~/.claude/agents/
# ... copy others as needed

Verification Copy Section

After installation, verify the agents are recognized by listing the directory:

ls .claude/agents/

You can also ask Claude which subagents are available in the current session, and it will report the built-in and custom agents it can delegate to.

File Structure Copy Chapter

project/
├── .claude/
│   └── agents/
│       ├── code-reviewer.md
│       ├── test-engineer.md
│       ├── documentation-writer.md
│       ├── secure-reviewer.md
│       ├── implementation-agent.md
│       ├── debugger.md
│       ├── data-scientist.md
│       ├── clean-code-reviewer.md
│       └── performance-optimizer.md
└── ...

Related Concepts Copy Chapter

Related Features Copy Section

• Slash Commands - Quick user-invoked shortcuts
• Memory - Persistent cross-session context
• Skills - Reusable autonomous capabilities
• MCP Protocol - Real-time external data access
• Hooks - Event-driven shell command automation
• Plugins - Bundled extension packages

Comparison with Other Features Copy Section

Integration Pattern Copy Section

graph TD
    User["User Request"] --> Main["Main Agent"]
    Main -->|Uses| Memory["Memory(Context)"]
    Main -->|Queries| MCP["MCP(Live Data)"]
    Main -->|Invokes| Skills["Skills(Auto Tools)"]
    Main -->|Delegates| Subagents["Subagents(Specialists)"]

    Subagents -->|Use| Memory
    Subagents -->|Query| MCP
    Subagents -->|Isolated| Context["Clean ContextWindow"]

Observability Copy Chapter

Added in v2.1.139.

API requests originating from a subagent carry two extra HTTP headers so traces and logs can be correlated back to the dispatching session:

The same identifiers are exposed on claude_code.llm_request OpenTelemetry spans as the attributes claude.code.agent.id and claude.code.agent.parent_id. Use them to:

• Attribute API spend to a specific subagent type rather than the parent session
• Reconstruct a chain of agent invocations after the fact (parent_id forms a tree)
• Alert on runaway subagents (e.g., one agent.id accounting for >50% of session spend)

See the OpenTelemetry section in Advanced Features → Telemetry for end-to-end exporter setup.

Additional Resources Copy Chapter

• Official Subagents Documentation
• CLI Reference - --agents flag and other CLI options
• Plugins Guide - For bundling agents with other features
• Skills Guide - For auto-invoked capabilities
• Memory Guide - For persistent context
• Hooks Guide - For event-driven automation

Last Updated: August 19, 2026
Claude Code Version: 2.1.235
Sources:

• https://code.claude.com/docs/en/sub-agents
• https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md
• https://code.claude.com/docs/en/cli-reference
• https://code.claude.com/docs/en/agent-teams
• https://code.claude.com/docs/en/changelog#2-1-172
• https://code.claude.com/docs/en/changelog
• https://github.com/anthropics/claude-code/releases/tag/v2.1.117
• https://github.com/anthropics/claude-code/releases/tag/v2.1.131
• https://github.com/anthropics/claude-code/releases/tag/v2.1.138
• https://github.com/anthropics/claude-code/releases/tag/v2.1.139
• https://github.com/anthropics/claude-code/releases/tag/v2.1.140
• https://code.claude.com/docs/en/model-config
  Compatible Models: Claude Fable 5, Claude Opus 5, Claude Sonnet 5, Claude Sonnet 4.6, Claude Opus 4.8, Claude Haiku 4.5

File: 05-mcp/README.md Copy Chapter

MCP (Model Context Protocol)

This folder contains comprehensive documentation and examples for MCP server configurations and usage with Claude Code.

Overview Copy Chapter

MCP (Model Context Protocol) is a standardized way for Claude to access external tools, APIs, and real-time data sources. Unlike Memory, MCP provides live access to changing data.

Key characteristics:

• Real-time access to external services
• Live data synchronization
• Extensible architecture
• Secure authentication
• Tool-based interactions

MCP Architecture Copy Chapter

graph TB
    A["Claude"]
    B["MCP Server"]
    C["External Service"]

    A -->|Request: list_issues| B
    B -->|Query| C
    C -->|Data| B
    B -->|Response| A

    A -->|Request: create_issue| B
    B -->|Action| C
    C -->|Result| B
    B -->|Response| A

    style A fill:#e1f5fe,stroke:#333,color:#333
    style B fill:#f3e5f5,stroke:#333,color:#333
    style C fill:#e8f5e9,stroke:#333,color:#333

MCP Ecosystem Copy Chapter

graph TB
    A["Claude"] -->|MCP| B["FilesystemMCP Server"]
    A -->|MCP| C["GitHubMCP Server"]
    A -->|MCP| D["DatabaseMCP Server"]
    A -->|MCP| E["SlackMCP Server"]
    A -->|MCP| F["Google DocsMCP Server"]

    B -->|File I/O| G["Local Files"]
    C -->|API| H["GitHub Repos"]
    D -->|Query| I["PostgreSQL/MySQL"]
    E -->|Messages| J["Slack Workspace"]
    F -->|Docs| K["Google Drive"]

    style A fill:#e1f5fe,stroke:#333,color:#333
    style B fill:#f3e5f5,stroke:#333,color:#333
    style C fill:#f3e5f5,stroke:#333,color:#333
    style D fill:#f3e5f5,stroke:#333,color:#333
    style E fill:#f3e5f5,stroke:#333,color:#333
    style F fill:#f3e5f5,stroke:#333,color:#333
    style G fill:#e8f5e9,stroke:#333,color:#333
    style H fill:#e8f5e9,stroke:#333,color:#333
    style I fill:#e8f5e9,stroke:#333,color:#333
    style J fill:#e8f5e9,stroke:#333,color:#333
    style K fill:#e8f5e9,stroke:#333,color:#333

MCP Installation Methods Copy Chapter

Claude Code supports multiple transport protocols for MCP server connections:

HTTP Transport (Recommended) Copy Section

# Basic HTTP connection
claude mcp add --transport http notion https://mcp.notion.com/mcp

# HTTP with authentication header
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

Stdio Transport (Local) Copy Section

For locally running MCP servers:

# Local Node.js server
claude mcp add --transport stdio myserver -- npx @myorg/mcp-server

# With environment variables
claude mcp add --transport stdio myserver --env KEY=value -- npx server

`CLAUDE_PROJECT_DIR` for stdio servers (v2.1.139+)

Every MCP stdio server is spawned with CLAUDE_PROJECT_DIR=<absolute path to repo root> already set in its environment — the same convention used for hooks. Plugin and project .mcp.json files can reference ${CLAUDE_PROJECT_DIR} in the command, args, and env values, and the substitution happens before execve():

{
  "mcpServers": {
    "repo-tools": {
      "type": "stdio",
      "command": "node",
      "args": ["${CLAUDE_PROJECT_DIR}/.claude/mcp/repo-tools.js"],
      "env": {
        "REPO_ROOT": "${CLAUDE_PROJECT_DIR}"
      }
    }
  }
}

Use this when your stdio server needs to read files relative to the project root regardless of where Claude Code was launched.

stdio MCP servers also receive CLAUDE_CODE_SESSION_ID (matching the value passed to hooks and Bash), including when the session is resumed with --resume (v2.1.163+).

SSE Transport (Deprecated) Copy Section

Server-Sent Events transport is deprecated in favor of http but still supported:

claude mcp add --transport sse legacy-server https://example.com/sse

Session Working Directories (roots/list) Copy Section

MCP servers can discover the session's working directories: the launch directory plus all --add-dir/additionalDirectories entries are returned via the MCP roots/list request, and a notifications/roots/list_changed notification is sent whenever the set changes (v2.1.203). The idle timeout now also applies to stdio servers (30 minutes), with a per-server timeout acting as an idle floor (v2.1.203).

Windows-Specific Note Copy Section

On native Windows (not WSL), use cmd /c for npx commands:

claude mcp add --transport stdio my-server -- cmd /c npx -y @some/package

OAuth 2.0 Authentication Copy Section

Claude Code supports OAuth 2.0 for MCP servers that require it. When connecting to an OAuth-enabled server, Claude Code handles the entire authentication flow:

# Connect to an OAuth-enabled MCP server (interactive flow)
claude mcp add --transport http my-service https://my-service.example.com/mcp

# Pre-configure OAuth credentials for non-interactive setup
claude mcp add --transport http my-service https://my-service.example.com/mcp \
  --client-id "your-client-id" \
  --client-secret "your-client-secret" \
  --callback-port 8080

Overriding OAuth Metadata Discovery

If your MCP server returns errors on the standard OAuth metadata endpoint (/.well-known/oauth-authorization-server) but exposes a working OIDC endpoint, you can tell Claude Code to fetch OAuth metadata from a specific URL. Set authServerMetadataUrl in the oauth object of your server config:

{
  "mcpServers": {
    "my-server": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "oauth": {
        "authServerMetadataUrl": "https://auth.example.com/.well-known/openid-configuration"
      }
    }
  }
}

The URL must use https://. This option requires Claude Code v2.1.64 or later.

Authentication Startup Notice and Dynamic-Header Refresh (v2.1.193)

• Startup auth notice (v2.1.193+): At startup, Claude Code surfaces a notice listing any MCP servers that still need authentication, so a server that needs a login isn't left silently non-working.
• headersHelper auto-refresh (v2.1.193+): If you supply custom auth via a headersHelper, the helper is re-invoked automatically when a server returns HTTP 401 or 403. Credentials refresh on the fly without a manual reconnect. See Use dynamic headers for custom authentication.

Claude.ai MCP Connectors Copy Section

MCP servers configured in your Claude.ai account are automatically available in Claude Code. This means any MCP connections you set up through the Claude.ai web interface will be accessible without additional configuration.

Claude.ai MCP connectors are also available in --print mode (v2.1.83+), enabling non-interactive and scripted usage.

Startup note (v2.1.117+): Concurrent connect is the default when both local and claude.ai MCP servers are configured (previously serial), reducing startup latency when multiple servers are in use.

To disable Claude.ai MCP servers in Claude Code, set the ENABLE_CLAUDEAI_MCP_SERVERS environment variable to false:

ENABLE_CLAUDEAI_MCP_SERVERS=false claude

Note: This feature is only available for users logged in with Claude.ai accounts.

MCP Setup Process Copy Chapter

sequenceDiagram
    participant User
    participant Claude as Claude Code
    participant Config as Config File
    participant Service as External Service

    User->>Claude: Type /mcp
    Claude->>Claude: List available MCP servers
    Claude->>User: Show options
    User->>Claude: Select GitHub MCP
    Claude->>Config: Update configuration
    Config->>Claude: Activate connection
    Claude->>Service: Test connection
    Service-->>Claude: Authentication successful
    Claude->>User: ✅ MCP connected!

`/mcp` command Copy Section

Type /mcp inside a session to list connected servers, trigger OAuth flows, and inspect connection state.

• Since v2.1.121, MCP retries the initial connection up to 3 times on transient errors.
• Since v2.1.128, /mcp displays the tool count for each connected server and visually flags servers reporting 0 tools so misconfigured servers stand out at a glance.

MCP Tool Search Copy Chapter

When MCP tool descriptions exceed 10% of the context window, Claude Code automatically enables tool search to efficiently select the right tools without overwhelming the model context.

Note: Tool search requires Sonnet 4 or later, or Opus 4 or later. Haiku models are not supported for tool search.

Bypassing Tool Search per Server (v2.1.121+) Copy Section

If a particular MCP server's tools are needed on every turn, mark its
configuration with "alwaysLoad": true to skip tool-search deferral and
keep its tools always available:

{
  "mcpServers": {
    "always-on-tool": {
      "command": "node",
      "args": ["./tools/always.js"],
      "alwaysLoad": true
    }
  }
}

Use sparingly — every always-loaded tool consumes context that could
otherwise be used for tool search to surface a more relevant tool.

Dynamic Tool Updates Copy Chapter

Claude Code supports MCP list_changed notifications. When an MCP server dynamically adds, removes, or modifies its available tools, Claude Code receives the update and adjusts its tool list automatically -- no reconnection or restart required.

MCP Apps Copy Chapter

MCP Apps is the first official MCP extension, enabling MCP tool calls to return interactive UI components that render directly in the chat interface. Instead of plain text responses, MCP servers can deliver rich dashboards, forms, data visualizations, and multi-step workflows -- all displayed inline without leaving the conversation.

MCP Elicitation Copy Chapter

MCP servers can request structured input from the user via interactive dialogs (v2.1.49+). This allows an MCP server to ask for additional information mid-workflow -- for example, prompting for a confirmation, selecting from a list of options, or filling in required fields -- adding interactivity to MCP server interactions.

Tool Description and Instruction Cap Copy Chapter

As of v2.1.84, Claude Code enforces a 2 KB cap on tool descriptions and instructions per MCP server. This prevents individual servers from consuming excessive context with overly verbose tool definitions, reducing context bloat and keeping interactions efficient.

MCP Prompts as Slash Commands Copy Chapter

MCP servers can expose prompts that appear as slash commands in Claude Code. Prompts are accessible using the naming convention:

/mcp__<server>__

For example, if a server named github exposes a prompt called review, you can invoke it as /mcp__github__review.

Server Deduplication Copy Chapter

When the same MCP server is defined at multiple scopes (local, project, user), the local configuration takes precedence. This allows you to override project-level or user-level MCP settings with local customizations without conflicts.

Recent Lifecycle Fixes (v2.1.136) Copy Chapter

Two long-standing MCP lifecycle bugs were fixed in v2.1.136 — worth upgrading for if you run multi-server setups:

• MCP servers persist across /clear: Servers configured via .mcp.json, plugins, or claude.ai connectors no longer disappear after /clear in VS Code, JetBrains, or the Agent SDK. Earlier versions silently dropped them and required a restart.
• OAuth refresh-token concurrent-refresh fix: Multi-server OAuth setups no longer lose refresh tokens when several servers race to refresh simultaneously. This eliminates the "every morning I have to re-auth" pattern that affected setups with multiple OAuth-protected MCP servers.

MCP Resources via @ Mentions Copy Chapter

You can reference MCP resources directly in your prompts using the @ mention syntax:

@server-name:protocol://resource/path

For example, to reference a specific database resource:

@database:postgres://mydb/users

This allows Claude to fetch and include MCP resource content inline as part of the conversation context.

MCP Scopes Copy Chapter

MCP configurations can be stored at different scopes with varying levels of sharing:

Select a scope when adding a server with --scope (short form -s). Omit it and
Claude Code uses local:

# Project scope — writes to .mcp.json so the team shares it
claude mcp add --scope project --transport http github https://api.github.com/mcp

# User scope — available in every project
claude mcp add --scope user --transport stdio memory -- npx @modelcontextprotocol/server-memory

Using Project Scope Copy Section

Store project-specific MCP configurations in .mcp.json:

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.github.com/mcp"
    }
  }
}

Team members will see an approval prompt on first use of project MCPs. In an untrusted workspace, servers that a repo self-approved via a committed .claude/settings.json are not auto-spawned by claude mcp list/get — they show ⏸ Pending approval until you accept the trust dialog, and enableAllProjectMcpServers is ignored in an untrusted folder (v2.1.196).

MCP Configuration Management Copy Chapter

Adding MCP Servers Copy Section

# Add HTTP-based server
claude mcp add --transport http github https://api.github.com/mcp

# Add local stdio server
claude mcp add --transport stdio database -- npx @company/db-server

# List all MCP servers
claude mcp list

# Get details on specific server
claude mcp get github

# Remove an MCP server
claude mcp remove github

# Reset project-specific approval choices
claude mcp reset-project-choices

# Authenticate an MCP server from the CLI (v2.1.186+)
claude mcp login github

# Sign out of an MCP server (v2.1.186+)
claude mcp logout github

# Import from Claude Desktop
claude mcp add-from-claude-desktop

# Add a server from a JSON blob (useful for scripted setup)
claude mcp add-json events-server '{"type":"stdio","command":"npx","args":["@modelcontextprotocol/server-events"]}'

Note: In JSON configs — .mcp.json, ~/.claude.json, or claude mcp add-json — the type field accepts streamable-http as an alias for http. The MCP specification uses the name streamable-http for this transport, so configurations copied from a server's own documentation work unmodified.

claude mcp login <name> / claude mcp logout <name> are the non-interactive equivalent of the OAuth flow in the /mcp menu — authenticate or sign out without opening it. Add --no-browser to login to complete OAuth over SSH or in a headless session (it redirects the flow through stdin).

Available MCP Servers Table Copy Chapter

Practical Examples Copy Chapter

Example 1: GitHub MCP Configuration Copy Section

File: .mcp.json (project root)

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

Available GitHub MCP Tools:

Pull Request Management

• list_prs - List all PRs in repository
• get_pr - Get PR details including diff
• create_pr - Create new PR
• update_pr - Update PR description/title
• merge_pr - Merge PR to main branch
• review_pr - Add review comments

Example request:

/mcp__github__get_pr 456

# Returns:
Title: Add dark mode support
Author: @alice
Status: OPEN
Reviewers: @bob, @charlie

Issue Management

• list_issues - List all issues
• get_issue - Get issue details
• create_issue - Create new issue
• close_issue - Close issue
• add_comment - Add comment to issue

Repository Information

• get_repo_info - Repository details
• list_files - File tree structure
• get_file_content - Read file contents
• search_code - Search across codebase

Commit Operations

• list_commits - Commit history
• get_commit - Specific commit details
• create_commit - Create new commit

Setup:

export GITHUB_TOKEN="your_github_token"
# Or use the CLI to add directly:
claude mcp add --transport stdio github -- npx @modelcontextprotocol/server-github

Environment Variable Expansion in Configuration Copy Section

MCP configurations support environment variable expansion with fallback defaults. The ${VAR} and ${VAR:-default} syntax works in the following fields: command, args, env, url, and headers.

{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}",
        "X-Custom-Header": "${CUSTOM_HEADER:-default-value}"
      }
    },
    "local-server": {
      "command": "${MCP_BIN_PATH:-npx}",
      "args": ["${MCP_PACKAGE:-@company/mcp-server}"],
      "env": {
        "DB_URL": "${DATABASE_URL:-postgresql://localhost/dev}"
      }
    }
  }
}

Variables are expanded at runtime:

• ${VAR} - Uses environment variable, error if not set
• ${VAR:-default} - Uses environment variable, falls back to default if not set

Example 2: Database MCP Setup Copy Section

Configuration:

{
  "mcpServers": {
    "database": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-database"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    }
  }
}

Example Usage:

User: Fetch all users with more than 10 orders

Claude: I'll query your database to find that information.

# Using MCP database tool:
SELECT u.*, COUNT(o.id) as order_count
FROM users u
LEFT JOIN orders o ON u.id = o.user_id
GROUP BY u.id
HAVING COUNT(o.id) > 10
ORDER BY order_count DESC;

# Results:
- Alice: 15 orders
- Bob: 12 orders
- Charlie: 11 orders

Setup:

export DATABASE_URL="postgresql://user:pass@localhost/mydb"
# Or use the CLI to add directly:
claude mcp add --transport stdio database -- npx @modelcontextprotocol/server-database

Example 3: Multi-MCP Workflow Copy Section

Scenario: Daily Report Generation

# Daily Report Workflow using Multiple MCPs

## Setup
1. GitHub MCP - fetch PR metrics
2. Database MCP - query sales data
3. Slack MCP - post report
4. Filesystem MCP - save report

## Workflow

### Step 1: Fetch GitHub Data
/mcp__github__list_prs completed:true last:7days

Output:
- Total PRs: 42
- Average merge time: 2.3 hours
- Review turnaround: 1.1 hours

### Step 2: Query Database
SELECT COUNT(*) as sales, SUM(amount) as revenue
FROM orders
WHERE created_at > NOW() - INTERVAL '1 day'

Output:
- Sales: 247
- Revenue: $12,450

### Step 3: Generate Report
Combine data into HTML report

### Step 4: Save to Filesystem
Write report.html to /reports/

### Step 5: Post to Slack
Send summary to #daily-reports channel

Final Output:
✅ Report generated and posted
📊 47 PRs merged this week
💰 $12,450 in daily sales

Setup:

export GITHUB_TOKEN="your_github_token"
export DATABASE_URL="postgresql://user:pass@localhost/mydb"
export SLACK_TOKEN="your_slack_token"
# Add each MCP server via the CLI or configure them in .mcp.json

Example 4: Filesystem MCP Operations Copy Section

Configuration:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-filesystem", "/home/user/projects"]
    }
  }
}

Available Operations:

Setup:

# Use the CLI to add directly:
claude mcp add --transport stdio filesystem -- npx @modelcontextprotocol/server-filesystem /home/user/projects

MCP vs Memory: Decision Matrix Copy Chapter

graph TD
    A["Need external data?"]
    A -->|No| B["Use Memory"]
    A -->|Yes| C["Does it change frequently?"]
    C -->|No/Rarely| B
    C -->|Yes/Often| D["Use MCP"]

    B -->|Stores| E["PreferencesContextHistory"]
    D -->|Accesses| F["Live APIsDatabasesServices"]

    style A fill:#fff3e0,stroke:#333,color:#333
    style B fill:#e1f5fe,stroke:#333,color:#333
    style C fill:#fff3e0,stroke:#333,color:#333
    style D fill:#f3e5f5,stroke:#333,color:#333
    style E fill:#e8f5e9,stroke:#333,color:#333
    style F fill:#e8f5e9,stroke:#333,color:#333

Request/Response Pattern Copy Chapter

sequenceDiagram
    participant App as Claude
    participant MCP as MCP Server
    participant DB as Database

    App->>MCP: Request: "SELECT * FROM users WHERE id=1"
    MCP->>DB: Execute query
    DB-->>MCP: Result set
    MCP-->>App: Return parsed data
    App->>App: Process result
    App->>App: Continue task

    Note over MCP,DB: Real-time accessNo caching

Environment Variables Copy Chapter

Store sensitive credentials in environment variables:

# ~/.bashrc or ~/.zshrc
export GITHUB_TOKEN="ghp_xxxxxxxxxxxxx"
export DATABASE_URL="postgresql://user:pass@localhost/mydb"
export SLACK_TOKEN="xoxb-xxxxxxxxxxxxx"

Then reference them in MCP config:

{
  "env": {
    "GITHUB_TOKEN": "${GITHUB_TOKEN}"
  }
}