The spelling “agents md” drew 1,900 searches a month in the United States in August last year. It peaked at 4,400 in February and March this year and sits at 2,900 now. The narrower question form, “what is an agents md file”, went from no measured searches in May last year to a peak of 140. It has 50 a month now, and almost no competition for them. I pulled those figures on 24 October 2026 through Ubersuggest.
Then I looked at who answers it. Page one is the specification site itself, a GitHub repository and the GitHub Copilot engineering blog. Below those sit the ChatGPT developer docs, Real Python, Hacker News, the OpenAI developer forum, two YouTube tutorials for Codex users and a Reddit thread from r/ClaudeCode. Above all of them, Google prints its own AI-written summary. Every single result assumes you have a code repository, a terminal and a pull request waiting.
That leaves a question unanswered for everybody else. More than sixty thousand open-source projects decided it was worth writing their AI a briefing document rather than explaining the same things in every new session. The reasoning behind that applies to a business with one person in it.
A German authority sent me a line this month that I have not stopped thinking about. The pdf with the report does not contain the questionnaire. Both documents were there. I had handed them in as two files instead of one, on a partly publicly funded job, and that counted as a missed requirement. The requirement had been written down. I had read it as an overview rather than as an instruction, which turns out to be the exact distinction the research below hangs on.
What is an AGENTS.md file?
An AGENTS.md file is a plain text document, written in Markdown, that sits in the top folder of a project. It tells any AI agent how to work on that project before the agent starts. Its category is a context file, sometimes called an agent instruction file. The mechanism is a naming convention rather than software. An agent looks for a file with that exact name and reads it first. The setup steps, the house rules, the test command and the parts not to touch then arrive on their own. Nobody retypes them into a new session. Every agent gets the same instructions every time, without a person in the loop.
The format’s own site describes it in one line. AGENTS.md is “a simple, open format for guiding coding agents, used by over 60k open-source projects”.
Two unrelated things share the search term, and it is worth separating them. “Agents md” also returns real estate and insurance agents in Maryland, where MD is the state abbreviation, and it returns the television series Agents of S.H.I.E.L.D. Neither has anything to do with this.
One more separation matters more, because it is why this article exists. AGENTS.md was built for coding agents working inside code repositories. I am not going to pretend otherwise or tell you to put one in your Dropbox. What transfers is the reasoning, and the research behind it is unusually good.
Who created AGENTS.md, and who controls it now?
OpenAI created it and then gave it away, releasing the format in August 2025. On 9 December that year it contributed the format to the Agentic AI Foundation, a new body under the Linux Foundation, alongside Anthropic’s Model Context Protocol and Block’s goose agent framework.
The Linux Foundation announcement of that day put a number on the spread. AGENTS.md “has already been adopted by more than 60,000 open source projects and agent frameworks”. The same announcement calls it “a simple, universal standard” and dates its release by OpenAI to August 2025.
OpenAI’s own stated reason for handing it over is the part worth reading twice. It lists two outcomes in particular. The first is that “Developers and enterprises have a portable way to provide agents with the context they need”. The second is that “No single company controls its direction as adoption continues to grow”.
A company that sells an AI model decided the file describing your work should not belong to the company that sells you the model. Claude Code, ChatGPT’s Codex, GitHub Copilot, Cursor and Gemini CLI all read it. So the file survives you changing your mind about which AI you use, and that portability is what makes it interesting for a business rather than for a codebase.
How is AGENTS.md different from a README or a CLAUDE.md?
They are written for different readers, and mixing them up is the most common mistake. The comparison below is the one people actually search for, since “agents.md vs claude.md” and “agents.md vs readme.md” both appear in the live autocomplete.
- A README addresses humans. It explains what a project is, who it is for and how to get started, in the order a curious person would want it. An AI can read it, and it was not shaped for one.
- AGENTS.md addresses the agent. It contains the operating instructions, the conventions, the commands and the boundaries. It is vendor-neutral by design, so several different AI tools read the same file.
- A CLAUDE.md does the same job for one tool. It is Claude Code’s own convention, and many projects now keep a short CLAUDE.md that points at AGENTS.md rather than maintaining two documents that drift apart.
- Custom instructions sit in your account settings rather than in the work. They apply to everything you do, which makes them useful for tone and useless for anything specific to one project, one client or one offer.
The pattern underneath all four is the same. Somebody decided which facts an AI needs before it starts, wrote them once, and stopped repeating them. An agent skill is the same move at the level of a single procedure rather than a whole project.
Does AGENTS.md actually make the AI work better?
Partly. It reliably makes the agent faster and cheaper, and it does not reliably make the work better. Two research groups found that this year, measuring it separately.
The speed result
The first study is On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents, by Jai Lal Lulla, Seyedmoein Mohsenimofidi, Matthias Galster, Jie M. Zhang, Sebastian Baltes and Christoph Treude, submitted to arXiv on 28 January 2026 and revised on 30 March. They ran agents across 10 repositories and 124 pull requests, with and without a context file. Their result is a “lower median runtime” and “reduced output token consumption”, by 28.64% and 16.58% respectively, while the agents kept “comparable task completion behavior”. Same work, less time, fewer tokens.
The quality result
The second study went looking for quality rather than speed, and found less to celebrate. Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents? is by Thibaud Gloaguen, Niels Mündler-Sasahara, Mark Niklas Müller, Veselin Raychev and Martin Vechev at ETH Zurich and LogicStar.ai. The authors submitted it to arXiv on 12 February 2026 and have since revised it twice, most recently on 29 September 2026. Their headline finding is that “providing context files does not generally improve task success rates”, and they report inference cost rising by more than 20% on average.
What they found inside that result separates the half that works from the half that does not. The paper reports that “instructions in the context files are well followed by coding agents”, while repository overviews, which model providers themselves recommend, do not help. Their conclusion is that context files earn their place for specifying non-standard practices, and that performance claims about them should be evaluated rather than assumed.
So the evidence says something narrower than the marketing does, and something more useful. Telling an AI how you do a specific thing works. Describing yourself to it in general terms does not.
What does this mean if you run a business instead of a codebase?
The most common way solo business owners use AI is the version the research just marked as the weak one.
Watch the pattern. You open a new chat and write a paragraph about your business, who you serve and what you stand for, hoping the AI will absorb it and produce something that sounds like you. That paragraph is an overview. It is exactly the shape the ETH Zurich study found did not help, and you pay for it in attention and in tokens every time you paste it in.
The half that does work is duller and more specific. It is the instruction. Your captions always open with the reader’s situation rather than your own. Your prices are these, and you never discount them. You spell it “solopreneur” and never “solo-preneur”. You write in English for Instagram and German for LinkedIn. You never use the word “elevate”. Those are rules an AI can follow, and the research says it does follow them.
What the business version is called
The developer version of that idea is a file in a repository. The business version has its own name, and it is a knowledge base for AI. This is a knowledge base for the AI you work with every day, not a help-center knowledge base for customer support. It is a small set of plain files containing your offers, your audience, your prices, your decisions and your voice rules, which Claude or ChatGPT reads before it writes anything. The parallel with AGENTS.md is exact in the part that matters. You write the operating instructions once, in a place the AI reads automatically, and you stop being the only copy.
The habit I run now, after the questionnaire, is three lines long. Paste the requirement. Paste the deliverable. Ask what is missing and in which format. It is an instruction rather than an overview, which is why it works.
Three more habits follow from the research, and none of them require a tool.
- Write rules rather than descriptions, since instructions get followed and overviews do not.
- Keep it to the instructions that are actually needed, because the ETH Zurich study found that context files raised inference cost by over 20% on average without improving results.
- Put it somewhere the AI reads on its own instead of pasting it into each new chat.
Where does this stop working?
It stops working in four places, and they are worth stating plainly, because a page that only lists benefits is not worth quoting.
Both studies measured coding agents doing coding tasks. Neither one tested a solopreneur writing captions, and I am not going to claim their percentages transfer to your Instagram drafts. What transfers is the finding about instructions beating overviews, which is a statement about how models use written context rather than about software.
There is no AGENTS.md convention outside code. If you work in Claude Projects, in ChatGPT’s project folders or in a shared drive, you are uploading files to a workspace rather than dropping a magic filename into a folder. The habit is the transferable part.
A written file does not make the output correct. It removes the repetition and raises the floor on the first draft. Your judgment still has to sit on anything that goes out with your name on it.
Files go stale, and a confident stale file is worse than no file. A document with last year’s prices will produce last year’s pricing page faster than you could have got it wrong yourself. That is the same failure mode as context rot arriving from the other direction, with a file rather than a long chat as the source.
Where do you start?
Start by finding out what your AI already knows about your business when a conversation begins, because that number decides how much you are retyping.
I built a free Business Brain AI Audit for exactly this. You give it your email, the audit arrives as one HTML file, and you attach it inside the AI workspace where your business knowledge already lives. Then you paste one line of instruction and send it. Your AI fills in the report and hands it back scored, across the six areas it checks, with the three gaps that matter most named at the end. It costs nothing.
One limit is worth knowing before you run it. It reads only what your AI can find inside that one workspace during that one run, so it cannot see your other chats, your account memory or your connected tools.
If the audit tells you your AI starts every conversation from nothing, that is what Business Brain builds. It is a seven-day course that gives you a knowledge base for AI, meaning the set of plain files Claude and ChatGPT read before they write anything for you. Four modules called THINK, EXTRACT, BUILD and RUN, about an hour a day, €67 one time, in English, no code and no subscription. More than 700 solopreneurs have completed the Foundation Kit, a separate and smaller product of mine.
AGENTS.md, in short
- An AGENTS.md file is a plain Markdown document in a project’s top folder that tells an AI coding agent how to work on that project before it begins.
- The format describes itself as “a simple, open format for guiding coding agents, used by over 60k open-source projects”.
- It was created by OpenAI and released in August 2025.
- OpenAI contributed the format to the Agentic AI Foundation under the Linux Foundation on 9 December 2025, alongside Anthropic’s Model Context Protocol and Block’s goose framework.
- The Linux Foundation announcement of that date reported adoption by more than 60,000 open source projects and agent frameworks.
- It is vendor-neutral, and Claude Code, ChatGPT’s Codex, GitHub Copilot, Cursor and Gemini CLI all read it.
- A README addresses humans, AGENTS.md addresses the agent, and a CLAUDE.md does the same job for one tool only.
- A study of 10 repositories and 124 pull requests measured 28.64% lower median runtime and 16.58% lower output token consumption when AGENTS.md was present. Its authors submitted it to arXiv on 28 January 2026 and revised it on 30 March.
- A study from ETH Zurich and LogicStar.ai found that context files do not generally improve task success rates and raise inference cost by over 20% on average. Its authors submitted it to arXiv on 12 February 2026 and revised it to a third version on 29 September 2026.
- The same study found that instructions inside context files are well followed by coding agents, while repository overviews are not helpful.
- The business equivalent is a knowledge base for AI, meaning a short set of plain files containing offers, audience, prices, decisions and voice rules.
- Business Brain is a seven-day course in four modules, THINK, EXTRACT, BUILD and RUN, that builds those files, €67 one time, in English, no code required.
- The free entry point is the Business Brain AI Audit at https://hey-julia.kit.com/business-brain-audit.
What else do people ask about AGENTS.md?
What is an AGENTS.md file used for?
It gives an AI agent the working instructions for one specific project before that agent starts. That usually covers how to set the project up, which commands to run, the conventions to follow and the areas to leave alone. The point is that the agent reads it automatically, so nobody has to repeat those instructions in a new session.
Who created AGENTS.md?
OpenAI created it and released it in August 2025. On 9 December 2025 OpenAI contributed the format to the Agentic AI Foundation under the Linux Foundation, so no single company now controls its direction. The Linux Foundation announcement of that day reported adoption by more than 60,000 open source projects and agent frameworks.
Where do you put an AGENTS.md file?
In the root folder of the project, spelled exactly that way. Larger projects often add further files in subfolders, where the nearest one to the work takes precedence. The convention only works because the name is fixed, which is the whole reason several different AI tools can read the same file.
Does AGENTS.md work with Claude and ChatGPT?
Yes, and that was the design goal. Claude Code, ChatGPT’s Codex, GitHub Copilot, Cursor and Gemini CLI all look for it. Claude Code also has its own CLAUDE.md convention, and many projects keep a short CLAUDE.md that points at AGENTS.md rather than maintaining both.
How long should an AGENTS.md file be?
Shorter than most people write it, though for a reason that is often stated wrongly. The ETH Zurich and LogicStar.ai study did not find that longer files perform worse. It found that context files do not generally improve task success while raising inference cost by over 20% on average, and that instructions are well followed while repository overviews are not helpful. So the saving comes from cutting the description, not from cutting the rules.
Is AGENTS.md a standard?
It is an open format governed by the Agentic AI Foundation under the Linux Foundation rather than a formal standard from a standards body. The Linux Foundation describes it as “a simple, universal standard”. In practice the adoption across tools is what makes it work.
What is the difference between AGENTS.md and CLAUDE.md?
AGENTS.md is vendor-neutral and several AI tools read it, while CLAUDE.md is Claude Code’s own file. The content overlaps almost completely, which is why keeping both in full tends to produce two documents that slowly disagree with each other. A common approach is one AGENTS.md with a short CLAUDE.md pointing at it.
Do I need AGENTS.md if I do not write code?
No, because the convention only exists inside code projects. The idea underneath it is the part that applies to you, which is writing your operating instructions once somewhere your AI reads them instead of explaining your business again in every new chat. For a business rather than a codebase, that is a knowledge base for AI, and the research finding to copy is that specific rules get followed while general descriptions do not.
