Comment by CMay

Prediction: this means extra work for developers. it also means extra potential abuse and risk through agents. the agents.md will sometimes be outdated or inconsistent with the readme. even the readmes are sometimes outdated or inconsistent with the code. some developers will interpret agents.md as compiling code for the agents to use, not for the user's to use, so maybe you're not even compiling the same code the same way a human should and expectations are broken. it's only a contextual efficiency if it's reliable too, because errors can mean having to use even more context accounting for it.

better idea since agents will already be cursed to do these things:

- any decent readme should have titled sections unless it's small

- if it's small, just feed the entire readme into it

- if it's large, provide it with a list of readme sections and let it choose which ones are relevant.

- also highlight which parts of the markdown include code blocks.

- if all else fails and it's huge without sections, just use RAG.

- if your model runs fast enough, then even if it's huge, just feed the whole thing in so you avoid the risks of RAG. setting up new software can be important enough that you may as well get it right.

people couldn't be hassled to make things accessible to the blind or visually impaired really, why suddenly should they be all excited to make everything accessible to AI? besides, agents.md comes with psychological baggage like, "i'm presuming my project is interesting enough to be used by agents!". just use the readme. it's basically always there and then in most cases you won't have to do 2 requests, you can just do 1.

if "agents.md" is supposed to be anything, it should be a locked file or special URL generated by github for your repo that always mirrors the relevant instructions in the readme so there's some higher reliability. then anyone that specifically wants to improve agents.md can simply follow some conventions in the readme file to make sure understanding is maximized. essentially, a github agent generates agents.md for other agents. if the github agent can't understand the readme well enough to produce an agents.md, what chance would your agent have? if the github agent feels like there are contradictions or confusion, it can automatically report that to the developers so they can sort it out.

besides, github themselves could have motivation to do this if they are destined to be slammed with tons of bot traffic they have no way to sufficiently block. at least this way maybe they can make it more efficient and it becomes another valuable feature of the platform.