For about two years my kitchen ran on three systems. The spice rack that came with the flat, screwed to the wall above the hob. The drawer I organised myself once the rack filled up. And a shelf in the pantry for whatever fit in neither.
All three had paprika in them. I know, because I bought it three times.
That isn’t a disaster; you live with it. What broke me was a Saturday when a friend cooked at my place and I spent the whole evening standing behind him — no, the good pan is under the sink, that salt is coarse, halve it, the oven runs hot. He is a better cook than I am. He just couldn’t work in my kitchen without me standing in it.
Two weeks ago I realised our repositories were in exactly that state.
Three racks, one kitchen
OwlMeans Common is the library every project we build sits on, and every one of those projects is built by a coding agent. So a repo here doesn’t only hold code — it holds the instructions the agent reads first: how we lay things out, what never to do, which script does what.
We supported two agents, Claude Code and GitHub Copilot, and each wanted its own shelf. So every rule got written twice — once as .claude/skills/<name>/SKILL.md, once as .github/instructions/<name>.instructions.md. Two always-on context files that were near-copies. Two maps of the repo. The same shell script sitting byte-identical in two directories. Two memory folders, quietly drifting apart.
The tax is right there in the history: one commit from that period touches twelve skill files and their eleven mirrored twins. Nobody decided this was a good idea. It accreted, the way a third spice rack accretes.
One shelf, one card
So I tore it out. Everything moved into one folder — .agents/, holding skills, rules, scripts and memory — and everything an agent must read before starting moved into a single file at the root: AGENTS.md. In OwlMeans Common that deleted two hundred and thirteen duplicate instruction files. CLAUDE.md, eighty-six lines of everything before, is now six hundred bytes.
I didn’t invent the shelf. I took the one everyone else had already settled on — and how they settled on it is why I trust it.
In May 2025 Amp proposed a single file called AGENT.md, singular. Then OpenAI picked the plural for Codex — the plural being the point, since many agents share one file. Amp could have fought for their name. Instead they wrote: “instead of insisting on what we came up with, we decided that we’d prefer one standard,” on condition that OpenAI secure the agents.md domain. OpenAI did, and Amp switched.
It went from twenty thousand repositories in August 2025 to more than sixty thousand today, and in December it was donated to the Agentic AI Foundation under the Linux Foundation. Twenty-three tools read it natively now — Codex, Cursor, Copilot, Gemini CLI, Zed, Windsurf, Devin, Jules, Aider.
The other half of the shelf came from the opposite direction. Agent Skills — the SKILL.md format — was Anthropic’s, opened as a public spec in December 2025 and stewarded by that same foundation. It defines exactly what a skill folder looks like and says nothing at all about where the folder goes. So each vendor picked a parent. Codex scans .agents/skills. Copilot accepts .agents/skills. That made the choice for me.
The guest who brings his own knives
One agent doesn’t read the card on the door.
Claude Code reads CLAUDE.md, and only CLAUDE.md. The request to read AGENTS.md as well has been open since March — issue #34235 in the Claude Code repository, behind a cluster with thousands of upvotes — and it is open still. Which is a little funny, given that Anthropic wrote the skills format sitting in the other half of the folder.
The tempting fix is a second copy. Everyone who tries it reports the same ending: two files edited by hand always drift, and a drifted instruction file is worse than no file, because the agent believes it.
So we bridged instead. CLAUDE.md survives at six hundred and ten bytes, byte-identical in every repo, and its first line is @AGENTS.md. The rest is a note saying skills live in .agents/skills/ and must never be written anywhere else. A small shell script then generates one symlink per skill into a gitignored .claude/skills/, and a session hook regenerates them each time. Per skill, not per directory — Claude Code accepts a symlinked skill entry but not a symlinked skills folder, the kind of thing you only learn by trying it.
Recipes in my own hand
The second change matters more than the folder.
A cookbook says bake twenty-five minutes at a hundred and eighty. The card inside my cupboard says twenty-two minutes, back left, this oven runs hot. Both are correct; only one is about my kitchen.
OwlMeans projects don’t install generic skills — each grows its own. Our platform repository carries nineteen, the agent repository beside it twenty-three, and where the names overlap the contents don’t: execution means the abstraction in one and the platform-side use of it in the other. That isn’t duplication. Those are two different kitchens.
The trouble with a card taped to a door is that ovens change. So the harness now closes the loop. Approving a plan is also approving the pass that follows it: when the work lands, the agent walks back through the skills that work touched, rewrites the ones no longer true, and the completion report has to carry a table of what it updated, what it created, and what needed nothing — with a reason. A report without that table counts as unfinished.
One more rule, which I like more than I expected to: a skill states current rules, never what changed. No dated bulletins, no formerly X, now Y. The test is that a finished skill should read as though the feature was always that way.
Shelves by dish, not by shopping date
The third change is the one I’d give up last.
Agents keep memory now, and left alone they keep it as a diary. Ours did — files named after things that had happened, like slot-status-reconciler.md or null-error-investigation.md, each opening with what we were doing that week. That’s a shopping log. It records perfectly when you bought something and says nothing about what tonight’s dish needs.
So we regrouped the shelves by dish. A memory node is now named after a real part of the project — a subsystem, a concern like routing or translations, an external service, or the workspace itself — and never after an event, a date or a task. Its body splits into what is true, what must hold, what bites you, and where to look, and dates are allowed in exactly one section, for work still in flight.
The index does the actual work. Fifty lines at most, one per node, each carrying the paths that node covers. An agent reads it at the start of a session and nothing else; when a task arrives it matches the task’s paths against those lines and opens the one or two that match. It never reads the whole store.
And writes are merges. When something changes you rewrite the line in place — never append a dated correction underneath, or the file quietly becomes a diary again. Our platform repo went from twenty chronological files to eleven structural nodes, and finding anything stopped being an excavation.
You can just have it
Step back and none of this is exotic. One folder instead of three. A card on the door saying how the place works. Recipes in your own hand, kept current. Shelves grouped by what you actually cook.
It still cost two weeks, and most of that went on things you can’t look up — that the standard exists and which one won, that a symlinked skills directory fails where per-skill symlinks work, that memory keyed to events rots while memory keyed to structure doesn’t.
So here’s the honest pitch.
If you’re building anything real with a coding agent, you will hit this. You’ll add a second agent and start writing everything twice. You’ll grow a memory folder that reads like a diary nobody wants to open. You can do what I did and burn the two weeks. That was worth it for me — it’s my job.
It is not your job.
This is what OwlMeans ships. Every project the Platform builds comes out with the harness already in it — .agents/, AGENTS.md, skills tailored to that project, a memory graph shaped like its own code — and OwlMeans Services fits the same thing to a codebase you already have. You own all of it. No lock-in, and no house agent: Codex, Copilot, Claude Code, whatever ships next quarter — they all read the same shelf.
Any cook, any kitchen. Skip my two weeks — you can just have it.
OwlMeans builds full-stack TypeScript SaaS from your user stories — typed, SSO-ready, and yours to keep building with any agent. See what it can do →