add(considered): AGENTS.md is a repository convention, not a website one - #213
Draft
jdevalk wants to merge 1 commit into
Draft
add(considered): AGENTS.md is a repository convention, not a website one#213jdevalk wants to merge 1 commit into
jdevalk wants to merge 1 commit into
Conversation
AGENTS.md passes the adoption bar easily — 60k+ repositories, 20+ tools, now stewarded by the Agentic AI Foundation alongside MCP — so its absence from an agent-readiness spec needs an explanation rather than silence. It fails the direction test instead. Every agent-readiness topic here describes something an origin answers over HTTP to an agent that arrived from outside; AGENTS.md travels with the source to an agent that already cloned it. No URL to check, no visitor or crawler outcome. The entry names Agent Skills discovery as the website-side equivalent, since the two are easy to confuse. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Deploying specification-website with
|
| Latest commit: |
4e7440d
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://24d4c456.specification-website.pages.dev |
| Branch Preview URL: | https://considered-agents-md-2026-09.specification-website.pages.dev |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What changed
Adds
src/content/considered/agents-md.md— one entry in the public/considered/register. No spec page, no changelog entry, no derived surfaces touched.Why now
Today's standards scan picked it up through the Agentic AI Foundation thread: A2A moved into AAIF on 17 August 2026, and AAIF's anchoring contributions are MCP,
gooseand AGENTS.md. The spec covers MCP and A2A and says nothing at all about AGENTS.md, which is now the odd silence — this is a spec about agent-readiness, and AGENTS.md is the single most widely adopted agent-facing Markdown convention there is.It comfortably clears the adoption bar (60,000+ repositories, 20+ coding tools). Turning it down on adoption grounds would be wrong; turning it down silently would leave readers guessing. So: an entry, with the actual reason.
The reason —
out-of-scopeNobody serves it. Every agent-readiness topic in this spec describes something an origin answers over HTTP to an agent that arrived from outside and knows nothing about the site — llms.txt, Agent Skills discovery, A2A agent cards, Markdown source endpoints. AGENTS.md runs the other way: instructions that travel with the source, read by an agent that already holds a working copy. There is no URL to check, and a website is neither better nor worse for the file existing.
The entry also names Agent Skills discovery as the website-side equivalent, because the two are the same instinct pointed in opposite directions and are easy to confuse.
revisit: a served form of the convention —agents.mddescribing a path an origin answers, or consumers fetching AGENTS.md over HTTP from a site they never cloned. Direction is the open question, not adoption.Sources
Verification caveat: the scan sandbox blocked direct fetches to
agents.mdandlinuxfoundation.org, so these three URLs were confirmed via search-index results (title + URL returned live) rather than a directGET. Worth a click before merge.Checks
npm run buildpasses (170 pages, Pagefind index clean).npm run format:checkclean; pre-commit hook (eslint, prettier, skill-drift) passed — SKILL.md still agrees at 170 pages / 10 categories.sign:skillneeded.🤖 Generated with Claude Code