Claude Code: The Complete Guide

What This Section Is About

Claude Code is a terminal-based AI programming assistant that goes far beyond chat-based coding help. It reads your entire codebase, writes code across multiple files, runs commands and tests, manages git operations, and iterates autonomously on complex projects for hours while you do other things.

This guide is for intermediate to advanced technical users who want to understand what Claude Code can do, how it works under the hood, and how to use it effectively in real development workflows. For background on Claude's capabilities, see Platform Breakdown.

Note: This guide assumes basic comfort with the command line and development workflows. If you've never used a terminal before, this isn't the right place to start. For non-technical users who want AI to build things, see the /topics/building-apps section on /topics/no-code-automation.

What Claude Code Is and Why It's Different

Chat-based coding help works like this: You paste a function, describe a bug, and get back a suggested fix. You copy the fix, paste it into your editor, and hope it works. This traditional approach is covered in /topics/ai-in-your-tools.

Claude Code works like this: You give it a project-level goal. It reads your entire codebase, makes changes across multiple files, runs commands to test those changes, catches and fixes errors, and repeats until the feature works. You come back hours later to a working pull request.

The difference isn't just convenience. It's the ability to work at the scale of entire projects rather than individual functions.

What Claude Code can do:

• Read and write files anywhere on your system
• Run terminal commands (npm, git, pytest, build scripts, etc.)
• Search across your entire codebase with grep and glob
• Manage git operations (add, commit, push, create branches)
• Spawn specialized subagents for specific tasks
• Use custom skills for reusable workflows
• Iterate autonomously for extended periods
• Work with any programming language or framework
• Connect to external tools via MCP (Model Context Protocol)

What makes it different:

• It operates directly in your development environment, not a chat window
• It maintains session context across hours of work
• It can spawn parallel agents and coordinate complex workflows
• It has a sophisticated system for managing context across long sessions
• It integrates deeply with your actual tools and workflows

The tradeoff: This is a developer tool, not a no-code platform. You need technical knowledge to verify and guide the work. Claude Code is a force multiplier for developers, not a replacement for them.

Getting Started

Installation and Setup

Claude Code is included with Claude Pro and Max subscriptions. As of February 2026, Pro costs $20/month and Max costs $100-200/month depending on usage tier. See the pricing page for current details.

Installation:

# Using npm (recommended)
npm install -g @anthropic-ai/claude-code

# Or using Homebrew on macOS
brew install claude-code

See the official installation guide for alternative installation methods and detailed setup instructions.

Initial setup:

claude auth login

This opens a browser window where you authorize Claude Code to access your account. Once authenticated, you can use it from any terminal. See authentication documentation for troubleshooting.

Your first session:

cd /path/to/your/project
claude

You'll see a welcome message and land in a Claude Code session. From here, you can type requests directly or invoke skills with a slash (like /commit). See the Skills System section below for more on built-in and custom skills.

Basic Commands and Navigation

Once you're in a session, interact with Claude naturally:

You: Read the README and tell me what this project does

Claude: [Reads README.md, summarizes the project]

You: List all TypeScript files in the src directory

Claude: [Uses Glob to find and list files]

Claude Code has access to specialized tools that let it work with your codebase:

• Read: Read file contents
• Write: Create or overwrite files
• Edit: Make targeted changes to files
• Glob: Find files by pattern (like src/**/*.ts)
• Grep: Search file contents
• Bash: Run terminal commands
• Git: Perform git operations

See the tools reference for complete documentation on all available tools.

You don't need to memorize these. Claude knows when to use them.

Your First Real Task

Let's say you want to add error handling to a Node.js project:

You: Add error handling to all API routes in src/routes/. Wrap each route handler
in a try-catch that logs errors and sends a 500 response with the error message.

Claude will:

1. Use Glob to find all route files
2. Read each file to understand the current structure
3. Use Edit to add error handling to each route
4. Run npm test to verify nothing broke
5. Show you a summary of changes

If tests fail, it will read the error output, fix the issues, and test again. This loop continues until tests pass or you intervene.

The Skills System

Skills are how you extend Claude Code with custom workflows and commands. A skill is a reusable prompt that defines how Claude should approach a specific type of task. When you invoke a skill by name, Claude switches into that mode and follows its defined workflow.

This is a key feature of agentic AI — the ability to encode and execute specialized workflows autonomously.

What Skills Are

Skills are invoked as slash commands. When you type /commit, /test, or /deploy-staging, you're invoking a skill. Skills and slash commands are the same thing — the terms are interchangeable.

Each skill is defined in a markdown file (typically SKILL.md) that contains:

• A name and description
• A system prompt that defines how the skill behaves
• Optional configuration for which tools the skill can use
• Optional instructions for when the skill should auto-approve actions

See the skills documentation for the complete skills specification and advanced configuration options.

Built-in Skills

Claude Code comes with several built-in skills available to everyone:

/commit

• Guides you through creating a git commit
• Runs git status and git diff to see changes
• Drafts a commit message based on the changes
• Creates the commit with proper formatting

/test

• Runs tests in your project
• Interprets test results
• Fixes failures and re-runs tests
• Continues until all tests pass

/review

• Reviews recent changes
• Checks for bugs, security issues, and code quality problems
• Suggests improvements

/plan

• Enters plan mode for exploration and design before implementation
• Covered in detail in the Plan Mode section below

You can see all available skills by running /help in a Claude Code session.

Creating Skills: Use the Skill Creator

Here's the thing about writing skills: you shouldn't write them yourself. You should use Claude to write them.

Claude Code includes a native skill called /skill-creator (or just skill-creator) that guides you through creating new skills through conversation. It asks you questions about what you want the skill to do, then generates the SKILL.md file for you.

How to use it:

You: /skill-creator

Claude: I'm the Skill Creator. I'll help you build a new skill by asking you
questions about what it should do. What kind of skill do you want to create?

You: I want a skill that helps me deploy to staging.

Claude: Great. Let me ask you some questions to understand what this skill should
do:

1. What should happen when the skill is invoked? What's the workflow?
2. Are there any preconditions or prerequisites?
3. What tools should this skill have access to?
4. Should any operations require confirmation?
5. What should happen if something goes wrong?

[Claude asks clarifying questions, you answer]

Claude: Based on what you've told me, here's the skill I've created. Would you
like me to write it to .claude/skills/deploy-staging/SKILL.md?

[Shows you the generated skill file]

You: Yes, that looks right.

Claude: [Writes the file] Your skill is now available as /deploy-staging

This is the recommended way to create skills. The skill-creator knows the proper format, asks the right questions, and generates a working skill file. You don't need to memorize the skill specification or markdown format.

Where skills live:

• Project skills: .claude/skills/ in your project directory
• Global skills: ~/.claude/skills/ for skills available across all projects
• Community skills: You can download skills from repositories like anthropics/skills

Thinking About Skills: A Framework

Not everything should be a skill. Here's how to think about when to create one:

Good candidates for skills:

• Repeated workflows — Things you do multiple times with the same steps (deployment, release processes, database migrations)
• Complex multi-step operations — Tasks that require multiple commands, checks, or decisions in a specific order
• Team standards — Workflows that need to be done consistently across a team (code review checklists, testing procedures)
• Specialized knowledge — Tasks that require specific expertise or context that Claude might not have by default

Poor candidates for skills:

• One-off tasks — If you'll only do it once, just tell Claude what to do directly
• Simple commands — Running a single command like npm test doesn't need a skill
• Overly broad goals — "Build my app" is too vague; "Deploy to staging and run smoke tests" is specific enough

The skill-creator will help you figure this out. Part of its job is asking whether your idea actually makes sense as a skill, and it will suggest simpler approaches if a skill isn't the right tool.

Best Practices for Skill Design

Make skills focused and reusable

• Good: A skill for "deploy to staging" or "run database migrations"
• Bad: A skill for "do my job" or "handle the entire release process end-to-end"

Be explicit about permissions

• Use permissionMode: auto for safe, read-only operations
• Use permissionMode: confirm for anything that modifies data or makes irreversible changes

Include error handling

• Tell the skill what to do when things go wrong
• Specify rollback procedures for dangerous operations

Document assumptions

• List any prerequisites (e.g., "assumes Docker is running")
• Specify what the skill expects from the environment

Test your skills

• The skill-creator can help you test skills after creating them
• Try invoking the skill and see if it behaves as expected
• Iterate based on what doesn't work

Context Management and Compactions

One of Claude Code's most important features is how it handles long sessions. You can work on a project for hours, making hundreds of changes, and Claude maintains context throughout. This is particularly important when working with agentic AI systems that need to maintain coherence over extended operations.

How Context Management Works

Every interaction with Claude consumes tokens. Your entire conversation history, all files read, and all command output count toward the context limit. For Claude 4.6, this is 200,000 tokens by default (up to 1 million tokens on higher tiers). See /topics/cost-management for strategies on optimizing token usage.

In a long session, you will hit this limit. When you do, Claude performs a "compaction."

What Compactions Are

A compaction is a process where Claude summarizes and compresses the conversation history to make room for new work. Less important details are summarized or dropped. Critical information is preserved.

What gets preserved:

• The current state of your codebase
• Recent file contents and changes
• Important decisions and their rationale
• Active tasks and their status

What gets summarized:

• Old conversation turns
• Intermediate debugging steps
• Completed tasks
• Verbose output from commands

When Compactions Happen

Compactions happen automatically when the session approaches the token limit. You'll see a notification like:

[Compacting session context to make room for new work...]

This is normal and expected. Claude Code is designed to work across many compactions in a long session.

Keeping Important Context Across Compactions

Sometimes you want to ensure Claude remembers something specific across compactions. You can mark information as important:

You: IMPORTANT: The database migration in migrations/20240215_add_users_table.ts
must be run before the API in src/api/users.ts can work. Don't forget this relationship.

Claude will prioritize preserving this information during compactions.

When Context Issues Arise

Sometimes compactions lose information that matters. You might see Claude forget something you told it earlier.

Signs of context loss:

• Claude asks about something you already explained
• Claude suggests an approach you already rejected
• Claude seems confused about the project structure

How to fix it:

• Restate the important information explicitly
• Use CLAUDE.md files in your project to document important context (see the project instructions guide)
• Consider starting a new session if context becomes too degraded

Subagents: When and How to Use Them

Subagents are specialized Claude instances spawned for specific tasks. Each subagent has its own context, tools, and instructions. They coordinate with the main session to accomplish complex goals. This is a core pattern in agentic AI systems.

The Two Main Benefits of Subagents

Subagents exist for two reasons:

1. Parallel execution

Subagents can run simultaneously. If you have three independent tasks, you can spawn three subagents to work on them in parallel. This is dramatically faster than doing them sequentially.

2. Isolated context (the real power)

When a subagent reads files, searches codebases, or runs commands, all of that context stays in the subagent. The main session doesn't see any of it. The subagent only reports back its findings or results.