Your First Agent Workflow

Let's be honest about something before we start.

If you need to check whether a file exists, you're faster than any AI agent. Type ls budget.csv: done in two seconds. The agent would need to think, pick a command, ask permission, then respond. Fifteen seconds for a two-second task.

So why are you reading a chapter about directing agents to handle files?

Because your Downloads folder has 847 files in it. You don't know what's in half of them. Three of them are tax documents you'll need in April. One is a duplicate that's eating 2 GB of disk space. And the file your boss asked about yesterday? It's in there somewhere, buried under six months of random downloads.

You could spend an afternoon sorting through them manually. Or you could describe the problem in one sentence:

You: I have a cluttered Downloads folder. Help me understand what's
in here. How many files, what types, what's taking up space?

That's it. No commands, no technical details, no specifying how to analyze it. The agent ran six commands, self-corrected when its first count was wrong, and produced a complete breakdown in 30 seconds.

The rule of thumb you'll internalize in this chapter: If you can describe the task faster than you can do it, ask the agent. If you can do it faster than you can describe it, just do it. Three files to move? Drag them. Three hundred files to categorize by type, date, and project? That's agent territory.

The pattern you'll learn today (describe the problem, let the agent figure out the solution) applies to data analysis, project management, research, and any domain where you work with General Agents.

The Conversation

Open Claude Code. Here's the full exchange: including the parts most tutorials edit out.

You: I have a cluttered Downloads folder. Help me understand what's
in here. How many files, what types, what's taking up space?

Claude Code: I'll analyze your Downloads folder. Let me take a look.

> Allow Claude Code to run: ls -la ~/Downloads | head -20
> [Y/n]: Y

You have 23 items in your Downloads folder. Actually, let me
recount — that's just the top-level view. Some of those are
folders with files inside them. Let me get the real number.

> Allow Claude Code to run: find ~/Downloads -type f | wc -l
> [Y/n]: Y

You have 847 files in your Downloads folder — much more than the
23 items that ls showed, because many are nested in subfolders.

Pause. Did you catch what just happened? The agent got it wrong the first time: 23 items, and then corrected itself. It didn't hide the mistake or pretend the first answer was right. It noticed that ls only shows the top level, switched to find -type f, and got the real number. That self-correction is what good agent work looks like.

Claude Code: Let me break down what types of files you have.

[Runs: find ~/Downloads -type f -name "*.pdf" | wc -l]
[Runs: find ~/Downloads -type f -name "*.xlsx" -o -name "*.csv" | wc -l]
[Runs: find ~/Downloads -type f -name "*.jpg" -o -name "*.png" | wc -l]
[Runs: find ~/Downloads -type f -name "*.zip" | wc -l]

Here's what I found:

| File Type     | Count | Notes                         |
|---------------|-------|-------------------------------|
| PDFs          | 234   | Documents, reports, receipts  |
| Spreadsheets  | 89    | .xlsx and .csv files          |
| Images        | 156   | Screenshots, photos           |
| Archives      | 43    | .zip files (may contain more) |
| Other         | 325   | Mixed: .docx, .dmg, .exe     |

Now let me see what's taking up the most space.

[Runs: du -sh ~/Downloads]
[Runs: du -ah ~/Downloads | sort -rh | head -10]

Total folder size: 12.4 GB

Your largest files:
1. project-backup.zip (2.1 GB)
2. video-recording.mp4 (1.8 GB)
3. database-export.sql (890 MB)
4. presentation-final.pptx (456 MB)
5. dataset.csv (312 MB)

Just these 5 files account for 5.5 GB. Almost half your folder.

Would you like me to help you organize these, or should I look
for duplicates first?

That took about 30 seconds. You now know:

• Total file count (847)
• Breakdown by type
• Total size (12.4 GB)
• Where the space is going

You didn't run a single command. You described a problem, and the agent solved it.

The Division of Labor

Look at what just happened through a different lens. You described the problem in language: "cluttered Downloads folder." The agent chose the solution in code: ls, find, wc, du. You couldn't have chosen those commands (you don't know bash). The agent couldn't have chosen what to analyze (it doesn't know what matters to you). Neither of you could have done the other's job. That's the insight: the value isn't automation. It's the combination of your judgment with the agent's technical execution.

And Sometimes the Agent is the Wrong Tool Entirely

Not every file task belongs in a terminal:

• Browsing photos: You need to see thumbnails to decide which to keep. The agent sees filenames and metadata. You see memories.
• Network drives and NAS: File operations on mounted network storage can behave differently: latency, permission models, case sensitivity. The agent doesn't know your NAS has a 2-second round trip per operation.
• Decisions that need human eyes: That folder of old photos from college? Don't let an agent bulk-delete based on file size rules. Some decisions aren't computational.

The best collaborators know when to hand off and when to handle it themselves. Acknowledging the agent's limits is part of the skill, not a weakness.

---

The Agent's Toolkit: What Those Commands Mean

The agent ran several commands. Let's decode them.

The Building Blocks

• ls: list files in a folder
• find: find files matching a pattern
• wc: word count (counts lines, words, or characters)
• du: disk usage (measures sizes)
• sort: sort results in order

Anatomy of a Command

Let's break down one command the agent ran:

find  ~/Downloads  -type f  -name "*.pdf"  |  wc -l
  |        |          |          |         |    |
  |        |          |          |         |    +-- -l = count Lines only
  |        |          |          |         |
  |        |          |          |         +-- pipe: "then do this..."
  |        |          |          |
  |        |          |          +-- -name = match this filename pattern
  |        |          |
  |        |          +-- -type f = only Files (not folders)
  |        |
  |        +-- where to search
  |
  +-- the command

Read it left to right: "Find in Downloads, only files, named *.pdf, then count lines."

Common Flags You'll See

Flag	Means	Memory Trick
-l	Lines (or Long listing)	lines
-h	Human-readable (KB, MB, GB)	human
-r	Reverse order	reverse
-s	Summary (totals only)	summary
-a	All (including hidden files)	all

When the agent ran du -sh, that's "disk usage, summary, human-readable."

When it ran sort -rh, that's "sort, reverse order, human-readable": biggest first.

The Pipe: Chaining Tools Together

The pipe (|) connects commands. Output from the left feeds into the right:

find ~/Downloads -name "*.pdf" | wc -l

"Find PDFs, then count them."

Small tools, chained together, solving big problems. That's what makes the shell so powerful.

You don't need to memorize these commands. But recognizing them helps you understand what the agent is doing, and verify it's doing the right thing.

The Pattern

Here's the prompt pattern you just used:

"Help me understand [my problem]. Show me [what I need to know]."

This pattern works because it does two things:

1. Describes the problem, not the solution. You said "cluttered Downloads folder," not "run find and du commands." You let the agent figure out how to help.

2. Specifies the outcome you want. You asked for "how many files, what types, what's taking up space." The agent knew what success looked like.

This is fundamentally different from learning bash commands yourself. You're not memorizing syntax. You're describing problems and letting the agent choose the right tools.

The pattern generalizes. Try these variations:

Your Problem	The Prompt
Messy Desktop	"Help me understand my Desktop. What's here, what's old, what's taking up space?"
Mystery disk usage	"Help me understand where my disk space is going. What folders are largest?"
Project scattered across folders	"Help me understand where files related to [project name] are scattered."
Duplicate photos	"Help me understand if I have duplicate photos. Show me likely duplicates."

The specifics change. The pattern stays the same.

✅ Checkpoint: Do This Now

Stop reading. Open Claude Code and run the survey on YOUR Downloads folder.

Use this prompt (modify if needed):

Help me understand what's in my Downloads folder. How many files,
what types, what's taking up space? Show me the full picture.

After Claude Code finishes, ask it to save the results:

Save this analysis as FILE-INVENTORY.md in a new folder called file-organizer/

You should now have: A file-organizer/FILE-INVENTORY.md file with your actual file analysis.

Don't move to Lesson 2 until you've created this file. Everything that follows builds on understanding YOUR files, not the example files in this book.

What to do if your Downloads folder is empty or tiny: Pick a different folder: Documents, Desktop, or any folder with at least 20 files. Adjust the prompt accordingly.

---

PRIMM-AI+ Practice: Survey Your Downloads Folder

This is a learning cycle used throughout this book: before you run an agent, predict what it will do. After it runs, investigate where your prediction matched and where it did not. This builds the verification habit that makes agent work reliable. Chapter 42 teaches this method in full depth for programming. Here you use it for agent workflows. The five stages — Predict, Run, Investigate, Modify, Make — work the same way: commit to an answer before you see the result, then learn from the gap.

Your goal: direct the agent to analyze a cluttered folder and produce a full breakdown of file types and disk usage.

Predict [AI-FREE]

Before you open Claude Code, write down:

• Which commands do you think the agent will run to count files?
• Will the agent run one command or several? Why might it need more than one?
• What categories of file types do you expect to appear in your Downloads folder?
• Your confidence score from 1 to 5.

Do not ask the agent until those notes are written.

Run

Start your session:

$ claude

Then type the prompt below at the > prompt.

What you tell the agent

Help me understand what's in my Downloads folder. How many files,
what types, what's taking up space? Show me the full picture.

Investigate

First, write your own one-sentence explanation of why the agent ran multiple commands instead of just one. Then ask the agent: "Why did you switch from ls to find? What would have been wrong with using only ls?"

Notice whether the agent corrected itself during the analysis. That self-correction is deliberate behavior, not a bug.

Modify

Change one requirement: run the same survey on your Desktop folder instead of Downloads. Predict whether you expect more or fewer files and a higher or lower total disk size, then direct the agent to confirm your prediction.

Make [Mastery Gate]

Pick a folder you have never surveyed before (Documents, an old project folder, or any folder with at least 20 files). Run the full survey without copying the prompt above. Passing means you receive a breakdown by file type and a list of the five largest files using only your own prompt.

PRIMM Slash Commands Setup

These three commands help you follow the PRIMM-AI+ cycle in your own projects. Create a .claude/commands/ folder in your working project and add one file for each command below. You can reuse these commands in every chapter from here on.

.claude/commands/predict.md

Switch to Plan Mode now. Do not run any commands, create any files, or suggest code until I say "run it."

I am predicting the outcome of: $ARGUMENTS

Wait for me to finish writing my prediction. When I say "run it," execute the task and show me what happened.

.claude/commands/investigate.md

I just ran: $ARGUMENTS

Before I tell you what I expected, walk me through what actually happened step by step. After each step, ask me: "Did this match your expectation?"

Do not summarize until we have gone through every step.

.claude/commands/modify.md

I want to change one thing about: $ARGUMENTS

Before making any changes, ask me:
1. What specifically am I changing?
2. What do I predict the new outcome will be?

Only after I answer both questions should you suggest the modification. Do not implement anything until I say "go."

Try With AI

Prompt 1: Go Deeper

I tried the "help me understand" pattern on my Downloads folder.
Now I want to go deeper. Based on what you found, what should
I investigate next? Pick the most interesting finding and
help me understand that in more detail.

What you're practicing: Iterative prompting. One analysis leads to the next question. You're building a habit of drilling down, not stopping at the first answer.

Prompt 2: Translate to a new domain

The "help me understand [problem], show me [what I need]" pattern
worked for files. I want to apply it to something else.

Help me understand my recent shell history. What commands have I
run most often? What patterns do you see in how I use my computer?

What you're practicing: Pattern transfer. The same prompt structure works for different problems. You're learning that General Agents respond to well-structured requests regardless of domain.

Prompt 3: Reflect on the agent's approach

I watched you analyze my Downloads folder. You used commands
like find, wc, and du.

Why did you choose those specific commands? What alternatives
did you consider? What would you have done differently if I'd
asked a slightly different question?

What you're practicing: Understanding agent reasoning. By asking the agent to explain its choices, you learn how it thinks. This makes you better at directing it in the future.

Prompt 4: The Bash Tutor

Break down this command for me piece by piece:

du -ah ~/Downloads | sort -rh | head -10

What does each part do? What do the flags like '-ah', '-rh',
and '-10' mean? Teach me to read this command.

What you're practicing: Just-in-time learning. Instead of memorizing a textbook, you ask the agent to teach you the specific syntax relevant to the problem you just solved. The agent becomes your tutor, explaining commands in context.

---

Flashcards Study Aid

Your Downloads folder is visible now. But visibility creates a new problem. You can see exactly what's there, and some of it matters. Tax documents. Financial spreadsheets. Irreplaceable photos buried under random downloads. If the next step goes wrong, those files could disappear. And unlike code, your files don't have git revert.