AGENTS.md, Cursor rules, and Claude skills are all solving the same problem — badly

I keep a folder of other people's config files. It started as research and turned into something closer to a hobby. .cursorrules, AGENTS.md, CLAUDE.md, .github/copilot-instructions.md, a growing pile of SKILL.md folders. At last count the biggest public collection of Cursor rules has north of forty thousand stars, which tells you this is not a niche concern.

Read enough of them and a pattern shows up that nobody advertises. Almost every one of these files is a person trying to explain their project to something that will forget the explanation.

That is the actual problem. The three formats are three different guesses at how to solve it.

The three formats, briefly

AGENTS.md is the boring one, and boring is the point. Plain markdown at your repo root. No frontmatter, no metadata, no activation modes. You describe how the project works — build commands, conventions, the things a new hire would ask in week one — and most agents will read it. Claude Code, Codex, Gemini CLI, Cursor, and others all pick it up. Its virtue is that it is a convention rather than a product, so it costs nothing to adopt and nothing to abandon.

Cursor rules live in .cursor/rules/ and buy you scoping. Each rule carries frontmatter with file globs, so a rule about your API layer only activates when you are in the API layer. This is genuinely useful in a large repo where a single instructions file would either be too vague to help or too long to fit. The catch is portability: they are Cursor's format, and they do not travel to Claude Code, Codex, or Copilot.

Claude skills are a different shape entirely. A skill is a folder with a SKILL.md plus whatever scripts, templates, and reference files it needs, and the agent loads it when the task calls for it. The distinction I find most useful: skills are verbs, rules are adjectives. A rule says this project uses Tailwind and prefers server components. A skill says here is the procedure for cutting a release.

What to use when

If you use exactly one agent and you have a large codebase with genuinely different conventions per directory, Cursor rules earn their keep. The scoping is real.

If more than one agent touches your repo — or you think one might, or a teammate uses something else — write AGENTS.md. Portability beats features here. A file every tool reads at 80% fidelity is worth more than a file one tool reads perfectly.

If you have a multi-step procedure that you keep re-explaining, that is a skill. Deploy steps, a review checklist, a migration you run quarterly. Anything where the answer is a sequence rather than a preference.

Most repos want AGENTS.md plus two or three skills. The scoped-rules-per-directory approach tends to be an answer to a problem you should fix in the codebase instead.

Where all three break

Here is the thing that took me too long to notice.

Every one of these formats is a write-ahead log for context. You anticipate what the agent will need, you write it down in advance, and you hope you guessed right. When you guessed right, it works beautifully. When you did not, the agent confidently does the wrong thing, and you go add another line to the file.

That failure mode has three parts.

Drift. The file describes the project as it was on the day you wrote it. Code changes daily. Nobody has a habit of updating AGENTS.md in the same commit that changes the convention it documents. Within a few weeks you have a file that is 80% true, and the 20% is invisible — you cannot tell which parts have gone stale by looking. A stale instruction is worse than a missing one, because a missing one produces a question and a stale one produces confident garbage.

Fragmentation. Once you have three agents you have three files, and they disagree. AGENTS.md was meant to fix this and largely does, but only for the ambient layer. Skills and rules still fragment. I have watched a team maintain both CLAUDE.md and .cursor/rules/ where the two contradicted each other on error handling, and neither author knew.

The part nobody writes down. This is the big one. The reason you chose Supabase over Firebase. The bug that made you add a seemingly pointless await. The customer conversation that killed a feature. The three approaches you tried before the fourth one worked.

None of that is in the repo. It is in Slack, a PR comment thread, a design doc, or somebody's head. And it is exactly what a competent collaborator needs. A new engineer gets it through osmosis — standups, code review, asking someone who was there. An agent gets nothing, because the only channel you have given it is a markdown file that documents conclusions and throws away reasoning.

You can watch this happen. Ask an agent to change something load-bearing and it will cheerfully undo a fix, because the code looks redundant and the reason it exists was never written down anywhere it could read.

The framing that helped me

The instructions file is not documentation. It is a cache. It is a small, hand-maintained, hand-invalidated cache in front of a much larger body of knowledge that lives in your repo history, your issue tracker, your notes, and your conversations.

Once you see it that way, the ergonomics make sense. Caches go stale. Caches need invalidation, and manual invalidation is the kind humans are worst at. And a cache is only as good as its hit rate — which here means: only as good as your ability to predict, in advance, what will be asked.

That prediction problem is not solvable by writing a better file. You cannot pre-write the answer to a question you have not been asked.

So what actually helps

I do not think the answer is a fourth format. Some things that measurably helped:

Write down decisions, not just rules. A one-paragraph note per non-obvious decision, dated, with the reasoning and the alternatives you rejected. Not "we use pgvector" — "we use pgvector over a separate vector DB because we were already running Postgres and the operational cost of a second datastore was not worth the recall improvement at our scale." The second one survives being questioned. The first one just gets overruled.

Put the reasoning where it can be retrieved, not just where it can be read. A decision log that is one 4000-line markdown file is a decision log nobody reads. The value is in getting the relevant three paragraphs at the moment they matter. That is a retrieval problem, not a writing problem — and it is the reason semantic search over your own notes is more useful than it sounds.

Keep AGENTS.md short and true over long and comprehensive. Fifteen lines you actually maintain beat two hundred that rot. Every line is a maintenance liability. If you would not update it during a refactor, cut it.

Let stale things die visibly. Date your notes. A dated note that says something from eight months ago reads as history. An undated one reads as current fact.

The uncomfortable version

The reason these formats feel unsatisfying is that they ask you to solve a retrieval problem with a writing problem. Write more, write better, write in advance. But the failure was never that you wrote too little. It was that the thing you needed was written somewhere — in a PR, a note, a message — and nothing could find it and hand it over at the right moment.

Which is, when you look at it directly, the same problem you have. You wrote it down. You cannot find it either.

That is the part I find genuinely interesting: the reason your coding agent keeps forgetting your project is a slightly sharper version of the reason you keep re-deriving decisions you already made. Fixing it for the agent and fixing it for yourself turn out to be the same piece of work.