Claude Code Learning Journey
There is no one correct way of using Claude Code
An onboarding guide for non-engineers & engineers alike.
There is no one correct way of using Claude Code
An onboarding guide for non-engineers & engineers alike.
I'll unpack each of these as we go — for now, just let them wash over you.
vibe coding — describing what you want in plain English and hoping the AI nails it
agentic engineering — building guardrails so AI acts like a reliable teammate, not a gamble
progressive disclosure — feeding the AI only what it needs right now, not everything upfront
orchestration — coordinating several AI agents like a conductor leads a band
dumb zone — the stretch where AI has too much context and starts thinking worse, not better
agentic workflows — AI that plans, acts, checks its work, and adapts — multi-step on its own
MCP — a universal adapter letting AI talk to your tools (GitHub, Slack, databases)
hooks — auto-triggers that run your rules before or after the AI does anything
harness — the scaffolding around the model — files, terminal, tools — that turns a chatbot into a worker
compaction — auto-summarizing old chat so the AI keeps going without hitting its memory ceiling
context engineering — deliberately curating what the AI sees so it answers well
context rot — quality decay as the conversation drags on and earlier details blur
prompt engineering — the craft of phrasing requests so the AI understands exactly what you mean
AI slop — low-effort, generic AI output that looks polished but says nothing
hallucination — when AI confidently makes up facts that sound true but aren’t
context bloat — overstuffing the AI’s memory so it slows down and loses focus
one-shot prompting — giving the AI one example and asking it to follow the same pattern
token burn — wasting expensive AI “words” on unnecessary back-and-forth or bloated prompts
Claude Code isn't just Claude. It's Claude (the model) wrapped in a harness with a set of tools — and that wrapper is what turns a chatbot into an agent.
The brain. Knows everything up to its training cutoff. Doesn’t know today’s date, can’t read your files, can’t search the web.
The body around the brain. Manages memory, permissions, how long conversations run, and how the brain talks to tools.
The hands. Read files, edit code, search the web, run commands, spawn helper agents.
Claude Code = Model + Harness + Tools
Ask a bare model “what’s the capital of Pakistan?” — it answers from training data. Ask it “what time is it in Karachi right now?” — it can’t know. That second question needs a tool, exposed through a harness. That’s the difference Claude Code makes — and the rest of this session teaches you how to configure it.
"Write me a weather report for Dubai."
No source specified. No format agreed. No memory of last time. The output varies every run.
Unpredictable. Hard to share. Hard to repeat.
"/weather-orchestrator"
One keystroke. Claude knows the source (Open-Meteo), the format (SVG card), the agent (weather-reporter).
Repeatable. Shareable. Same every time.
Better prompting doesn't fix these. But giving Claude a tool to count letters and a file that says today's date does. That's what agents, skills, and CLAUDE.md are for — and that's what this session teaches.
Even before you set up any structure, how you prompt matters. Specific beats vague. Context beats assumption.
"Give me the weather."
Which city? Celsius or Fahrenheit? From a live API or training data? Claude guesses.
"Fetch the current temperature for Dubai from Open-Meteo and return it in Celsius."
Source named. Location named. Unit specified. No guessing needed.
"Make this better."
Better how? Shorter? More formal? Better structured? Claude will pick one at random.
"Rewrite this in a warmer, less formal tone. Keep it under 100 words."
Tone named. Length constrained. Unambiguous.
You can encode good prompts permanently so you never have to write them again. That's what the next five topics are about.
We're going to learn five concepts using one running example: a weather reporter agent that fetches Dubai's temperature and renders a weather card. Same person — five different angles.
An agent is Claude playing a specific role. Meet the weather reporter — a specialist hired to fetch and report weather data for Dubai. Same Claude, different hat.
Without an agent, you walk into a random kitchen and shout "make me pasta!" — whoever happens to hear you might boil instant noodles or make a five-course Italian meal. With an agent, you're walking up to a specific person with a specific job title. The Italian chef makes pasta the Italian-chef way. Every time.
You ask Claude "What's the weather in Dubai?"
It might guess from training data, search the web, or make something up.
You don't know what it'll do.
The weather-agent has a clear job description:
"Always check the Open-Meteo weather service. Always return temperature in a clean, consistent format."
Same question, same approach, every time.
The difference in one picture: prompting is asking a stranger on the street; using an agent is asking your dedicated specialist.
| Prompting (stranger) | Agent (specialist) | |
|---|---|---|
| Who answers | Whoever happens to be there | The person you hired for this exact job |
| Source of truth | Could be anywhere | Always the official Open-Meteo weather service |
| Format | Whatever comes out | Clean, consistent temperature + unit |
| Twice in a row? | Different each time | Same method, same shape |
Agents don't make Claude smarter — they make it predictable. Same question → same approach → same quality. That's what you need for anything you'll do more than once.
"When Claude spawns an agent, that agent gets its own fresh brain. It can do as much work as it needs, then synthesize its results — only the final report comes back to you."
This connects directly to the weather reporter: the weather-agent works in its own brain — all that web fetching, JSON parsing, and failed attempts stay out of yours. You just get the temperature back.
You don't write an agent from scratch — Claude helps you build one. Type /agents inside Claude Code and a guided menu opens.
Type /agents in Claude Code. A menu appears with your existing agents and an option to create a new one.
/agents
A menu opens listing your existing agents (including weather-agent) plus "Create new agent".
.claude/agents/weather-agent.md — job description, allowed tools, model. Edit it like any document.
Creating an agent is like writing a job description for a new hire. You say what the role is, what tools they get, and how they should behave. Claude drafts the JD; you review and adjust.
Agents are just text files. Anyone on your team can create, share, or edit one. No coding required.
The config block at the top of an agent file controls its identity and capabilities. Here's what the real weather-agent.md uses:
weather-agent
"PROACTIVELY" for auto-invocation
haiku, sonnet, opus, or inherit (default). weather-agent uses sonnet
WebFetch, Read, Write, etc.
weather-fetcher
5
user, project, or local. weather-agent uses project
green
The skills: field is what makes the weather-agent special. It preloads weather-fetcher directly into the agent's brain at startup — before the agent has received a single instruction. The agent doesn't need to be told how to fetch weather; it already knows.
Skills are the specific things the reporter has been trained to do. Our reporter has two: fetch the data, and render it as a card.
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.
orchestration-workflow/weather.svg. This skill is invoked directly by the command.
Each skill has its own knowledge and methods. The reporter uses the right skill for the right step. Claude works the same way.
"If you do something more than once a day, turn it into a skill."
The rule is simple: anything you're explaining to Claude over and over is a skill waiting to be written down. The weather reporter's skills are a perfect example:
weather-fetcher.
weather-svg-creator.
Skills are how repetition becomes reliability. Write it down once, and Claude does it the same way forever — or until you update the skill.
The weather-agent is the person with the job title "Weather Reporter".
It defines the role and behavior: use Open-Meteo, return temperature, track history in memory.
The weather-fetcher skill is the specific training on how to fetch weather data.
It contains exact instructions:
current.temperature_2m from the responseOne 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.
Skills are plain markdown files. If you can write a recipe, you can write a skill.
Create .claude/skills/<your-skill-name>/SKILL.md in your project. That's it.
.claude/skills/weather-fetcher/SKILL.md. Or ask Claude: "Turn this into a skill."
The skill contains instructions, not code. It tells Claude how to do something using its existing tools.
The small config block at the top of a SKILL.md (the "frontmatter") controls how the skill behaves:
/slash-command. Defaults to directory name
false to hide from / menu — weather-fetcher uses this because it's agent-only
haiku, sonnet, or opus
fork to run in isolated subagent context
User-invocable: appears in / menu, user runs it directly (like weather-svg-creator). Agent-preloaded: set user-invocable: false, then list it in an agent's skills: field — it becomes domain knowledge injected into that agent (like weather-fetcher).
Now that you've met the reporter and know their skills, let's understand what they can actually hold in mind at once. Every agent — including the weather reporter — gets its own fresh brain.
Imagine Claude has a brain that holds everything it's aware of right now — your question, every file it's opened, every tool result, every word it's said back to you. If a thought isn't in the brain, Claude can't use it. Simple as that.
When the weather-agent is dispatched, it gets its own fresh brain — and weather-fetcher is pinned into it at startup via the skills: field. Everything you give Claude in a conversation lands in its brain:
1. The brain is finite. It can hold about 1 million tokens — roughly 750,000 words, or a short novel. Big, but not infinite. 2. The brain empties at the end of every chat. When you start a new conversation, Claude remembers nothing from the last one unless you tell it again.
The moment you open Claude Code, certain things land in Claude's brain before you've typed a word. The rest waits in the wings — only loaded when you actually need it. This is called progressive disclosure.
weather-fetcher; the full content loads when the agent runs.
Only descriptions of skills and agents are loaded at startup — the rest is fetched on-demand. That's progressive disclosure. It keeps the brain light.
The more stuff crammed into Claude's brain, the harder it is to focus on what matters. This is called context rot — performance drops as the brain gets crowded.
"Every turn is a branching point." After Claude finishes a response, you don't have to just keep typing. You have five options — and four of them exist to keep the brain clear.
| Option | When to use it |
|---|---|
| Continue | Same task, everything in the brain still matters |
| Rewind (tap Esc twice) | Claude went down a wrong path — jump back and try again |
| /compact | The brain is bloated — summarize and keep going |
| /clear (fresh chat) | Starting a truly new task — wipe the brain clean |
| Subagent | Next step will make a mess — send a helper to do it in their own brain |
When you start a new task, start a new chat. Don't let yesterday's thinking clutter today's brain.
You can't create the context — it's just there, the moment you open a chat. But you can see how full it is, trim it down, or wipe it clean. Three commands give you full control.
/context shows you how full the brain is. /compact summarizes it. /clear wipes it.
/context
Shows a breakdown of how many tokens are used and what's taking up space (system prompt, tools, files, conversation).
/compact or /clear
/compact keeps a short summary so you can continue. /clear wipes everything for a truly fresh start.
Check first with /context. Trim with /compact. Reset with /clear when starting a new task.
The weather reporter consults this at the start of every shift — even though their brain resets overnight. It's the standing instructions pinned in that brain before you've said a word.
Imagine hiring a brilliant new assistant every single morning — someone who forgets everything at 5pm. You'd get tired of re-explaining "we say clients, not customers" and "always CC my manager" over and over. So you pin those rules into their brain before the day starts. That's CLAUDE.md: a short list of standing instructions Claude reads first, every time.
For the weather reporter, CLAUDE.md might contain: "Always report in Celsius unless asked. Always cite Open-Meteo as the source." Here's a non-technical example:
Claude can draft your first CLAUDE.md for you. The next slide shows how.
You don't need to write CLAUDE.md by hand. Claude can look at your project and draft one for you.
Type /init inside Claude Code, in your project folder. Claude does the rest.
/init in Claude Code
Make sure you're in your project folder. No other setup needed.
Running /init is like asking the new hire to read everything on the shared drive before you meet them — they walk in already knowing the project's shape, and they write up what they learned as a handbook for future Claude.
You'll keep improving it over time. But /init gets you to a working draft in under a minute.
"After every correction, end with: Update your CLAUDE.md so you don't make that mistake again. Claude is eerily good at writing rules for itself."
The CLAUDE.md isn't something you write once and forget. It's a living memory of every lesson you've ever had to teach Claude. The workflow:
Keep it short. Under 200 lines. Long CLAUDE.md files get ignored — same as a 50-page employee handbook nobody reads.
Aim for under 200 lines. Files over 200 lines consume more context and may reduce adherence. Put detailed instructions in .claude/rules/ instead.
Claude Code uses two mechanisms to find CLAUDE.md files:
At startup, Claude walks upward from your current directory and loads every CLAUDE.md it finds.
Always loaded immediately.
CLAUDE.md files in subdirectories below you are loaded lazily — only when Claude reads files in those folders.
Loaded on demand.
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.
One word kicks off the whole chain. /weather-orchestrator → agent → skill → SVG card. Commands are the entry point into any workflow.
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."
You've already seen built-in commands in this presentation:
/init
Drafts a CLAUDE.md for your project (Topic 4)
/agents
Opens the agent creator menu (Topic 1)
/context
Shows how full Claude's brain is right now (Topic 3)
/clear & /compact
Reset or summarize the brain (Topic 3)
You can write your own commands the same way. The next slide shows how.
Commands are markdown files too. If you can write a recipe, you can write a command.
Create .claude/commands/<your-command-name>.md. As soon as it's saved, /<your-command-name> appears in Claude Code's slash menu.
.claude/commands/weather-orchestrator.md. The filename becomes the command name.
A command is like a button on a coffee machine. One press, the machine grinds, brews, foams, pours. You don't think about the steps — you just want espresso. Slash commands are buttons you've labelled yourself.
Commands are how you turn a multi-step prompt into a single keystroke that anyone on your team can run.
Watch the weather reporter example run from one keystroke to SVG card output. Five concepts, one orchestrated flow.
This is the core architecture pattern of Claude Code workflows — demonstrated in this very repo by the weather example:
The weather workflow demonstrates both skill patterns in a single flow:
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.
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.
A workflow isn't a separate file type. It emerges when one command calls agents and skills in sequence.
One command at the top. One agent with a skill preloaded for fetching. One skill at the end for output. Wire them in the command file.
.claude/commands/weather-orchestrator.md — the playbook the user types.
.claude/agents/weather-agent.md with skills: [weather-fetcher] in its config — the specialist + their training.
.claude/skills/weather-svg-creator/SKILL.md — invoked directly by the command after the agent returns.
The workflow is the relay race. The command is the starter pistol. The agent is runner one (fetches the data, hands the baton back). The skill is runner two (turns the data into a visual). You don't run the race — you just point and say "go."
Every workflow you'll ever build follows this same shape: Command at the top, Agent + Skill in the middle, Skill at the end. Once you've wired one, the rest are variations on the theme.
Five concepts, one running example
From meeting the weather reporter to wiring the full Command → Agent → Skill chain. The same five pieces compose every workflow you'll ever build.
👤 Agents — the specialist with a job title
🎓 Skills — the training they carry
🧠 Context — the brain that resets each session
📋 CLAUDE.md — the pocket rulebook that survives resets
⚡ Commands & 🎼 Workflow — the trigger that wires it all
github.com/shanraisshan/claude-code-best-practice