Commands Build Memory Skills Agents Prompts

# 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

#### Day 2 — Building

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.

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

1 / --
`←` `→` or `Space` to navigate