Claude Code Learning Journey

From your first conversation to building your first workflow

A multi-day onboarding guide for non-engineers & engineers alike.

The Learning Journey

Two Days, Six Levels

Day 1 builds understanding. Day 2 puts it into practice.

Day 1 — Understanding

1Prompting — Just Ask

2Agents — The Specialist

3Skills — The Training

Day 2 — Building

4Project Memory — CLAUDE.md

5Building Skills & Agents

6Commands & Orchestration

Day 1

Level 1

Prompting (Just Ask)

Like texting a friend who knows a lot — you ask a question and they'll give you an answer. But you have no idea how they got it.

The Big Picture

You've installed Claude Code. Now what?

Day 1 covers three foundational levels — each one gives you more control over how Claude does its work.

Think of it like hiring someone

Each level is a step up in how much you trust and structure the relationship.

1

Prompting Asking a stranger on the street for directions

2

Agents Hiring a specialist who always does things a certain way

3

Skills That specialist having specific training for specific tasks

Prompting In Action

Open your terminal and type claude. You're now in a conversation. Try typing:

what is the weather in Karachi?

Claude will answer — but how it answers is unpredictable. It might:

Pull from its training data (which could be outdated)
Search the web (if web tools are available)
Give you a general answer instead of real-time data

The Limitation

Every time you ask "what's the weather?", Claude might fetch data differently — or not fetch real data at all. There's no guarantee it uses the same source or method twice.

When Prompting Works Great

Prompting is perfectly fine for quick, one-off questions!

🔍

Asking questions about your codebase "what does this file do?"

✏️

Writing or editing documents "rewrite this email to sound more professional"

💡

Brainstorming ideas "give me 5 subject lines for this campaign"

💬

Explaining things "explain this error message like I'm not a developer"

Takeaway

For consistent, reliable results, prompting alone isn't enough. You need more control.

Level 2

Agents (The Specialist)

An agent is Claude playing a specific role — like assigning a job title.

The Restaurant Kitchen

Think of it like this

Without an agent, you walk into a random kitchen and shout "make me pasta!" — whoever hears you might boil instant noodles or make a five-course Italian meal.

Without an Agent

You ask Claude "What's the weather in Dubai?"

It might check its training data, search the web, or make a best guess.

You don't know what it'll do.

With an Agent

A weather-agent has a clear job description:

"Always check the Open-Meteo API for Dubai. Always return the temperature in a specific format."

Same question, same approach, every time.

Prompting vs. Agent

Here's what changes when you use an agent — using the weather-agent from this repo as a real example:

	Prompting	Agent
Source	Could be anywhere	Always Open-Meteo API
Location	Whatever Claude picks	Always Dubai (lat: 25.2, lon: 55.3)
Format	Random paragraph	Clean temperature + unit
Consistency	Different every time	Same method, every time

Takeaway

Agents give you predictability. Same question → same approach → same quality. Not smarter — consistent.

Level 3

Skills (The Training)

A skill is a specific capability that an agent (or Claude itself) can use — like a training manual for a new employee.

The Training Manual

Think of it like this

When someone joins your team, they have a role (agent), but they also go through specific training modules — how to use the CRM, how to write a proposal, how to run a standup. Each training module is a skill.

A Real Person Example

Shayan has many skills:

💻

Engineering skill Can write code

🎮

Gaming skill Knows game mechanics

📖

Reading skill Can digest and summarize long documents

Each skill has its own knowledge and methods. Shayan uses the right skill for the right task. Claude works the same way.

Why Separate Agents and Skills?

Agent = The Person

The weather-agent is the person with the job title "Weather Reporter".

It defines the role and behavior.

Skill = The Training

The weather-fetcher skill is the specific training on how to fetch weather data.

It contains exact instructions:

Call this specific API URL
Extract the temperature from this specific field
Return it in this specific format

The Power

One agent can have multiple skills, and one skill can be used by multiple agents. Skills are reusable building blocks. Agents are the people who use them.

Day 1 Summary

Putting It All Together

Three levels, each adding more control over how Claude works.

The Three Levels

Level 1: PROMPTING
You → "What's the weather?" → Claude figures it out somehow
                                (unpredictable method)

Level 2: AGENTS
You → Weather Agent → Always uses the same approach
                      (predictable method)

Level 3: SKILLS
You → Weather Agent → Uses weather-fetcher skill
                      (predictable method with specific instructions)

Level	What You Control	Best For
Prompting	The question	Quick one-off questions
Agents	The question + who answers	Repeatable tasks
Skills	The question + who answers + how they do it	Critical workflows

Day 1 Complete

You understand the three levels: Prompting, Agents, Skills.

Spend time at Level 1 — just prompt. Get comfortable asking Claude questions in the terminal. The more you use it, the more you'll notice tasks that would benefit from an agent.

Tomorrow: we build them.

Day 2

Level 4

Project Memory

Before building agents and skills, Claude needs to understand your project. That starts with CLAUDE.md.

CLAUDE.md — Your Project's Brain

Think of it like this

When a new person joins your team, they don't just start working — they read the team wiki, the README, the onboarding doc. CLAUDE.md is that onboarding doc for Claude.

Context window diagram showing how the 1M token limit is divided

It's a markdown file at your project root that tells Claude:

1

What the project is "This is a FastAPI backend with a React frontend"

2

How to work in it "Use pytest for tests, follow the existing route pattern"

3

What to avoid "Never modify the auth middleware directly"

Quick Start

Run /init in Claude Code to auto-generate a CLAUDE.md for your project.

What Goes in CLAUDE.md

# CLAUDE.md

## Project Overview
This is a TodoApp with a FastAPI backend and React frontend.

## Key Commands
- npm run dev      # Start frontend
- uvicorn main:app  # Start backend
- pytest            # Run tests

## Architecture
- Routes follow the pattern in routes/todos.py
- Frontend components use Tailwind CSS
- Tests mirror the source tree: tests/test_*.py

## Rules
- Always write tests for new endpoints
- Use the existing Sidebar component for navigation
- Keep CLAUDE.md under 200 lines

Keep It Short

Aim for under 200 lines. Files over 200 lines consume more context and may reduce adherence. Put detailed instructions in .claude/rules/ instead.

How Memory Loads

Claude Code uses two mechanisms to find CLAUDE.md files:

Ancestor Loading (UP)

At startup, Claude walks upward from your current directory and loads every CLAUDE.md it finds.

Always loaded immediately.

Descendant Loading (DOWN)

CLAUDE.md files in subdirectories below you are loaded lazily — only when Claude reads files in those folders.

Loaded on demand.

# Example: running `claude` from /myapp
/myapp/
  CLAUDE.md          # Loaded at startup (current dir)
  frontend/
    CLAUDE.md        # Loaded when you touch frontend/ files
  backend/
    CLAUDE.md        # Loaded when you touch backend/ files

Rules Directory

For topic-specific instructions, use .claude/rules/*.md. Each rule file can target specific file patterns using # Glob: pattern at the top — they only load when Claude works with matching files.

Level 5

Building Skills & Agents

Now that Claude knows your project, let's give it specialized capabilities.

Creating Your First Skill

A skill lives in .claude/skills/<name>/SKILL.md. It's a markdown file with YAML frontmatter.

# File: .claude/skills/weather-fetcher/SKILL.md
---
name: weather-fetcher
description: Fetch current temperature for Dubai from Open-Meteo API
user-invocable: false
---

# Weather Fetcher

To fetch the current temperature for Dubai:

1. Call the Open-Meteo API:
   https://api.open-meteo.com/v1/forecast
   ?latitude=25.2048&longitude=55.2708¤t=temperature_2m

2. Extract current.temperature_2m from the response

3. Return: "The temperature in Dubai is {value}{unit}"

Key Insight

The skill contains instructions, not code. It tells Claude how to do something using its existing tools (like WebFetch). Think of it as a recipe, not a program.

Skill Frontmatter Fields

The YAML at the top of a SKILL.md controls how the skill behaves:

name Display name and /slash-command. Defaults to directory name

description Recommended What the skill does — shown in autocomplete, used for auto-discovery

user-invocable Set false to hide from / menu — becomes background knowledge only

allowed-tools Tools allowed without permission prompts when skill is active

model Model to use: haiku, sonnet, or opus

context Set to fork to run in isolated subagent context

Two Ways to Use Skills

User-invocable: appears in / menu, user runs it directly. Agent-preloaded: set user-invocable: false, then list it in an agent's skills: field — it becomes domain knowledge injected into that agent.

Creating Your First Agent

An agent lives in .claude/agents/<name>.md. Same pattern — markdown with YAML frontmatter.

# File: .claude/agents/weather-agent.md
---
name: weather-agent
description: PROACTIVELY fetch weather data for Dubai, UAE
model: sonnet
tools: WebFetch, Read
skills:
  - weather-fetcher
color: green
---

You are a weather data specialist for Dubai.
Use your preloaded weather-fetcher skill to fetch
the current temperature and return it cleanly.

What Happened

The agent has: a role (weather specialist), restricted tools (only WebFetch and Read), a preloaded skill (weather-fetcher), and a specific model (sonnet for cost efficiency).

Agent Frontmatter Fields

The YAML at the top of an agent file controls its identity and capabilities:

name Recommended Unique identifier — defaults to filename if omitted

description Required When to invoke. Use "PROACTIVELY" for auto-invocation

model haiku, sonnet, opus, or inherit (default)

tools Allowlist of tools. Inherits all if omitted

skills List of skill names to preload into agent context at startup

maxTurns Maximum agentic turns before the agent stops

memory Persistent memory: user, project, or local

color Visual color in task list: red, blue, green, etc.

Agents vs. Skills — Where They Live

# Your project structure
myproject/
  .claude/
    agents/                    # Agent definitions
      weather-agent.md         # The person (role + behavior)
      code-reviewer.md         # Another agent
    skills/                    # Skill definitions
      weather-fetcher/         # Each skill is a folder
        SKILL.md               # The training (instructions)
      weather-svg-creator/
        SKILL.md
    commands/                  # Slash commands
    rules/                     # Conditional instructions
    settings.json              # Team settings
  CLAUDE.md                    # Project memory

	Agents	Skills
Location	`.claude/agents/*.md`	`.claude/skills/*/SKILL.md`
What it is	A role with behavior	Instructions for a task
Runs in	Its own isolated context	Inline or forked context
Has tools?	Yes — own tool allowlist	Uses parent's tools
Analogy	The employee	The training manual

How to Use Your Agent

Once you've created an agent file, Claude can invoke it automatically (if the description says PROACTIVELY) or you can ask Claude to use it:

# In a Claude Code conversation:
Use the weather-agent to get the current temperature in Dubai

Behind the scenes, Claude calls the Agent tool:

# What Claude does internally
Agent(
  subagent_type = "weather-agent",
  description   = "Fetch Dubai temperature",
  prompt        = "Get the current temperature in Celsius"
)

Think of it like this

You're the manager. You say "get me the weather." Claude dispatches the weather-agent (the specialist) into their own workspace. The agent uses their training (weather-fetcher skill) to do the work. They come back with the answer.

Level 6

Commands & Orchestration

Commands are the entry points that tie agents and skills into complete workflows.

Commands — The Entry Point

Think of it like this

If agents are employees and skills are their training, a command is the manager's playbook — "when someone asks for a weather report, first ask them Celsius or Fahrenheit, then dispatch the weather team, then create the visual."

A command lives in .claude/commands/<name>.md:

# File: .claude/commands/weather-orchestrator.md
---
description: Fetch weather and create SVG card
model: haiku
---

1. Ask the user: Celsius or Fahrenheit?
2. Use the weather-agent to fetch Dubai's temperature
3. Use the weather-svg-creator skill to create an SVG card
4. Show the user the result

How to Run

Type /weather-orchestrator in Claude Code. The command orchestrates the entire workflow.

Command → Agent → Skill

This is the core architecture pattern of Claude Code workflows:

The Orchestration Flow

  /weather-orchestrator          COMMAND (entry point)
         |
    Step 1: Ask user C/F?
         |
    Step 2: Agent tool
         |
         v
  weather-agent                   AGENT (specialist)
    skill: weather-fetcher       SKILL (preloaded training)
    tools: WebFetch, Read
         |
    Returns: temp + unit
         |
    Step 3: Skill tool
         |
         v
  weather-svg-creator             SKILL (invoked directly)
         |
    Creates: weather.svg + output.md

Two Ways Skills Are Used

The weather workflow demonstrates both skill patterns in a single flow:

Pattern 1: Agent Skill (Preloaded)

weather-fetcher is listed in the agent's skills: field.

Its full content is injected into the agent's context at startup. The agent reads it like a reference manual.

# In weather-agent.md
skills:
  - weather-fetcher

Pattern 2: Direct Invocation

weather-svg-creator is called directly by the command via the Skill tool.

It runs independently in the command's context, not inside any agent.

# In the command prompt
Skill(skill: "weather-svg-creator")

Day 2 Summary

Today you learned how to build the pieces and wire them together:

Component	Location	Purpose
CLAUDE.md	Project root	Project memory — tell Claude about your codebase
Rules	`.claude/rules/*.md`	Conditional instructions triggered by file patterns
Skills	`.claude/skills/*/SKILL.md`	Reusable instructions — the training manual
Agents	`.claude/agents/*.md`	Specialists with roles, tools, and preloaded skills
Commands	`.claude/commands/*.md`	Orchestrators that tie agents and skills into workflows

The Architecture

Command (entry point) → Agent (specialist with skills) → Skill (reusable instructions). Each layer adds structure and predictability.

Journey So Far

Day 1: Understand — Day 2: Build

You've gone from asking Claude a question to building a complete orchestrated workflow with agents, skills, and commands.

The learning journey continues — hooks, MCP servers, settings, and more.

github.com/shanraisshan/claude-code-best-practice