Add AGENTS.md

[felixarntz]

AGENTS.md is an emerging standard for a central LLM assistance file supported by many providers and tools.

While previously we were not considering any provider-specific or tool-specific files in this repository for reasons of neutrality, the new AGENTS.md format addresses that problem and is already widely supported. For tools without out-of-the-box support, potentially it can be configured manually as an additional context file, or it can be symlinked under another file name mandated by the respective tool.

As for the contents of the file, let's start pragmatically. We don't have to cover everything right away, instead we can iterate with time based on practical usage of AI coding tools. As we notice aspects that should be captured here or aspects that confuse the LLM or tool and should be fixed, we can address them in subsequent PRs.

For reference and credit: Much of the content is inspired by or directly copied from an older discarded CLAUDE.md file created by @JasonTheAdams, see 1ab1a24.

[JasonTheAdams]

Love it!! 🎉

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: felixarntz <flixos90@git.wordpress.org>
Co-authored-by: JasonTheAdams <jason_the_adams@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[justlevine]

Was this evaled in any way, or compared with

• no AGENTS.md
• an AGENTS.md that just says "Follow the guidelines in CONTRIBUTING.md"

I don't see a mention on this PR, and the source was for scaffolding an empty project which then still had to undergo significant work after the file's removal.

Would be helpful to keep a record, since we know this is inevitably going to be used as prior art elsewhere.

cc:

• Proposal: Add common instruction files for AI assisted coding tools abilities-api#30
• Proposal: Add common instruction files for AI assisted coding tools mcp-adapter#9

[felixarntz]

@justlevine It wasn't, but I think it's fair to assume that having a basic AGENTS.md will make AI tools do better than without having it.

Regarding your second point, to just tell it to use CONTRIBUTING.md, that's a fair point. We could see if one works better than the other.

As the PR description says, this is just a starting point. How well it works will have to be based on practical usage, and iterations are always welcome. But without having anything in place (like this), each contributor using an AI tool will build their own such files in a vacuum, and having this here gives us a central place to work with and iterate on.

Crowd-sourcing the testing and feedback on this file is going to be more powerful than only one of us doing a deep dive (but inevitably biased) session on evaluating what works well.

[justlevine]

but I think it's fair to assume that having a basic AGENTS.md will make AI tools do better than without having it.

Anecdotally my experience differs,

• when contributing to public projects with a file made for a specific type/gen of model (e.g. circa GPT3.5 when using 4.1, or 4o when using Gemini or Sonnet)
• when contributing to public and private projects where the sources of truth / human docs differ from the agentic docs.

(More in WordPress/abilities-api#30 (comment) )

Crowd-sourcing the testing and feedback on this file is going to be more powerful than only one of us doing a deep dive (but inevitably biased) session on evaluating what works well.

Definitely agree with this this. The important thing here IMO is to leave to document our assumptions before they become Chesterton fences. Now done 🚀