Claude Code — Complete Beginner's Guide

01

Claude & Anthropic

Understanding the foundation — models, hierarchy, and products

Anthropic is an AI safety company that builds powerful LLMs under the brand name Claude. Think of Anthropic as the parent company (like OpenAI) and Claude as the model family name (like GPT).

All three model families share the Claude prefix: Claude Haiku, Claude Sonnet, Claude Opus. They differ in speed, capability, and cost. For most coding tasks, Sonnet 4.6 is the sweet spot — balanced performance without the premium price of Opus.

💬

Claude Desktop

A web/desktop chat interface — Claude's equivalent of ChatGPT. Good for Q&A and quick generation, but it cannot write files to your system.

⌨️

Claude Code

Runs in your terminal. Has agentic tools that can read/write files, run commands, install packages, and more. The focus of this guide.

🔑

Anthropic API

Pay-per-token programmatic access. Recommended for developers — no subscription lock-in, you only pay for what you use.

02

What is Claude Code?

Architecture, tool calls, and the agentic loop

Normal LLMs respond with text. Claude Code is different — it wraps the LLM in an agentic graph with built-in tools that can act on your computer. When you ask it to "create a PySpark script in the /scripts folder", here's what happens under the hood:

Built-in Tools

📁

read / write / edit

Create, read, and modify files anywhere in your project directory.

🖥️

bash

Run any terminal command — install packages, run scripts, manage git.

🔍

glob / grep

Search and pattern-match across your entire codebase efficiently.

🌐

web_search / web_fetch

Look up documentation, APIs, and real-time information on the web.

💡

Key Insight: Claude Code is NOT magic — it's just an agentic graph. The LLM generates code, then makes tool calls to execute it locally on your machine. You can build your own lightweight version using LangGraph + tool functions, but Claude's implementation handles edge cases and is battle-tested.

03

Installation & Setup

Get Claude Code running on your machine in minutes

Prerequisites

🐍

Python (basic)

Only basic Python required — how to print, create variables. Claude Code does the heavy lifting.

📝

VS Code

Recommended editor. Has a native Claude Code extension for chat-style interaction within your IDE.

💳

API Key or Subscription

Claude Code is not free. Use API credits (pay-as-you-go, recommended for learning) or a Pro/Max subscription.

Step-by-Step Installation

1

Add API Credits (if using API)

Go to console.anthropic.com → Billing and add funds. Start with $10. Credits are valid for a year — no monthly expiry pressure.

2

Install Claude Code on Windows

Open PowerShell and run the install command. For Windows CMD instead, use the alternate command shown in the official docs at claude.ai/code.

 PowerShell
IRM https://claude.ai/install.ps1 | iex

3

Install on macOS / Linux / WSL

 bash
npm install -g @anthropic-ai/claude-code
# or via Homebrew:
brew install claude-code

4

Verify installation & add to PATH

If claude command isn't found, add the install directory to your System Environment Variables → PATH. Then open a new terminal.

 terminal
claude          # should open interactive session
claude --version  # check version (need ≥ 2.1.72 for scheduling)

5

Authenticate & choose model

On first launch, choose: (1) Subscription or (2) Anthropic Console (API). It will open your browser for OAuth. Once done, an API key named Claude Code Key is auto-created in your console.

 claude session
/model     # switch model (haiku=cheap, sonnet=balanced, opus=best)
/cost      # see token cost for current session
/context   # inspect context window usage
/exit      # leave claude code

6

Install VS Code Extension (optional but recommended)

In VS Code → Extensions, search "Claude" → install the official extension (6M+ downloads). This gives you a chat panel inside VS Code, file context awareness, and inline editing.

7

Set up your project with UV

 terminal
pip install uv            # install UV package manager
uv init                  # creates pyproject.toml, .gitignore, etc.
uv sync                  # creates virtual environment
# Windows activate:
.venv\Scripts\activate
# macOS/Linux:
source .venv/bin/activate

⚠️

PATH Gotcha (Windows): After install, if claude isn't recognized, go to System Properties → Environment Variables → Path → Edit → New and paste the Claude install path shown in the terminal output. Then restart your terminal.

04

The Claude.md File

Define project standards that Claude follows on every single prompt

Without guidance, Claude Code uses its own coding conventions. In an organization, you have specific standards — naming conventions, patterns, documentation style, security rules. The claude.md file solves this.

Location & Structure

Create .claude/claude.md at your project root. Claude reads it automatically at the start of every session — you never have to mention it.

 .claude/claude.md
## Project Overview
Data engineering pipeline project using PySpark and dbt.
Processes daily batch loads from 3 source systems into Snowflake.

## Project Structure
- /pipelines   – PySpark transformation scripts
- /models      – dbt models
- /tests       – unit and integration tests

## Coding Standards
- Use **camelCase** for all functions, methods, and variables
- Use **PascalCase** for class names
- Always add type hints to function signatures
- Every function needs a descriptive docstring (Google style)
- Keep functions small, focused on a single responsibility
- Maximum 30 lines per function

## Dependency Management
- Use uv for package management
- Record all dependencies in pyproject.toml
- Use exact versions in production, ranges in dev

## Version Control
- Write meaningful commit messages (imperative mood)
- Create branches for features: feature/description
- Never commit secrets or API keys

✅

Best Practice: Keep claude.md under 200 lines. More context = more tokens on every request. Be specific and concise — LLMs respond to clear, structured instructions, not verbose essays.

💡

Why not put everything in claude.md? Because skills (Section 5) have a smarter loading strategy — their detailed instructions only get injected into context when that skill is invoked, not on every prompt. This saves significant token cost.

05

Skills

Encode institutional knowledge for repeatable, automated workflows

Skills are the backbone of modern Claude Code. They let you define exactly how to perform a task — step by step — so Claude executes it identically every time without you writing a line of code in the prompt.

Folder Structure

 project structure
.claude/
├── claude.md           # ← project standards (loaded every session)
└── skills/
    ├── fetch-api/
    │   ├── SKILL.md    # ← orchestration (only loaded when invoked)
    │   ├── scripts/
    │   │   └── fetch.py  # ← reusable script (saves tokens!)
    │   └── references/
    │       └── api-docs.md
    ├── migrate/
    │   ├── SKILL.md
    │   └── scripts/convert_to_parquet.py
    └── visualize/
        ├── SKILL.md
        └── scripts/visualize_data.py

Writing a Skill (fetch-api example)

 .claude/skills/fetch-api/SKILL.md
---
name: fetch-api
description: Fetches data from multiple APIs asynchronously. Use when you
  want to download fresh data from source systems.
---

## usage

### Step 0 — Environment
Before starting, activate the virtual environment at `.venv`.

### Step 1 — Fetch data
Make async Python API calls (using `httpx`) to these URLs:
- https://raw.githubusercontent.com/.../dim_customer.csv
- https://raw.githubusercontent.com/.../dim_date.csv
- https://raw.githubusercontent.com/.../fact_sales.csv

### Step 2 — Save outputs
Save fetched CSV files to `.claude/skills/fetch-api/data/<timestamp>/`
where <timestamp> is formatted as YYYY-MM-DD_HH-MM-SS.

### Step 3 — Log results
Create a log file at `logs/<date>/fetch-api.log`.
Log: which APIs succeeded, which failed, and any errors encountered.

Invoking a Skill

Direct Invocation (precise)

/fetch-api

Follows your skill steps exactly. No extra interpretation. Best for scheduled/repeatable tasks.

Natural Language (flexible)

"Fetch the data from the APIs using my skills"

Claude identifies the right skill automatically via description matching, then may improvise steps.

Power Move: Scripts Folder

Instead of having Claude generate code every time (wasting tokens + risking inconsistency), pre-write your scripts and tell the skill to just run them:

 migrate/SKILL.md — Step 2
### Step 2 — Run migration
Run the Python script at:
  `.claude/skills/migrate/scripts/convert_to_parquet.py`

# vs. having Claude generate the code every time
# saves 3000+ tokens per invocation

🚀

Skill Creator Plugin: Anthropic ships a skill-creator plugin (installable via marketplace) that asks you guided questions and auto-generates a well-structured SKILL.md. Great for getting started quickly on complex skills.

06

Sub-Agents

Delegate specialized, permission-controlled tasks to lightweight workers

Sub-agents are lightweight, specialized versions of Claude Code that run in isolated context windows. They don't see your main conversation history — only the task they're given. This saves context, reduces cost, and lets you restrict permissions.

Creating a Sub-Agent

 .claude/agents/code-reviewer.md
---
name: code-reviewer
description: Reviews code for quality and best practices. Invoke when
  you want to analyze code in the skills directory and generate
  suggestions. Use this for code audits without modifying files.
model: claude-haiku-4-5-20251001  # cheaper model, sufficient for analysis
memory: project                    # persists memory at project level
tools:
  - read
  - glob
  - grep
# Note: NO write or bash access — cannot change code
---

You are a code reviewer sub-agent. Your role is to analyze code
for quality, patterns, and improvement opportunities. Update your
agent memory with patterns and recurring issues you discover.

When reviewing, write feedback to:
  `.claude/agents/code-reviewer/logs/<date>-review.md`

Key Differences: Skills vs Sub-Agents

📋

Skills = Orchestration

Step-by-step instructions for a specific repeatable task. Think "recipe". Executed by whoever invokes them (parent or sub-agent).

🤖

Sub-Agents = Workers

Specialized agents with their own context window, model selection, and permission set. They use skills, but aren't skills themselves.

07

Agent Teams Experimental

Parallel autonomous agents that communicate with each other

Regular sub-agents report back only to the parent Claude Code. Agent Teams take it further: the parent creates a shared task list and spawns teammates that can communicate directly with each other, divide work, and coordinate without going through the parent for every decision.

⚠️

Beta Warning: Agent Teams are disabled by default and have known limitations around session resumption, task coordination, and shutdown behavior. Don't use for production workloads yet. Enable by adding "experimental_agent_teams": true to your .claude/settings.json.

The key advantage: teammates can self-organize. Teammate A might say "I've fetched the data, Teammate B you can start migration." This reduces round-trips through the parent and enables truly parallel workflows.

08

Plugins & Marketplace

Extend Claude Code with community and Anthropic-built packages

Plugins are packages — skills, tools, or MCP servers — that others have built and published. Instead of writing everything from scratch, you install a plugin and immediately gain that capability.

1

Add Anthropic's Official Marketplace

Run this in your Claude terminal to unlock all official plugins:

 claude terminal
# Official Anthropic marketplace
/marketplace add https://github.com/anthropics/claude-plugins-official

# Community skills hub (includes skill-creator, evaluator, etc.)
/marketplace add https://github.com/anthropics/claude-code-skills

2

Browse and Install Plugins

 claude terminal
/plugin              # open plugin manager
# → Manage plugins → Marketplace → search for what you need
# Available: skill-creator, Figma, GitHub, Notion, Slack, Vercel, Firebase...

3

Enable a Plugin (e.g., skill-creator)

Search "skill creator" in the marketplace and click enable. Then restart the Claude session to load it.

 claude session
# After enabling skill-creator plugin:
I need to create a skill that sends daily pipeline reports to my manager
# → skill-creator auto-invoked, asks guided questions, generates SKILL.md

🔍

Community Resources: Find skills and plugins at skillsmp.io and smithery.ai — community hubs for Claude Code skills. Also check GitHub repos tagged claude-code-skill.

09

MCP Servers

Connect Claude Code to any external tool — Gmail, Playwright, Slack, APIs

Model Context Protocol (MCP) is an open standard (created by Anthropic) that lets any AI client connect to any external tool via a standardized JSON config. Think of it as a USB-C port — the same config works in Claude Code, VS Code, Cursor, or Claude Desktop.

Two Types of MCP Servers

Local (stdio)

Command: "uvx" or "npx"
Runs on your machine
Most MCP servers today

Requires Python (uvx) or Node.js (npx) installed. Communication via stdin/stdout — most secure.

Hosted (HTTP)

URL: "https://..."
Runs on provider's server
Future of MCP

Like a REST API call. No local setup needed. Requires API key. Tavily is a great example.

Adding MCP Servers

Ask Claude Code to add it for you — it will create/update your .mcp.json automatically at project level:

 claude session
Add the DuckDuckGo search MCP server to my project:
{
  "mcpServers": {
    "ddg-search": {
      "command": "uvx",
      "args": ["duckduckgo-mcp-server"]
    }
  }
}
# Claude will create .mcp.json with this config

 .mcp.json — Tavily (hosted)
{
  "mcpServers": {
    "tavily": {
      "type": "http",
      "url": "https://api.tavily.com/mcp?api_key=YOUR_KEY"
    }
  }
}

💡

Free Tavily API Key: Create an account at tavily.com — free tier includes 1,000 requests. Add it as an HTTP MCP server and Claude Code gets real-time, AI-optimized web search capability.

⚠️

Security: Only use trusted MCP servers. An MCP server has access to your system (via Claude's tools) when invoked. Check GitHub stars, read the code, prefer well-known providers like Microsoft's Playwright MCP.

10

Hooks & Automation

Run custom scripts on specific Claude events — no LLM involved

Claude Code exposes lifecycle events (pre-tool-use, post-tool-use, notification, etc.). You can attach hooks — local scripts that run at those events without touching the LLM, using zero extra tokens.

Popular Use Cases

🔒

Security Guardrails

Block dangerous bash commands like rm -rf before they execute. Pre-tool-use hook checks the command and denies if unsafe.

📊

Logging & Observability

Write every tool call to a log file. Track what Claude does across long sessions without any tokens spent.

🔔

Notifications

Use the notification event to send a Slack DM or system sound when Claude needs your input during a long-running task.

✅

Post-task Validation

After file writes, run linting, tests, or schema validation automatically via a post-tool-use hook.

Configuring a Hook

Ask Claude Code to create the hook for you (it writes to settings.json properly):

 claude session (ask Claude)
Create a pre-tool-use hook that runs my script at:
  .claude/hooks/prescript.py
And a post-tool-use hook that runs:
  .claude/hooks/postscript.py

# Claude creates/updates settings.json with the hook config
# settings.json format:
{
  "hooks": {
    "pre_tool_use": [{
      "matcher": "*",
      "command": "python .claude/hooks/prescript.py"
    }]
  }
}

💡

Virtual Env Tip: If your hook scripts use libraries only in your venv, replace python with the full path to the venv python: .venv/Scripts/python.exe (Windows) or .venv/bin/python (Mac/Linux).

11

Scheduling Prompts

Automate recurring tasks with cron-style scheduling

Claude Code 2.1.72+ supports scheduled prompts via the /loop command. Set a prompt to run on a cron schedule — perfect for daily data pipelines, automated reviews, or timed notifications.

 scheduling syntax
# Format: /loop [interval or cron] [prompt]

# Every day at 9 AM — run the data fetch pipeline
/loop "0 9 * * *" invoke my fetch-api skill

# Every 30 minutes — check if build finished
/loop 30m check if the deployment has finished

# Every Monday at 8:30 AM — review open PRs
/loop "30 8 * * 1" summarize all open PRs in my GitHub repo

# Check the cron ID to cancel it later
# Auto-expires after 3 days if not cancelled

# Cancel a specific job
/cron delete <job-id>

# Disable ALL scheduled jobs (add to settings.json or .env)
CLAUDE_CODE_DISABLE_CRON=1

Cron Quick Reference

 cron syntax: minute hour day month weekday
"0 9 * * *"    # Every day at 9:00 AM
"*/30 * * * *"  # Every 30 minutes
"0 8 * * 1"    # Every Monday at 8:00 AM
"0 0 * * *"    # Midnight every night
"0 */2 * * *"  # Every 2 hours, on the hour

⚠️

Requirement: Your machine must be running (terminal open, Claude active) for scheduled tasks to fire. This isn't a background daemon — it runs in your Claude session. For true background scheduling, use a system cron that triggers claude -p "your prompt".

12

Project Integration

Onboard onto any existing codebase in minutes using Claude Code

One of the most powerful applications: you join a project, there's a complex codebase with technologies you might not know deeply — use Claude Code to understand it instantly.

1

Generate a README from existing code

Ask Claude to scan the project and generate structured documentation — even if the code uses advanced or unfamiliar features:

 claude session
I have an Airflow project at ./airflow-project. Read all
the DAGs in the /dags folder and generate a README.md
explaining: project overview, DAG list with descriptions,
task workflows, key dependencies, and how to run locally.

2

Add new features following existing patterns

With the codebase as context, Claude will match your team's patterns automatically:

 claude session
Create a new Airflow DAG for the customer_churn pipeline.
It should follow the same patterns as data_fetch_dag.py —
use the same asset-based triggering approach, same error
handling, same variable naming conventions.

3

Create skills for your domain-specific workflows

Once you understand the project, encode your recurring tasks as skills for the whole team to use:

 example skills for data teams
# .claude/skills/run-tests/SKILL.md
# Step 1: activate venv
# Step 2: run pytest with coverage
# Step 3: report failures in a log

# .claude/skills/deploy-staging/SKILL.md
# Step 1: run linting checks
# Step 2: run unit tests
# Step 3: build docker image
# Step 4: push to staging registry

# /run-tests   /deploy-staging  ← invoke with slash command

🎯

Pro Tip for Teams: Commit your .claude/ folder to git. The claude.md, skills, and agent definitions become shared team standards. Every developer on the team gets the same intelligent, project-aware Claude — no individual setup required.

⌨️

Quick Reference — Slash Commands

All the Claude Code commands you'll use most

 slash commands
── Session ───────────────────────────────────
/model        pick haiku / sonnet / opus
/cost         token cost for current session
/context      context window breakdown (claw.md, tools, memory)
/login        switch between API and subscription
/exit         end session

── Skills & Agents ───────────────────────────
/fetch-api    invoke a skill by its name
/plugin       manage plugins and marketplace
/agents       list registered sub-agents

── Scheduling ────────────────────────────────
/loop 30m     run prompt every 30 minutes
/loop "0 9 * * *"  run prompt at 9am daily
/cron delete <id>  cancel a scheduled job

── Advanced ──────────────────────────────────
/btw          ask a side question without polluting context
/voice        enable voice input (Pro/subscription only)

Claude Code
Master Class

Contents

Built-in Tools

Prerequisites

Step-by-Step Installation

Location & Structure

Folder Structure

Writing a Skill (fetch-api example)

Invoking a Skill

Power Move: Scripts Folder

Creating a Sub-Agent

Key Differences: Skills vs Sub-Agents

Two Types of MCP Servers

Adding MCP Servers

Popular Use Cases

Configuring a Hook

Cron Quick Reference

Claude CodeMaster Class

Contents

Built-in Tools

Prerequisites

Step-by-Step Installation

Location & Structure

Folder Structure

Writing a Skill (fetch-api example)

Invoking a Skill

Power Move: Scripts Folder

Creating a Sub-Agent

Key Differences: Skills vs Sub-Agents

Two Types of MCP Servers

Adding MCP Servers

Popular Use Cases

Configuring a Hook

Cron Quick Reference

Claude Code
Master Class