AGENTS.md – Open format for guiding coding agents • Hacker News Board

You could get this page down to under 100 words by simply having it say "the name of the file LLM agents will look at for instructions on the repo is AGENTS.md; that's it, that's the standard".

It's a real problem! Every agent right now has their own weird filename. I love David Crawshaw's sketch.dev, but for reasons passing understanding they choose "dear_llm.md" for theirs.

Re: AGENTS.md – Open format for guiding coding agents

#5

Post by stingraycharles » Wed, Aug 20, 2025, 12:34 AM UTC

Yet every agent I use (Claude Code, Gemini and Aider) uses their own custom filename.

It would be nice if it was standardized. Right now I’m using ruler to automate generating these files for all standards as a necessary evil, but I don’t envision this problem being solved soon. Especially because these coding agents also use different styles for consuming MCP configs.

https://github.com/intellectronica/ruler

Re: AGENTS.md – Open format for guiding coding agents

#6

Post by diggan » Wed, Aug 20, 2025, 12:35 AM UTC

ivanjermakov wrote: post #2

I'm still not convinced that separating README.md and AGENTS.md is a good idea.

At this point, README.md becomes the "marketing/landing page markdown" and AGENTS.md/CLAUDE.md becomes the ones you visit to get an overview of the actual code/architecture/usage.

Re: AGENTS.md – Open format for guiding coding agents

#7

Post by stingraycharles » Wed, Aug 20, 2025, 12:36 AM UTC

ivanjermakov wrote: post #2

I'm still not convinced that separating README.md and AGENTS.md is a good idea.

It is. README is for humans, AGENTS / etc is for LLMs.

Document how to use and install your tool in the readme.

Document how to compile, test, architecture decisions, coding standards, repository structure etc in the agents doc.

Re: AGENTS.md – Open format for guiding coding agents

#8

Post by sergiotapia » Wed, Aug 20, 2025, 12:38 AM UTC

New Phoenix Framework projects have an AGENTS.md file in the root! It's really cool. https://x.com/alkadaemon/status/1955348410145358199

Re: AGENTS.md – Open format for guiding coding agents

#9

Post by blinkymach12 » Wed, Aug 20, 2025, 12:38 AM UTC

ivanjermakov wrote: post #2

I'm still not convinced that separating README.md and AGENTS.md is a good idea.

I had the same thought as I read this example. Everything in the AGENTS.md file should just be in a good README.md file.

Re: AGENTS.md – Open format for guiding coding agents

#10

Post by ethan_smith » Wed, Aug 20, 2025, 12:39 AM UTC

eats_indigo wrote: post #3

In what way is this a format or standard? It's just markdown in a namespce

Standards derive their value precisely from being simple and widely adopted - think of .gitignore, CONTRIBUTING.md, or LICENSE files that work because everyone agrees on their location and purpose.