Quickstart — your first agent in 5 minutes

The shortest path from zero to a running agent that reads files in your repo and tells you what it sees is five minutes in your terminal.

Prerequisites

macOS / Linux / WSL2
Node 22+
A working Claude Code installation (or GCP Vertex configured — see Setup)
An empty directory: mkdir my-first-agent && cd my-first-agent

Step 1 · Create the agent’s home

mkdir -p .claude/agents

Step 2 · Write its SOUL

Create .claude/agents/file-reader.md:

---
agent_id: file-reader
model: claude-sonnet-4-6
---

# Identity
I am a file-reader. I read files in the working directory and summarise them.

# Workflow
When invoked:
1. List files in the current directory
2. Read the most recent .md or .txt file
3. Print a 3-line summary
4. Exit

Step 3 · Drop a file to read

echo "# Hello World\n\nThis is my first file.\nLet's see if the agent reads it." > sample.md

Step 4 · Invoke

claude --agent file-reader

You should see:

[Reading sample.md...]
Summary:
- The file is titled "Hello World"
- Contains 3 short lines of plain prose
- Functions as a hello-world test for the file-reader agent

That’s it. You have a working agent.

Step 5 · Add a tool

To make the agent useful, give it a tool. Add an MCP server reference to the SOUL:

mcp_servers:
  - filesystem

Now the agent can read across the whole directory tree, not just the working dir. Try it on a real project.

What just happened

Step	What LIFEOSAI did
1	You created an agent home — `.claude/agents/` is where SOULs live
2	You wrote a SOUL — identity + workflow + (optionally) tools
3	You gave it raw material — files in the working directory
4	You invoked it — Claude Code loaded the SOUL, ran the workflow, printed result

The same pattern scales. The 9-agent Guardrail Lab is nine of these SOULs plus skills plus an orchestration layer that wakes them on schedule.