AGENTS.md Validator & Generator
Check an AGENTS.md file, pasted directly or fetched live by URL, against best-practice heuristics: line count against Claude Code's own published 200-line guidance, vague-instruction phrasing, missing structure, mixed line endings, a rough token estimate, and a self-import copy-paste footgun. AGENTS.md has no required schema (agents.md documents it as plain Markdown with no required fields), so this is a linter, not spec conformance checking. Or generate a new AGENTS.md from a simple form and copy the output. Paste mode runs entirely in your browser; URL fetch mode uses a rate-limited, SSRF-guarded server endpoint.
How to use
- Lint mode: paste AGENTS.md content directly, or enter a raw file URL to fetch and check it.
- AGENTS.md has no required schema, agents.md itself documents it as plain Markdown with no required fields, so this isn't spec conformance checking like the llms.txt validator. It's a best-practices linter: line count against Claude Code's own published 200-line guidance, vague-instruction phrasing, missing structure, a rough token estimate, and a couple of copy-paste footguns.
- Generate mode: fill in whichever common sections apply (dev environment, testing, PR conventions, code style, security) and copy the output. Skip any section that doesn't apply, none are required.
- A rough token estimate is shown (~4 characters per token) as an order-of-magnitude context-budget signal, not an exact tokenizer count.
Understanding the output
Results are grouped by severity. Errors flag things that are almost certainly mistakes (an empty file, a literal "@AGENTS.md" import line pasted inside the AGENTS.md file itself). Warnings flag likely quality issues (over 200 lines, vague instruction phrasing, mixed line endings). Info notes are optional suggestions (no headers found, no common sections detected, trailing whitespace) that may not apply to your project.
Common issues & tips
- •"That URL returned an HTML page, not raw text": fetch mode expects the raw file, on GitHub use raw.githubusercontent.com, not github.com/.../blob/....
- •"Found a literal @AGENTS.md line": that import syntax is for a CLAUDE.md file that imports AGENTS.md, seeing it inside AGENTS.md itself usually means the wrong file got pasted.
- •A high vague-instruction count usually means the file describes intent ("write good tests") rather than verifiable rules ("run `pnpm test` before committing"), the latter is what actually changes agent behavior.
Frequently asked questions
- Does this validate AGENTS.md against an official spec?
- Not in the sense the llms.txt validator does. AGENTS.md's own specification documents it as standard Markdown with no required fields, so there's no ordering or schema to violate. This tool is a best-practices linter instead: checks pulled from Claude Code's own published guidance for CLAUDE.md, which loads through the identical always-on-context mechanism, plus a couple of structural and copy-paste checks.
- Is my AGENTS.md content or the URL I check sent anywhere?
- Pasted text is linted entirely in your browser. Checking by URL calls a server endpoint to fetch that page's live content (necessary to avoid cross-origin browser restrictions), which is rate-limited and validates the target isn't a private or internal address before fetching, the fetched text itself isn't stored.
Related tools
llms.txt Validator & Generator
Validate an llms.txt file against the llmstxt.org spec, or generate one from a form.
Text Diff
Compare two blocks of text line by line, side-by-side or inline.
Markdown Live Preview & Exporter
Live GitHub Flavored Markdown editor with HTML preview, word count, and file downloads.