Coding agents are great at creating files. Keeping those files organized takes a bit more work, especially once you’re using a few different tools on the same machine. Each has its own directories, instructions and way of finding things. Before long, you’ve got several copies of a skill and you’re not sure which one the agent is actually using. Sound familiar?

I’ve been helping people work through this in coaching sessions, while making a fair amount of the same mess myself. Last night, for example, I had my agent research some card games and save the rules. (I know, I know, I’m really pushing the limits of AI here. But I love games, so sue me.) It put the notes into a workspace folder instead of my Obsidian vault, the collection of notes I use for personal reference. The vault already had a gaming folder, and the agent had instructions to consult its filing guide. We still had to move the notes.

Better instructions help, but there’s more to this than telling your agent to keep things tidy. You need to decide where things belong, make that easy to look up, and check what your tools are actually loading. Here’s how I’ve been approaching it.

Give each thing a home

The first thing I’d sort out is where the work goes. This sounds obvious until you’ve got a project folder, a notes app and an agent workspace that could all reasonably hold the same document.

I keep code and project specs with the project. Personal reference material goes into my Obsidian vault. For the work my assistant does, I use the following workspace directories.

knowledge/    Context about the work that should survive the conversation
drafts/       Work in progress for me to review
uploads/      Files I've sent to the assistant

The agent can write into the first two. The uploads directory is managed by the application, so I tell it to leave that one alone. Each workspace also has an instructions file explaining what the workspace is for and pointing to anything it needs to read before getting started.

The distinction between workspace knowledge and personal notes is where my card-game example went wrong. Both places can hold useful information, but I want to find game rules with the rest of my gaming notes, regardless of which conversation produced them. Having a folder called knowledge/ doesn’t explain that on its own.

You don’t need to use my directory names. You do need to describe what belongs in each place, including what should go somewhere else. Otherwise you’re leaving the agent to make a decision you probably haven’t made very clearly yourself.

Keep project skills with the project

A skill is a set of instructions an agent can load for a particular job. I have skills for things like writing, working with email and managing my tools. Some are useful across most of my work. Others only make sense inside one project.

Back in April, I worked with a client whose newsletter output had become inconsistent. The issue we found was in how the work was organized. Claude was picking up broad skills from the top-level setup instead of using the intended project-specific setup. We reorganized the newsletter into its own directory and tightened the instructions above it.

This is why I try to keep the global setup small. A personal writing preference might belong there. A newsletter’s section order, research process and output files belong with the newsletter. Putting everything at the top level makes it harder to see what applies to the job you’re doing.

It also helps to start the agent in the right project and inspect the context it’s using. For example, Claude loads instruction files from the directories above your working directory, as well as the project itself. Moving into a project doesn’t make the instructions above it disappear. If they disagree, you still need to fix them.

Sharing between tools

Once you’ve organized one agent, you might want to use another. This is where keeping things consistent becomes a pain in the ass.

There’s an open convention called AGENTS.md for project instructions. The idea is straightforward, you give coding agents a predictable file to read so you don’t have to explain the project every time. However, Claude Code still reads CLAUDE.md. Its documentation describes importing AGENTS.md from that file, or using a symbolic link.

A symbolic link, usually called a symlink, makes one filesystem path point to another. I still use one for my instructions, so CLAUDE.md points to AGENTS.md and I only have one file to maintain.

I used to use symlinks for skills and custom agents too. That became harder to manage as the setup grew. Different tools expect different locations, and custom agents can have different file formats as well. Sharing a directory doesn’t handle those differences for you.

To help with this, I built Overlord. It keeps my shared definitions under .agents and manages the files Claude and Codex need. Codex reads the skills there directly; Overlord maintains physical copies for Claude and generates each tool’s custom-agent files. If I edit a provider’s copy, it can bring that change back to the source.

For my setup, that’s easier than maintaining the copies myself. It also keeps the syncing work in ordinary code, where I can check the result, instead of asking an agent to remember to update several files whenever something changes.

The Agent Skills format gives us a common structure for the skills themselves. Each one is a directory containing a SKILL.md file, with optional scripts and reference material. That’s useful progress. There are still differences in where tools discover those skills and how the rest of their configuration works, so I wouldn’t assume that sharing the format means the whole setup is portable.

Check what’s actually loading

Of course, keeping files in sync doesn’t tell you whether you needed them in the first place. I ran into that on my own machine this week.

A batch of 103 skills for Amazon Web Services (AWS) had ended up in my shared skills directory. Overlord propagated them into the provider files it manages. Separately, an AWS plugin in Claude added another set of skills and a server connection that was failing. Codex eventually warned that its skill list was being truncated.

Those were two different sources of clutter, so cleaning up the shared folder alone wouldn’t have dealt with both. We removed the unwanted skills and the plugin, and checked fresh sessions to confirm they were gone. The truncation warning disappeared too.

This matters even if you never ask the agent to use those skills. The skills specification describes loading their names and descriptions at startup, with the full instructions loaded when needed. That saves loading every complete file, but a long list still takes space in the conversation. It also gives the agent more options to sort through.

I’d check this before adding another page of instructions about which skill to use. Look at the skills the session can see, the plugins you’ve installed and any startup errors. There’s a good chance the setup has changed since you last looked at it, particularly if you’ve been letting agents install things for you.

Where to start

If your setup has become difficult to follow, I’d start with one project you use regularly. You can organize that without redesigning your entire machine.

• Decide where its code, working documents and reference material belong, then put those locations in the project instructions.
• Keep the project’s own skills alongside it. Leave only broadly useful skills and preferences in the global setup.
• Choose one source for anything shared between tools and decide how the other copies get updated.
• Open a fresh session and check what’s being loaded. Remove unused additions after checking for anything you need to keep.

Instructions are still guidance, so I wouldn’t expect a perfect filing system to make every agent behave perfectly. My card-game notes had somewhere to go and still landed in the wrong place. But having a clear layout gives you something to check against, and makes it much easier to work out whether the problem is the instructions, the files being loaded, or the agent ignoring both.

I’d get that working for one project before carrying the same arrangement into the others. You’ll probably change a few things once you’ve used it for a while. That’s a lot easier when there’s only one setup to fix.