How to Actually Build Your First AI Agent with Claude Code (Complete Beginner's Course)
learn how to install Claude Code, write your first agent from scratch, and end up with something real: a working agent that reads a folder, spots problems, and writes a report, with no coding experience required.
a chatbot waits for you to ask a question and answers it. an AI agent is different: you give it a goal, and it figures out the steps, reads files, runs commands, and takes action on its own until the job is done. you are not driving every move. you are setting the destination.
that distinction matters because it changes what you can automate. you are not typing prompts one at a time. you are building something that does the work while you focus elsewhere.
What You Need Before You Start
--------------------------------
here is everything required before you touch a single command:
- a Claude account with a paid plan (Pro at $20/month is the minimum; Claude Code is included)
- a Mac running macOS 13 or later, or a Windows PC, or a Linux machine
- an internet connection
- roughly 30 to 45 minutes for the full setup and first build
no prior coding experience needed. every command in this guide is written out in full. you copy, paste, and press Enter.
cost to follow this guide: $0 beyond your subscription. Claude Code is included in all paid Claude plans.
Install Claude Code (Desktop App Route, No Terminal Required)
--------------------------------------------------------------
the easiest path for a beginner is the desktop app. it gives you all of Claude Code's power without needing to learn terminal commands first.
go to claude.ai and download the desktop app for your platform. on macOS, open the .dmg file and drag Claude into your Applications folder. on Windows, run the installer. launch the app, sign in with your Claude account, and click the Code tab at the top center of the screen.
if the Code tab asks you to upgrade your plan, your current plan does not include Claude Code. if it asks you to sign in online, complete the sign-in and restart the app. either way, you will land in a clean workspace once you are in.
what success looks like: you see a blank prompt box with a Code tab active and no error messages. that is your agent workspace. everything you build lives here.
What You Are Going to Build
-----------------------------
you are going to build one specific agent, and you will use it all the way through this guide.
the agent's job: read a folder of text files, find any file that is missing a title line at the top, and write a report called `missing-titles.txt` listing every file that needs fixing.
this is a real, useful task. it shows every core agent behavior: reading files, making decisions, and writing output. and it is simple enough to verify by eye when it works.
Step 1: Create Your Working Folder
------------------------------------
create a new folder on your Desktop called `my-agent`. this is where the agent will work. it can only see and touch files inside this folder, which keeps everything safe and contained.
inside `my-agent`, create a second folder called `articles`. this is where the agent will look for files to check.
now create four plain text files inside `articles`. name them `post-one.txt`, `post-two.txt`, `post-three.txt`, and `post-four.txt`. open two of them and add this as the very first line:
```
Title: My Article
```
leave the other two files completely empty. the agent's job is to find those empty ones.
what success looks like: your folder structure is `my-agent/articles/` and it contains four .txt files, two with a title line and two without.
Step 2: Write the CLAUDE.md Instruction File
----------------------------------------------
CLAUDE.md is a plain text file that Claude Code reads at the start of every session. it is your agent's standing instructions, the equivalent of a job description it never forgets.
inside the `my-agent` folder (not inside `articles`), create a new file called `CLAUDE.md`. open it in any text editor, including Notepad on Windows or TextEdit on Mac, and paste this exactly:
```
My File Checker Agent
Your job
Check every .txt file inside the /articles folder.
What to look for
A valid file starts with a line that reads exactly: Title:
If the first line does not start with "Title:", the file is missing its title.
What to do
What not to do
Do not edit any of the article files. Read only. Write only to missing-titles.txt.
```
save the file. this is the entire brain of your agent. Claude Code will read this before it does anything.
what success looks like: you have a file at `my-agent/CLAUDE.md` and it contains the instructions above.
Step 3: Point Claude Code at Your Folder
------------------------------------------
open the Claude Code desktop app and click the folder icon or the "Open folder" option to navigate to your `my-agent` folder. select it and confirm.
Claude Code will read your CLAUDE.md file automatically. you will not see a confirmation message for this, it happens silently in the background every time you open a folder.
if you are using the terminal instead of the desktop app, open your terminal and run:
```bash
cd ~/Desktop/my-agent
claude
```
the `cd` command means "change directory." it moves you into your `my-agent` folder. typing `claude` starts the agent session from inside that folder.
Step 4: Run the Agent
-----------------------
in the prompt box at the bottom of the Claude Code interface, type this exactly:
```
Read every .txt file in the articles folder. Find any file missing a Title line at the top. Write the results to missing-titles.txt as instructed in CLAUDE.md.
```
press Enter. watch what happens.
Claude Code will show you its work as it runs: which files it is reading, what it finds in each one, and what it writes. this transparency is intentional. you can see every action before it happens and stop it if something looks wrong.
what success looks like: Claude reads four files, identifies two without a title, and creates `missing-titles.txt` in your `my-agent` folder. open that file and you should see the two filenames listed, one per line.
Common Beginner Mistake: The Agent Says It's Done But the File Is Empty
------------------------------------------------------------------------
this happens when the agent writes `missing-titles.txt` but does not actually put anything in it. the cause is almost always a CLAUDE.md instruction that is too vague.
the fix: open CLAUDE.md and make the output instructions more explicit. instead of "list the files," write "write each filename on its own line, like this: post-two.txt." concrete examples in your instructions produce concrete output every time.
if the agent writes the wrong filenames or misses one, check that your article files actually have `.txt` extensions and not `.txt.txt`, which can happen on Windows when file extensions are hidden. turn on "show file extensions" in your File Explorer settings to check.
Step 5: Verify and Extend
---------------------------
open `missing-titles.txt` and confirm it lists exactly the two files you left empty. if it does, your agent worked correctly end to end.
you now have a working agent. it lives in `my-agent`, it reads from `CLAUDE.md`, and it can be run any time you drop new files into the `articles` folder and run the same prompt.
the one clear next step: update CLAUDE.md to also check that each file is longer than five lines. add this under "What to look for":
```
A valid file also has more than 5 lines of content.
If a file has 5 lines or fewer, flag it as "too short" alongside the title check.
```
run the agent again with the same prompt. it will now check two things instead of one, with no changes to your prompt, just a change to the instruction file.
What You Just Built and Why It Matters
-----------------------------------------
you built an agent that reads files, makes decisions, and writes output, without you supervising each step. that is the core pattern behind every more advanced agent you will ever build.
the CLAUDE.md file is the part that scales. every new rule, new check, or new output format you add there changes what the agent does without you changing how you run it. the prompt stays the same. the instructions evolve.
from here, the natural extensions are: checking more file types, writing the report to a different format like CSV, or running the check on a schedule using Claude Code's built-in Routines feature.
questions about any step? drop them below.
