I bought paprika three times because I kept it in three places.
The flat came with a spice rack above the hob. When that filled up, I organised a drawer. Then I added a pantry shelf. Each arrangement made sense while I was making it. Together they made finding paprika surprisingly difficult.
A friend cooking at my place exposed the problem. I spent the evening behind him: the good pan is under the sink, that salt is coarse, the oven runs hot. He cooks better than I do. He just needed directions through my kitchen.
In August I realised I had done the same thing to our repositories.
The duplicate rules
OwlMeans projects carry more than source code. They carry instructions for the coding agent: where things live, which commands to run, and what must survive an edit.
We supported Claude Code and GitHub Copilot. A rule for one became a skill under .claude/skills/; the other got a copy under .github/instructions/. Project maps, shell scripts and memory accumulated their own twins.
One commit touched twelve skill files and eleven mirrored versions. Every correction came with a small question: had I corrected the other copy?
In OwlMeans Common, the cleanup removed 213 duplicate instruction files. That count describes our repository change. It says nothing about how much faster an agent became.
The replacement was one canonical .agents/ folder and a root AGENTS.md. Skills, rules, scripts and shared memory each had a place. Agent-specific files became bridges into that source.
The shared format
AGENTS.md gives an agent project instructions in an ordinary Markdown file. The Agent Skills specification defines the structure of a skill folder and its SKILL.md.
These solve different problems. The root file tells the agent how to work in this repository. A skill holds a procedure it can load for a particular task.
The skills specification does not prescribe the parent directory. Choosing .agents/skills/ was our convention, selected for the tools we used. I should not present it as a directory every agent has promised to discover.
That distinction matters when you add another tool. Shared text only helps if the tool actually loads it.
The Claude bridge
Our August setup kept a small CLAUDE.md whose first instruction was @AGENTS.md. A script generated one symlink per skill into .claude/skills/.
That gave Claude Code its expected entry points without giving us another set of instructions to maintain. The session hook refreshed the links.
We arrived at the per-skill links by testing the setup. Linking the whole skills directory had failed in our configuration. That is an observation about that setup, rather than a permanent rule about every future Claude Code release.
I checked the native AGENTS.md support request again on 15 October 2026. It was still open. For an installation today, check the current Claude Code memory documentation and test what it reads. Our bridge remains explicit about the source it imports.
Instructions worth keeping
Moving files fixed duplication. It did not make their contents useful.
A generic skill about writing good code tells an agent little about our entrypoints or our project slots. The useful instructions explain this codebase: which package owns a resource, which boundary a change must respect, and which check catches the mistake.
OwlMeans Common packages carry guidance alongside their code. A generated project can install that guidance through @owlmeans/agent-skills. The package metadata supplies the instructions; the repository supplies the local context.
Someone still has to maintain both.
Our rule is to revisit the relevant skills after substantial planned work. If a command, path or behavior changed, rewrite the instruction that describes it. A skill states the current rule. A dated note saying the old rule stopped working leaves the next agent to decide which paragraph wins.
This has a cost. Some tasks finish with documentation work after the code already passes. I would rather pay it while I still remember why the implementation changed.
Memory by subsystem
Memory had a different kind of duplication. We were keeping an account of tasks.
A file named after an investigation told me what happened that week. To find what was currently true about routing, I had to read several investigations and work out which one superseded the others.
We regrouped the store around the project: routing, translations, deployment, external services. An index maps those nodes to the paths they cover. The agent reads that map first, then opens the relevant nodes.
A write updates the matching fact in place. It does not append another dated account beneath an obsolete one. Work still in flight can carry a date, but settled guidance should not require reconstructing the session.
In the platform repository, twenty chronological files became eleven structural nodes. Those were our counts during the reorganisation. The useful result was that I knew where to look.
A memory store still needs correction. Its shape cannot prevent a false assumption from being recorded, and a short index cannot guarantee the agent loads the right page. It gives us somewhere to repair the assumption when we find it.
The two weeks
The reorganisation took two weeks. I spent part of that time on directory conventions and part on the small compatibility problems that appear only when you run another agent.
Generated OwlMeans projects carry agent guidance. Our Services work also includes tailoring skills and metadata to the delivered project. Keeping that guidance useful remains work for whoever maintains the repository.
My friend still needs to know that the oven runs hot. At least I now have one place to write it.
Originally published 13 August 2026. Revised 15 October 2026 to distinguish the shared formats from our directory convention and to date the tool compatibility observations.