AGENTS.md: the paths squirrel probes and what counts

What AGENTS.md is

AGENTS.md is a plain Markdown file that tells a coding agent how to work in a codebase: how to install dependencies, how to run the tests, which commands to use, and the conventions the project expects. It lives at the repository root and is read by the agent before it starts changing files.

It is aimed at a repository rather than at a website, so it matters for a site that has a public codebase behind it and not for a site that does not. Absence is never a defect here.

What squirrel checks

The rule runs once per crawl against four probed paths, in this order: /AGENTS.md, /agents.md, /.well-known/agents.md and /docs/AGENTS.md. It emits one check:

• agents-md: reports at info status with the message AGENTS.md not checked: the discovery probe was not sent and the value not-checked when no well-known probe ran.
• agents-md-present: reports at info status with AGENTS.md found at <path> (N bytes) when a probe returned 200 with a body that did not sniff as HTML and read as Markdown. With no such hit anywhere, but a probe that returned 200 with an HTML body, it reports at info status with <path> responded 200 but returned an HTML page (SPA fallback) — not a real AGENTS.md. With no hit and at least one of the four paths never requested or unanswered, it reports at info status with AGENTS.md not checked: <reason>, where the reason is the discovery probe was not sent or the discovery probe got no answer, and the value not-checked, listing those paths in details.notChecked. With no hit at all, the result depends on the rest of the site: a site that publishes /llms.txt gets a warning with No AGENTS.md found — this site publishes llms.txt, so consider an AGENTS.md for coding agents too, and every other site gets an info result with No AGENTS.md found — consider adding one if this site has an associated codebase.

That last condition is the whole design. Recommending AGENTS.md to every site would be noise on a restaurant’s website, so the recommendation only fires where the site has already shown it is developer-facing by publishing llms.txt. The rule’s severity is info, so even the warning is a recommendation and does not move the score.

A probe goes unsent when discovery probes are turned off, when no rule that reads it was enabled for the crawl, or when the crawl’s preamble time budget ran out first. A probe that went out and got no answer, a refused connection or a timeout, counts the same. None of those says anything about the site, so the result is not-checked, never absent.

How to fix it

# AGENTS.md

## Setup
`bun install`

## Tests
`bun test <file>` runs one file. Never run the suite bare.

## Conventions
TypeScript only. Format with oxfmt before committing.

Commit it at the repository root. Publishing it on the website is optional; this rule probes the site because that is what an audit can see.

The common false positive is a single-page application whose server returns index.html for every unmatched path, which is why the rule sniffs the body rather than trusting the status code.

Enable / disable

Disable this rule

[rules]
disable = ["ax/agents-md"]

Disable all Agent Experience rules

[rules]
disable = ["ax/*"]

Enable only this rule

[rules]
enable = ["ax/agents-md"]

enable replaces the default ["*"], so this is the only rule selected. Leave disable out: a rule that matches any disable pattern is skipped even when enable names it. Only an enabled setting under a rule’s own [rule_options] table overrides both lists.

Related rules

• ax/llms-txt: the site-facing equivalent, and the signal that turns this rule’s note into a recommendation.
• ax/well-known-agent: MCP and A2A manifests, the machine-readable half of agent discovery.
• ax/api-discovery: OpenAPI and OAuth documents an agent needs before it can call anything.
• ax/markdown-response: serving Markdown for the site’s own pages.

Agent experience findings ship in every audit next to the SEO, performance and security rules. See llms.txt for how an agent works through a report.

References

• AGENTS.md
• text/markdown media type, RFC 7763

Check your site

Run squirrel audit https://example.com and open the Agent Experience section of the report. The path and file size are listed when one is found. Signed-out local audits need no account and cost nothing. Signed-in audits spend credits.