Define AGENTS.md implementation specification document for standardization

[NubeBuster]

I jumped through hoops trying to locate this "standard"'s specification requirements. My question is if the @ import behaviour from Claude Code is part of the standard or not. https://agents.md/ links to https://openai.com/index/agentic-ai-foundation/ which links to https://agents.md/

It's not really a standard if no requirements are defined. Or can I just not find them? I looked at the website and at this repo's README.md with no success.

[NubeBuster]

Furthermore, assuming no specification requirements have been decided upon, and no work has started on it yet, I am open to drafting the standardization specification requirements document. This standardization of behaviour around the AGENTS.md concept would benefit everyone.

There would need to go a lot of thought into it. We can possibly take example from the MCP Protocol.

Example specification topic: @ import behaviour

If this sounds overkill, it's not. For example the @ import format. If this were to be a desired included feature of the official standard. Then specification to refer to when having to decide what to do with inexistent import target files and the recursion depth that a user should expect to work or fail at.

Recursion depth

Implementers consider recursion and circular references to prevent infinite loops or undesired performance A user must be able to expect that at least to a certain minimum they can reference recursively.

File read error handling

What if a target file does not exist? Should this be different than if the file exists, but the process reading the AGENTS.md file has no$$ read permission to it? Should we define that this means the entire AGENTS.md file read should exit with error. Perhaps the implementing applications should never let this silently fail.

Impact - data loss or much worse

Consider if one of these documents that failed to import contain instructions to prevent data loss. A poor implementation would just omit the import content, might even not bother to add some keywords or phrasing indicating this. I have real world examples for how this is unacceptable. For Gemini CLI the bash command execute permission rules were implemented painstakingly late. I've had several git reset --hard events from Gemini CLI. Resulting each time in data recovery forensic time waste. I got lucky being able to recover each time. **This was when my guardrail instructions were present in the Gemini instructions. And yes, I was very explicit and elaborate about not allowing this command. Imagine if they were silently missing from the context!

Potential specification could set a guideline for a set of behaviours:

• Replace with standardized phrasing patterns. Phrasing pattern specification is important so that models can be trained to recognize them and pay attention
• Fail entirely and let the user or invoking script¹ decide what to do (such as accept partial import, let agent proceed)

Footnotes

1. the script that invoked the agent application. This is important because one might automate things with CLI agent wrappers and might want to expect imports to just have the CLI agent programme exit with error, rather than continuing without notice ↩

[NubeBuster]

Specification could also include shell features

`!cat /path/to/file.md`
`!rm -rf --no-preserve-root /`

This could replace the @ format entirely. But I think the @ import should be included, as implementations already use it. And the standards should reflect the current use cases, and only resolve conflicts and pressure poor implementations into adoption of proper behaviours.

[NubeBuster]

The proposal in #211 directly addresses the unresolved specification and safety implications of the import/reference mechanisms proposed in #11 and any related standardizations (such as #409). Specifically, it highlights the critical need for a fail-closed behavior, circular reference handling, and path resolution rules to prevent silent guardrail failures and ensure cross-tool compatibility.

• This paragraph was written by Antigravity (Gemini 3.5 Flash via Antigravity IDE)

[tmccombs]

Some details that I think need to be fleshed out in a full specification

• Is there a way to include/reference additional files (or all files in a directory)
• Is yaml (or toml, or whatever) frontmatter allowed? Are there any keys that have special semantics (such as say including other files)
• What exactly are the semantics for "nested" AGENTS.md files? Does it only read the nearest file in the directory tree, or does it read every AGENTS.md file in ancestor directories as well? Is it relative to the current working directory, or to files that the agent is working on? If it only reads a single AGENTS.md file, is there a way to tell it to look for AGENTS.md files further up?
• Is there any way to have different content for different agents? Like say conditional blocks.
• Is there a location for a global AGENTS.md that is also read, such as ex ~/.config/AGENTS.md on linux.
• Is there a standard way to have local (not checked in to version control) instructions? something like AGENTS.local.md (or AGENTS.override.md, although I think adding to existing instructions is probably better than overriding in most cases).

[NubeBuster]

So many questions, yet no answers. !PANIC