Your first AI agent lives in a folder

From chat to agent

What you will build, and why it is worth it. You do not need to install anything yet.

When you use ChatGPT, Claude or Gemini in the browser, three things happen:

• Every chat starts almost from zero. Some apps remember a little, but you do not decide what. You explain again who you are and what you want.
• You are the messenger. You copy text from your files, paste it in the chat, copy the answer and paste it somewhere else.
• It cannot touch your files. It cannot open your notes, add your workout to a table, or save a PDF on your computer.

An agent fixes all three. It is an AI model (the "brain" that understands and writes text) that can also act, not only talk: read files, write them, and follow several steps on its own. To act, it needs an app on your computer that gives it those hands, and a folder to work in.

The endless chat trap

Because each new chat starts almost from zero, many people do the logical thing: they open one chat for one subject (their classes, their diet, their renovation) and use it for weeks. That way they do not have to explain everything again. But this creates another problem, and almost nobody sees it.

Everything the model reads to answer is called the context: its rules, the whole conversation and your new message. The context has a maximum size. When an endless chat fills it, the app must make room: depending on the app, it compacts the old messages into a summary, or stops reading them. It does not tell you, and details get lost on the way.

And even when everything fits, a huge context works worse. Think of it like this: if I give you one page and ask you something about it, you will almost surely get it right. If I give you the whole Bible and ask the same question, it is much easier to miss something. A model is the same: the longer the context, the harder it is to keep every detail in mind.

An agent with a folder solves this, because what matters lives in files, not in the chat. So you can open a new chat for each task, with a clean context, and the agent reads only the files that the task needs.

And on top of that, an agent can…

Beyond remembering, working in a folder opens up things that a chat does not do:

• Create real files on your computer. A page to print, a table for Excel and, if your app can, a PDF or a Word file, saved straight into your folder.
• Work with many files. In a chat you attach a few. In a folder you can have hundreds or thousands: 300 scanned invoices, for example. The agent opens them one by one and leaves you a table with the total for each month. It takes time and uses up your plan, but there is no limit on how many files you can give it.
• Use programs on your computer, with your permission: sort photos, convert documents or do exact sums with a script.
• Leave a trail. Everything it does stays in files that you can check, fix or delete.

So the agent you will build has three parts:

• The model, the brain. A company (Anthropic, OpenAI, Google) or an open project makes it. It almost never lives on your computer: it is on the internet.
• The app, the hands. A desktop program that connects the model to your computer. It lets the model read and write files, and it asks you for permission first.
• The folder, the home and the memory. It holds the agent's instructions, what it must remember and what it gives you. It is yours, and you can always open it.

Choose your example

The guide is the same for everyone. Only what the agent knows how to do changes. Choose the example that is closest to your case; later you can adapt it to anything.

• StudentA tutor that asks you exam questions, remembers what you already know and keeps track of your assignments.
• TeacherA helper that makes worksheets and keeps track of how each class group is doing.
• Health and fitnessA coach that logs your workouts and meals and tells you how close you are to your goal.
• JournalA journal that saves each day and helps you see what repeats.
• Home renovationA project manager for your bathroom or kitchen: steps, contacts and budget.

Without JavaScript you will see all five examples in each step, each with its name. Follow only yours.

Step 1 of 8

Choose your app

You choose and install the program that connects the model to your folder.

Here I just call it "the app". If you see the word elsewhere, its technical name is a harness: the part that wraps the model and gives it tools.

You need a computer (Windows, Mac or Linux), not a phone: the agent works with the files on your computer.

Each app works with some accounts and not with others. So the best app for you depends on what you already pay for. Mark what you have:

This table sums up the advice:

Step 2 of 8

Create the folder

You create the agent's home.

A folder is a container on your computer that holds files. A file is a document with a name, and its ending (.md, .csv, .pdf) tells you what kind of content it holds.

The agent only sees what is inside its folder. That is good: you decide what it knows and what it does not. But remember that it sends what it reads to the model, on the internet, so that it can answer. Do not put anything in the folder that you would not tell that company.

1. Create a folder on the Desktop (or in Documents, if you prefer). On a Mac: right-click on the Desktop, "New Folder". On Windows: right-click, "New", "Folder".
2. Give it a name with no spaces and no accents, for example: Student my-study-tutor Teacher my-class-helper Health my-coach Journal my-journal Renovation bathroom-renovation . Simple names avoid problems with some apps.
3. Inside it, create two folders: data and exports. The agent will create the rest later.

When you finish the guide, the folder will have these parts. Each one has a colour, the same everywhere on this page. Tap a part to see what it is for and who reads it.

Did you know? If you copy the folder to another computer, the agent travels with it: its instructions and its memory are inside. And if you prefer to start from a ready-made one, download your example and keep reading to understand each part.

Step 3 of 8

Open the folder in your app and say hello

You connect the app to the folder and check that the agent can see it.

From here on, the agent does almost everything: you tell it what you want, and it creates the files.

Now write your first message:

Hello. What is in this folder?

You will see something like this. The agent uses its tools (read, write, search) and shows you each step:

The robot is the agent; the person on the right is you.

Each app has a permission mode: it decides what the agent does on its own and what it asks you first. At the start, choose the most careful mode of your app (the one named above). Some ask you before every change; others change files inside your folder without asking, but ask you before they leave it, use the internet or run programs. When it asks for permission, read what it wants to do and accept if it makes sense. For example, if it asks to create the file that you just asked for, accept. When you trust it, you can give it more freedom inside that folder.

If it does not see the folder, check that you chose the right folder and not the whole Desktop. On a Mac, the first time, the system asks if the app can access the Desktop: click "Allow". If you said no, go to "System Settings > Privacy & Security > Files and Folders", and turn on your app.

Step 4 of 8

Give it instructions: the AGENTS.md file

You tell the agent who it is and how it must work, one time and for good.

That goes in a file called AGENTS.md, at the root of the folder (directly inside it, not in a subfolder).

Remember the context, from the start: the model remembers nothing between messages. Each time you write, the app sends it everything it must keep in mind, all at once. This is what goes in:

(Skills are recipes for tasks that you repeat; you will see them in step 6.) That is why AGENTS.md is so powerful: it is in the context of every conversation. What you write there, the agent always keeps in mind. And it is an open standard: Claude, ChatGPT (Codex), Antigravity, Goose and many other apps read it. So you do not depend on any one app.

Your AGENTS.md

This is the AGENTS.md for your example. Read it: it says who the agent is, what it does, where it keeps each thing, and a few rules. Change the details that are yours (your school year, your groups, your goal) and keep the structure.

# My study tutor

You are my personal tutor. I am in the last year of high school.
You speak to me in English, with short sentences and examples.

## What you do
- You explain the topics in a simple way, with examples.
- When I ask, you give me exam-style questions, one at a time, and you correct me.
- You keep track of what I already know well and what I find hard.
- You remind me of the assignments that are due.

## Where you keep things
- data/subjects.md: my subjects, their topics and the exam dates.
- data/progress.md: a table with each topic, its status (new, in progress, mastered), the date of the last review and what I find hard.
- data/assignments.md: each assignment with its due date and its status.
- data/notes/: my notes, one file per topic.
- exports/: the practice exams and the summaries.

## Rules
- Before you answer, read what you need from data/.
- At the end of each study session, update data/progress.md.
- If something is not in my notes, tell me. Do not make it up.
- To prepare a practice exam, use the practice-exam skill.

# My class helper

You are my class helper. I teach maths in Year 4 (4th grade), to two groups: 4A and 4B.
You speak to me in English, in a clear and practical way.

## What you do
- You make worksheets with exercises that fit the level of each group.
- You keep track of how each group is doing: which topics we have covered and what is hardest.
- You help me plan the week.

## Where you keep things
- data/groups.md: each group, the current topic and what it finds hardest.
- data/grades.csv: the grades, with the columns student,group,activity,date,grade. One row per student and activity.
- data/calendar.md: the planned lessons and assessments.
- exports/: the worksheets and the plans, ready to print.

## Rules
- Never save the full names of students. Use their class list number (A01, A02…).
- The worksheets have the answers on a separate page.
- Before you prepare anything, read data/groups.md.
- To prepare a worksheet, use the make-worksheet skill.

# My coach

You are my personal coach. My goal is in data/goal.md.
You speak to me in English, with encouragement but without exaggeration.

## What you do
- You log each workout and each meal that I tell you about.
- You suggest workouts based on my routine and on how I am doing.
- Each week you tell me how close I am to my goal, with numbers.

## Where you keep things
- data/goal.md: my goal, my starting point and the deadline.
- data/log.csv: one row per entry, with the columns date,type,detail,amount,unit. For example: 2026-10-20,run,easy,5,km. The type is run, gym or meal. A run takes two rows, one in km and one in min. Gym goes in min and meals go in kcal.
- data/routine.md: my weekly routine.
- exports/: the weekly summaries.

## Rules
- Write in data/log.csv as soon as I tell you something. Do not wait until the end.
- If I ask you something medical, or I tell you about a pain that does not go away, tell me to ask a professional.
- For the weekly summary, use the weekly-summary skill.

# My journal

You are my personal journal. I tell you how my day went and you put it in order.
You speak to me in English, calmly. You do not judge: you listen and you put things in order.

## What you do
- You save what I tell you each day, in my own words.
- You ask me one or two questions if I want to go deeper, never more.
- When I ask, you help me see what repeats: people, topics, moods.

## Where you keep things
- data/entries/: one file per day, with the date as its name (2026-10-25.md).
- data/themes.md: the topics and the people that come up often.
- exports/: the summaries that I ask for.

## Rules
- Each entry starts with two lines: the date (# 2026-10-25) and the mood in one word (Mood: calm).
- Do not change what I wrote: if you summarise it, save the summary separately.
- To close the day, use the close-the-day skill.

# Bathroom renovation

You are the project manager for my bathroom renovation. I know nothing about building work: explain everything to me.
You speak to me in English, in a clear and orderly way.

## What you do
- You keep the list of renovation steps and their status.
- You keep the contacts of the professionals and what we discussed with each one.
- You keep the budget: what we planned and what we spent.
- You warn me about anything that blocks the next step.

## Where you keep things
- data/steps.md: each step in order, with its status (to do, in progress, done) and what it depends on.
- data/contacts.md: each professional, their phone number and a summary of each conversation.
- data/measurements.md: the bathroom measurements that I give you.
- data/budget.csv: one row per item, with the columns item,planned,spent.
- data/ideas/: photos and notes with ideas for the design.
- exports/: lists to take to the shop, summaries, simple plans.

## Rules
- Before you answer, read data/steps.md.
- Do not accept a measurement that I did not give you.
- To prepare a call with a professional, use the prepare-call skill.

To create it, the easiest way is to ask the agent. Click "Copy" on the text above. Then write this message and, under it, paste the text with Ctrl + V (Cmd + V on a Mac):

Create an AGENTS.md file in this folder with this content:

(paste the text here)

If you create it by hand on Windows, make sure that it does not end in .txt: Windows hides the end of file names, and the agent would not find the file. Further down, in "I prefer to create it by hand", you can see how to avoid this.

Now start a new conversation, because the app reads the AGENTS.md at the start. Ask:

Who are you and what can you do?

If it answers with what you put in the AGENTS.md, it works.

Step 5 of 8

Give it memory: the data folder

You create the files where the agent keeps what it must remember.

This is what turns a chat that forgets into an agent that knows you.

Your AGENTS.md already says which files to use and when to update them. So you only have to ask:

Create the data files that the AGENTS.md lists. To fill them in, ask me the questions you need, one at a time.

The agent will ask you questions and create the files. In your example:

Open the files yourself too. A .md file opens in any text editor (TextEdit, Notepad); a .csv file opens in Excel or Google Sheets. They are yours: if something is wrong, correct it by hand or tell the agent. And if one day you want to start again from zero, delete them.

Why is ChatGPT's memory not enough? ChatGPT's memory is a short list of notes that the app keeps, and it only works in that app. You can read your files in full, correct them and take them to any app.

Step 6 of 8

Teach it recipes: skills

You teach the agent a task that you repeat, step by step, so that it always does it equally well.

That is a skill: a recipe.

You could put all the steps in the AGENTS.md, but they would take up the context of every conversation, even the ones that do not need them. A skill is smarter: the agent only sees its name and one sentence that describes it. When you ask for something that matches that sentence, it opens the full recipe and follows it.

A skill is a folder with a SKILL.md file inside. The folder has the same name as the skill. That file starts with a block between two --- lines with the name and the description, and then come the steps. The skills in the agent's folder go here:

On a Mac, the dot at the start hides the folder. Finder does not show folders whose name starts with a dot, and it does not let you create them. To see them, press Cmd + Shift + . in Finder. On Windows you see them normally. The easiest way, on both: let the agent create it.

This is the skill for your example:

---
name: practice-exam
description: Prepares a practice exam on the topics I ask for, with questions like the ones in class. Use it when I want to practise for an exam.
---

# Prepare a practice exam

1. Ask me which subject and which topics are in the exam, if I have not said so.
2. Read my notes on those topics in data/notes/ and their status in data/progress.md.
3. Write 10 questions: 4 on the topics I find hardest and 6 on the rest. Mix short questions and longer written ones.
4. Save the exam in exports/exam-SUBJECT-DATE.md, with the answers at the end.
5. Ask me if I want to do it now with you, one question at a time.
6. When we finish, update data/progress.md with what I got right and wrong.

---
name: make-worksheet
description: Prepares a worksheet of exercises for a group and a topic, ready to print. Use it when I ask for a worksheet or exercises for class.
---

# Make a worksheet

1. Ask me the group and the topic, if I have not said so.
2. Read data/groups.md to know the level of the group and what it finds hardest.
3. Write 8 exercises, from easiest to hardest. The first two come with a worked example.
4. Save the worksheet in exports/worksheet-GROUP-TOPIC.html, with no spaces or accents in the name (for example worksheet-4B-fractions.html), with large letters and space to answer, and the answers on a separate page.
5. Tell me how to print it: open it in the browser and use Print.

---
name: weekly-summary
description: Makes the summary of the week's workouts and meals and compares it with the goal. Use it when I ask for the summary or ask how I am doing.
---

# Weekly summary

1. Read data/log.csv and keep only the last 7 days.
2. If scripts/summary.py exists, run it to get the totals. If not, add them up yourself, carefully.
3. Compare with data/goal.md: am I on track?
4. Write the summary in exports/summary-DATE.md: totals, what went well and one single thing to improve.
5. Tell me the summary in three sentences.

---
name: close-the-day
description: Saves the day's entry from what I tell you. Use it when I say that I want to close the day or write in the journal.
---

# Close the day

1. If I have not told you about my day, ask me: "How did today go?".
2. Listen. Ask me two questions at most to understand it better.
3. Save the entry in data/entries/DATE.md in the format that the AGENTS.md gives: the date, the mood and what I told you, in my own words.
4. If a person or a topic comes up that is already in data/themes.md, add one mention to it. If it is new and I have named it twice, add it.
5. Say goodbye with a short sentence.

---
name: prepare-call
description: Prepares a call or a visit with a professional for the renovation, with what to ask and what to decide. Use it when I am going to talk to a plumber, a builder, an electrician or a shop.
---

# Prepare a call

1. Ask me who I am going to talk to, if I have not said so.
2. Read data/steps.md, data/contacts.md and data/budget.csv.
3. Write a short list: what I must tell them, what I must ask them and what we must decide.
4. Save it in exports/call-PROFESSIONAL-DATE.md.
5. After the call, ask me what we discussed and update data/contacts.md and data/steps.md.

To create it, ask the agent, with the text pasted:

Create a skill with this SKILL.md, in the skills folder that this app uses:

(paste the text here)

Then, in a new conversation, ask for something that matches the description. You will see that it opens the skill and follows its steps:

Make me a practice exam on topic 3.

Make me a multiplication worksheet for 4A.

How am I doing this week?

I want to close the day.

Tomorrow I am calling the plumber. Prepare the call for me.

Step 7 of 8 · optional

Fixed tools: the scripts folder

You give the agent a tool that always gives the same result. You can skip this step.

It is useful for counts, sums and dates.

A model writes very well, but it calculates like a person in a hurry: almost always right, sometimes wrong. A script is a small program that does an exact calculation, the same way every time. You do not have to write it or run it: the agent does that.

Write a script in scripts/what-to-review.py that reads the table in data/progress.md and tells me which topics I have not reviewed for more than 7 days, from the oldest to the most recent. Add to the AGENTS.md, under Rules, that you use it when I ask what I should review.

Write a script in scripts/averages.py that reads data/grades.csv and calculates the average of each group and of each activity. Add to the AGENTS.md, under Rules, that you use it when I ask for averages or a summary of grades.

Write a script in scripts/summary.py that reads data/log.csv and adds up the workout minutes and the kilometres of the last 7 days, counting back from the most recent date in the log. Add to the AGENTS.md, under Rules, that you use it for the summaries.

Write a script in scripts/mood.py that reads the entries in data/entries/ and counts how many days of each mood there were in each month, from the "Mood:" line. Add to the AGENTS.md, under Rules, that you use it when I ask how I have been.

Write a script in scripts/budget.py that reads data/budget.csv and gives the total planned, the total spent and the items that go over what was planned. Add to the AGENTS.md, under Rules, that you use it when I ask about money.

You do not need to know how to program. If the agent asks you to install something (such as Python, the language of these scripts) and you do not want to, say no and skip this step; on a work computer, you may not be allowed to. On a Mac, a window can appear that offers to install the "command line developer tools": you can say no to that too. The agent still works: it will do the calculations itself, carefully.

Step 8 of 8

The results: the exports folder

You ask the agent for something finished, to use outside the conversation.

It will save it in exports, so you always know where to look.

Make me a one-page summary of the topic I find hardest, to review on the bus.

Make me a fractions worksheet for 4B.

Make me this week's summary.

Make me a summary of this month: the best, the worst and what repeats.

Make me the list of materials for the bathroom shop, with the measurements from data/measurements.md.

Which format should you ask for?

• Markdown (.md) to read it yourself or to give it to another agent.
• An HTML page (.html) for something that looks nice: it opens in the browser and you print it from there.
• CSV (.csv) to open in Excel or Google Sheets. If Excel puts everything in one column, use "Data > From Text/CSV" and choose the comma as the separator.
• PDF or Word if your app can create them. Ask it: "Can you create a PDF?".

Check your agent

Check that your folder has everything in its place, when you finish or when something does not work.

You can also check it by hand, or ask the agent: "Check that the folder matches this list".

• There is an AGENTS.md file at the root, with that exact name.
• The data folder has the files that the AGENTS.md names.
• Your app's skills folder has one folder per skill, each with its SKILL.md. On a Mac, press Cmd + Shift + . to see it.
• The exports folder exists. The scripts folder is optional.
• In a new conversation, the agent knows who it is without you explaining it.

Adapt it to your case

Create an agent for something that is not in the five examples: your job, a hobby, a project.

The steps are the same; only the AGENTS.md changes.

The easiest way is to let the agent interview you. In a new folder, open it and write:

I want an agent that helps me with (your task). Ask me questions, one at a time, about what I do and what I need. When you have enough, write an AGENTS.md with this template and create the folders that it names.

And paste this template under it:

# (Your agent's name)

You are (who it is: my helper for…, my tutor for…).
You speak to me in (language), (in what tone).

## What you do
- (The three or four tasks that you will ask for most.)

## Where you keep things
- data/(file).md: (what it holds).
- exports/: (what you give me).

## Rules
- (What it must always do.)
- (What it must never do.)

Some ideas to get you started:

• Human resources: the open hiring processes, their stages and the questions for each interview, with candidates by code, never by name.
• Research: the log of field samples in a CSV, and a skill that prepares the report for each field trip.
• A hobby: your vegetable garden, your recipes or your trips, with what worked and what did not.

Use it every day

The habits that make the agent better the more you use it.

• One conversation per task. When you finish something, start a new one. The memory is in the files, not in the chat, so you lose nothing, and the context stays clean.
• Correct the file, not the chat. If it does something wrong, ask it to add a rule to the AGENTS.md or to improve the skill.
• Ask it what to save. At the end of a session: "Is there anything from today that you should save in data?".
• Look at its files from time to time. They are your agent. The better they are, the better it works.
• Grow little by little. When you repeat a task three times, turn it into a skill.

Limits and warnings

What this agent does not do, and what you should know before you trust it with things.

• What is in the folder goes to the model. To answer, the app sends parts of your files to the company that runs the model. Do not keep passwords there, or data about other people who have not given you permission.
• If it is for work, ask first. Check if your company has rules about AI and a company account (for example Claude Team or ChatGPT Business). Do not save data about colleagues with their names: use codes, as the teacher example does.
• It makes mistakes. Check the important things: a health figure, a building measurement, a student's grade.
• The apps have usage limits. With a free or cheap plan, you can reach the limit on a day of heavy use. Wait a few hours or change apps: the folder works in all of them. If you move to Claude, or away from Claude, ask the agent to copy the skills to the folder that the new app uses.
• Make copies. If the folder is in Google Drive, OneDrive or Dropbox, you have a copy and you can open it on another computer. That also uploads your data to that service, and on a Mac the Desktop can be synced with iCloud without you knowing. If you know how to use Git, even better: it saves every change.
• On two computers, one at a time. The folder travels, but the conversations and the app settings stay on each computer. Add the folder in the app on each one, work on only one at a time, and wait until it finishes syncing. If a "conflicted" file appears, ask the agent to merge the two.

And from your phone? Your agent lives on your computer, so your phone does not see it. There are workarounds: if you leave the computer on with the app open, Claude and Antigravity (with their "Remote Control") and ChatGPT (with Codex in the phone app, on iPhone or Android) let you continue the conversation from your phone. Goose does not. And if the folder is in Google Drive, you can open it on another computer. But the natural place for this agent is the computer.

Download the examples

If you want to see how the folder looks at the end, or start from a ready-made one, download your example. Each one is a .zip file. On a Mac, double-click it to unzip it; on Windows, right-click it and choose "Extract All"; inside there will be another folder with the same name: use that one, the one with the AGENTS.md. Move the folder wherever you want and open it with your app (step 3). Each one comes with a little sample data, one skill, one script and one result; delete the sample data and add your own. On a Mac you will not see the folders that start with a dot (the skills) until you press Cmd + Shift + ..

• Studentmy-study-tutor
• Teachermy-class-helper
• Healthmy-coach
• Journalmy-journal
• Renovationbathroom-renovation

The examples have the skills in both folders, .agents/skills/ and .claude/skills/, so that they work in any app. In your folder you only need the one for your app.

Glossary

The key words of the guide, in one sentence each. In the text, move the mouse over a word in bold, or tap it on your phone, to see its definition.

Model (LLM)

The brain: a program trained on a huge amount of text that understands and writes. For example Claude, GPT or Gemini. LLM stands for "large language model".

App or harness

The desktop program that connects the model to your computer: it gives the model tools and passes it your instructions. For example Claude, ChatGPT in Codex mode, Antigravity or Goose.

Agent

A model that, thanks to the app, can act on its own over several steps: read, decide, write and check.

Folder

A container on your computer that holds files. The agent's folder is its home: it only sees what is inside.

File

A document with a name. Its ending (.md, .csv, .json) tells you what kind of content it holds.

AGENTS.md

A text file with the agent's instructions, at the root of its folder. It is an open standard that almost every app reads.

Context

Everything the model reads before it answers: the app's rules, the AGENTS.md, the name and description of each skill, the conversation and your message. The model does not know anything that is not in the context. The longer it is, the harder it is to keep every detail in mind.

Compact

What the app does when a conversation no longer fits in the context: it summarises the old messages, or stops reading them, to make room. Details get lost on the way.

Skill

A recipe for a task that you repeat: a folder with a SKILL.md file (name, description and steps). The agent only reads the description until it needs the skill.

Script

A small program that does one exact task, the same way every time, such as adding up a column in a table.

API key

A long password that gives access to a model from any app. You pay for what you use, instead of a monthly fee. OpenRouter gives one key for hundreds of models.

Subscription

A monthly fee, such as ChatGPT Plus or Claude Pro, with a usage limit. It almost always works only in that company's apps; Goose can sign in with ChatGPT Plus or Pro.

Git

A program that saves the history of every change in a folder, so that you can go back. The history also keeps the data, so treat it with the same care.

Tool

An action that the app lets the model do: read a file, write it, search or run a script.

If you are an AI helping someone with this guide