Build the Expertise Into Each Folder

Open a new session with a coding agent and it begins from nothing. That is not a flaw, it is just how a fresh context works: no memory of yesterday, no idea which corner of which project you are in, no sense of the conventions you have already settled. So you re-explain. You paste the same background, restate the same rules, correct the same small mistakes you corrected last week. For a while I treated that re-explaining as the price of working this way. Then it occurred to me that the price was avoidable, and that the place to avoid it was the filesystem.

I have written before about what an agent actually changes for a solo builder: mostly, it lowers the cost of acting on understanding you already have. The build methodology has its own page; this is the day-to-day around it, the running and more specific version, and it lives in the practice thread. The single idea is this: a folder is not just where files sit. A folder is a context. If you treat each working directory as a small, self-contained workspace, with its own memory, its own skills, and its own conventions, then any agent you start inside it is briefed by the folder rather than by you.

The reason this works is that a folder is already a category. You do not throw every kind of work into one directory. You separate the site from the research notes from the scripts because they are different kinds of work with different rules. Once you accept that a directory is a category of work, the next step is small but it changes everything: give the category its own brain. Each folder accumulates the memory, the procedures, and the standards for one kind of work, and the agent that opens it inherits a specialist, not a generalist starting cold.

What a folder carries

Here is what “briefed by the folder” means in practice, concretely.

Memory, as one fact per file. Each folder carries a small set of memory notes: short, standalone facts about the work done there, each in its own file, each with a one-line description of what it covers. There is an index that lists them. When an agent starts in the folder, it reads the index and pulls in the specific notes whose descriptions look relevant to the task in front of it. The exact format matters less than the discipline: one fact, one file, recall by description. A memory that tries to hold everything gets ignored. A memory that holds one clear thing gets used.

Documentation that says what the work is. At the top of each folder sits a short conventions file, the thing an agent reads first. It is not vague mission text. It says what this directory is for, what categories of task belong here, how the code or content is organized, and the rules that are not negotiable in this folder. It is the orientation a new teammate would get on their first day, except the teammate is a fresh agent and the first day is every session. An agent that reads it knows where it is and what is expected before it touches a single file.

Skills, as the procedures that repeat. A skill is a written procedure the agent follows: the steps for a recurring job, the order to do them in, the checks at the end. The ones that earn their place are the jobs I would otherwise re-describe every single time. Turning a rough draft into this site’s diagram format. Generating a batch of files the same way each time. Building and checking a release before it ships. The skill is not magic. It is the thing I would have said out loud, written down once so I never have to say it again.

Git, and a session you can resume. Two things keep the folder from forgetting between sittings. The first is version control: the work is in git, but so, increasingly, is the configuration around it, the memory and the conventions, which means the folder’s expertise has a history you can read and roll back like any other code. The second is the session itself. When I open the editor back up in a folder, the agent does not just see the files. It can pick up the thread of the last conversation we had there: what we were doing, what we decided, what was left unfinished. A cold start in a folder is rarely cold. It resumes.

The write-back loop. This is the part that makes the whole thing compound. When the agent gets something wrong, the fix is not only the edit in front of me. The correction goes back into the folder: a new memory note, a tightened rule in a skill, a guard in the code so the mistake cannot recur. The principle I hold to is that a correction should only happen once. Done consistently, the folder gets a little smarter every time I work in it, and the next agent inherits all of it.

Scoped, but not bound

It would be easy to hear all of this as “lock each agent in its folder,” and that is the opposite of what happens. The folder is a base of operations, not a cage. Skills in particular live at a level above any one directory: they are globally available, and globally buildable, so a procedure I wrote while working in one folder is there for me in all of them. An agent based in the site folder can still reach into the research folder when a task crosses over. What the folder gives is a center of gravity, a place where one kind of work is most at home and most practiced, without walling that work off from everything else. You get local expertise and global reach at the same time, which is exactly the combination a single global config never manages.

That is the decision underneath all of this: scope context to the filesystem instead of to one global configuration. I could put everything in a single place that every session loads. I tried versions of that, and it does not hold up. A global config grows into a pile that is mostly irrelevant to whatever I am doing right now, and irrelevant context is not neutral. It is noise, and noise makes the agent worse. Scoping by folder keeps each context small and local. The rules for the site do not leak into the research notes; one project’s conventions do not bleed into a throwaway script. And because the context travels with the directory, a fresh agent that opens the folder is competent there right away, not after a paragraph of setup, but on the first message.

You are the orchestrator

Once each folder is a competent base, you are no longer limited to one agent at a time. This is where working in the editor, on the files, pulls ahead of the chat-app version of the same tools. You can run several agents in succession, handing each a piece. You can run more than one in the same folder at once, on different items. You can run them across folders at the same time. You can even point two at the same problem, let them try it different ways, and keep the better result.

But it is worth being exact about what makes that work, because it is easy to picture it wrongly. These agents are not off running themselves while I watch a dashboard. I steer every one of them, on every task, and correct them as they go. They are extensions of me, which means the cohesion does not come from some clever arrangement that makes them cooperate on their own. It comes from me. Whether they run one at a time or several at once, at what pace, on what, and in what order, is a function of how much direction I can give and how much work I have to hand them. I am the orchestrator, and that is not a role I can pass off, because the thing being distributed is my intent, and I am the only one who has it.

So where does the work log fit? Not as the thing that coordinates them. The agents do not report to it the way employees file status to a manager who then runs the floor. The log is a record. Every finished piece of work leaves one line in it: which folder, which machine, what kind of work, what changed, what is still open. I keep it because at the end of a stretch I can read one log and see the whole shape of what has been done, across every folder, which is what lets me plan the next stretch and decide what the business actually needs. It is also how the folders get better: the patterns I notice in the log become new skills, tighter conventions, a sharper sense of what belongs where. The log informs the system. It does not drive it.

There is a lot more to say about that log, about recording the work itself and staying honest about what actually shipped. That is its own piece, and I will write it. Here it is enough that the record exists, and that I am the one who reads it.

So the leverage is not in automating the work away. It is in lowering the cost of moving what I want into a form an agent can act on. I can build skills, shortcuts, and small programs that make that handoff faster and more reliable, and I do. But it never collapses into a task list I set running and walk away from. The bottleneck, and the skill actually worth getting good at, is me: how clearly and how efficiently I can direct a group of capable agents that are only ever as coordinated as I make them.

It travels

Here is the part that surprised me most. Because a folder’s context is just files, memory notes and a conventions file and the rest, it is portable. Put those folders on a shared drive, a Google Drive or anything like it, and the expertise stops living in one person’s head or on one person’s laptop.

Someone else on the team who wants to set up their own agents does not start from zero. They open the same folder and inherit its memory and its conventions, the accumulated understanding of how that kind of work gets done here. Maybe the heavier custom skills stay mine, at least at first. But the memory and the configuration, the part that is hardest to reconstruct and easiest to lose, is right there for them, and they carry on from where the folder is rather than from where a blank agent would be. A folder that began as my way of not re-explaining things to an agent turns out to be a way of not re-explaining things to a colleague either.

The editor and the app

None of this is an argument that the editor is the only place to use an agent. The desktop and web apps are genuinely good at something different: quick, uniform, research-and-documentation work, where you want a clean conversation, a consistent set of built-in tools, and a tidy artifact at the end. When I want to think something through or produce a one-off document, that is often the better room to be in.

But for day-to-day work where the work is files, where the output is code and content that has to live somewhere, get committed, and be picked up again tomorrow, the folder-and-editor approach is far more practical. The context is the directory, the history is in git, the results land in the registry, and tomorrow’s session resumes today’s. The two are not rivals so much as different tools for different shapes of work. The trick is knowing which shape you are holding.

What this asks of you

What this asks of you in return is discipline, and it is the unglamorous kind. The setup only learns if you actually feed it: write the correction back instead of just fixing the line, prune the memory that has gone stale, and notice when a skill has drifted away from how you really work now. Skip that and you get the worst of both worlds, a folder full of confident, outdated instructions that an agent will follow straight off a cliff. The structure does not maintain itself. It is closer to a garden than a machine.

And the more agents you run, the more a second discipline matters: coordination. It is genuinely possible to start more work than you can review, to let the registry fill with results you have not actually checked, to mistake motion for progress. Running many agents well is not the same as running many agents. The whole approach rewards the person who can hold the system in their head and direct it, and it quietly punishes the person who just turns everything loose.

If you want to try it

Do not build the whole thing at once. Start with one folder, the one you work in most. Give it a single memory file for the fact you are tired of repeating, and one skill for the job you are tired of explaining. Then let it grow the way mine did, from real corrections: every time you catch yourself saying the same thing twice, that is the signal to write it down where the folder can keep it. Only once one folder is clearly paying you back is it worth adding a second agent, a registry, a shared drive. The order matters. The expertise comes first; the orchestration is what you build on top of it once there is expertise worth orchestrating.

This is the quiet shift the practice is really about. The agent is not just a tool you reach for. The configuration around it, the folders and what they carry, the record you keep of them, the drive they live on, is itself something you build, with the same care you would give the software it helps you build. And like that software, the value is not in any one session. It is in what each session leaves behind for the next, and increasingly, for the next person.