AGENTS.md Checker
Paste or drop an AGENTS.md, CLAUDE.md, GEMINI.md, Copilot or Cursor rules file, or a whole folder, and see what to fix, line by line, with the doc or study behind each check. It runs in your browser.
Key facts
- AGENTS.md is plain Markdown read by Codex, Copilot, Cursor and other coding agents; over 60,000 open-source projects use it, and it is now stewarded by the Agentic AI Foundation under the Linux Foundation.
Examples
Checked as CLAUDE.md: read by Claude Code; GitHub Copilot reads one at the root.
Drop files or a whole repository folder here. Nothing is uploaded.
Example: CLAUDE.md · 47 lines · ~295 tokens
64/ 100
Needs work: 1 fix, 4 worth fixing, 2 suggestions.
- Project overview103
- Code style60
- Project structure43
- More34
- README-style 49%
- Build and test commands: 1 finding
- Concrete rules: 2 findings
- No contradictions or repeats: 2 findings
- Instructions, not a README: 2 findings
- Size: passed
- Links and imports: passed
- No secrets: passed
- No hidden characters: passed
- Headings: passed
- File names and format: passed
A checklist from each format’s docs and published studies, not a promise of how any agent behaves. SourcesTerms
Convert to another formatAGENTS.md, CLAUDE.md, GEMINI.md, Copilot or Cursor
Converts CLAUDE.md where the meaning carries over. Relative links are rewritten for the new place, and a rule scoped to some files stays scoped where the format allows it.
- @docs/api-conventions.md is now a link: the AGENTS.md format has no imports (only Claude Code expands them), so the agent sees a link it may or may not open. Paste in anything it must always know.
# AGENTS.md ## Project overview Ledgerly is a web app that helps small teams track invoices and payments. It is built with React and TypeScript on the front end and a Node API on the back end, and it stores everything in Postgres through Prisma. The goal of the project is to give customers a simple, fast and reliable way to see where their money is, and to make month-end close less painful for the people who do it. ## Project structure ``` src/ ├── api/ # Express routes ├── components/ # React components ├── lib/ # shared helpers └── pages/ # routes ``` ## Commands - Install: `pnpm install` - Dev server: `pnpm dev` - Tests: `pnpm test` - Type check: `pnpm typecheck` ## Code style - Write clean code and follow best practices. - Use 2-space indentation. - Use single quotes in TypeScript. - Prefer named exports over default exports. - Use double quotes for strings. - Never commit directly to `main`. ## Testing - Make sure everything works before you open a PR. - Run `npm install` after pulling. ## More - API conventions: [docs/api-conventions.md](docs/api-conventions.md) - How we deploy: [deployment guide](docs/deploy.md) - Use 2-space indentation.
Start a new fileThe essentials for your stack
Only the essentials: exact commands first, then rules an agent can’t learn from the code. Replace the example lines with yours, and add a rule when you see an agent make the same mistake twice.
# AGENTS.md ## Commands - Install: `pnpm install` - Build: `pnpm build` - Test: `pnpm test` - One test: `pnpm test -- path/to/file.test.ts` - Lint: `pnpm lint` ## Conventions - Replace these lines with rules an agent can’t learn from the code, such as “Money is integer cents, never floats.” - Name the folder for each kind of file that has a fixed home, such as “API routes live in `src/api/routes/`.” ## Boundaries - Ask before adding a dependency. - Don’t edit generated files; change their source and regenerate them. - Never read, print or commit `.env` files or keys. ## Before you finish - Run the test and lint commands above and fix what fails.
What each check is based onThe doc or study behind every rule
Each check names where its rule comes from: a format’s own docs, a study, or, where neither says anything, our own style suggestion. Rules checked against the docs on October 25, 2026.
Build and test commands
- No build or test commandsFixExact commands are the part agents use most: the AGENTS.md format lists them first, agents run the checks a file names, and in the ETH Zurich study agents used a tool 1.6 times per task when the file named it, under 0.01 when it didn’t. agents.md, Claude Code docs, ETH Zurich study
- No test commandWorth fixingAgents try to run the programmatic checks a file lists before they finish. Without a test command they guess or skip it. agents.md, Claude Code docs
- No build, lint or type-check commandSuggestionA lint or type-check command lets the agent catch its own mistakes before you do. agents.md
- More than one package managerWorth fixingCommands or rules name two package managers for the same project. Contradicting instructions may be followed either way. Claude Code docs, GitHub Copilot docs
Concrete rules
- Vague ruleSuggestionWrite instructions concrete enough to verify: "Use 2-space indentation" instead of "Format code properly", "Run npm test before committing" instead of "Test your changes". Claude Code docs
- A lot of CRITICAL and MUSTSuggestionNewer models follow instructions closely, and capitalised warnings can make them overreact. Anthropic suggests plain wording: "Use this tool when…". Claude prompting docs
No contradictions or repeats
- Contradicting rulesFixTwo rules ask for different things (single and double quotes, 2 and 4 spaces). Claude Code’s docs say it may pick one arbitrarily; GitHub’s say to avoid conflicting instructions. Claude Code docs, GitHub Copilot docs
- A rule and its oppositeWorth fixingOne line says to do something and another says not to. Claude Code docs, GitHub Copilot docs
- Repeated instructionWorth fixingEvery line is loaded into every session, so a repeat costs tokens and adds nothing. When files are combined (nested files, imports) repeats across them count too. Claude Code docs
Instructions, not a README
- Project overviewWorth fixingIn the ETH Zurich study, repository overviews in context files did not get agents to the right files any sooner, while every extra line raised cost. The agent reads the code and README itself. ETH Zurich study
- Folder listingWorth fixingA tree of folders is the kind of overview the ETH Zurich study found unhelpful: the agent can list the folders itself, and the tree goes stale. ETH Zurich study
- README materialSuggestionLicence, contributors, a table of contents or a roadmap are for people. The study’s authors advise only instructions an agent can’t find in the repository. ETH Zurich study (the wording is our style suggestion)
- Badges or imagesSuggestionAn agent can’t use a build badge or a screenshot. They cost tokens. Style suggestion.
- Long paragraphSuggestionGroup instructions under headings and bullets: organised sections are easier to follow than dense paragraphs. Claude Code docs
Size
- Over 200 linesWorth fixingClaude Code’s docs: target under 200 lines per file; longer files use more context and are followed less reliably. Move rules for one part of the code into path-scoped rules or a nested file. Claude Code docs
- Over 500 linesWorth fixingCursor’s docs: keep rules under 500 lines and split large ones. Cursor docs
- Over 32 KiBFixCodex stops adding instruction files once their combined size reaches 32 KiB (project_doc_max_bytes); the rest is never read. Codex docs
- Over 32 KiB with its parent filesWorth fixingCodex joins AGENTS.md files from the root down and stops at 32 KiB combined, so the deepest file is cut first. Codex docs
- Empty fileFixThe file has no instructions. agents.md
Links and imports
- Link to a missing fileWorth fixingThe link points at a file that isn’t in the folder. Claude Code’s own audit looks for references to files that don’t exist. Claude Code docs
- Link to a missing headingSuggestionNo heading in the file has this anchor. Style suggestion.
- Import of a missing fileWorth fixingImports resolve relative to the file that contains them, not the folder you start the agent in. Claude Code docs, Gemini CLI docs
- Quoted importWorth fixingClaude Code doesn’t import a path wrapped in quotes. For spaces, put a backslash before each one: @Design\ Docs/api.md. Claude Code docs
- Import from outside the projectSuggestionClaude Code asks before loading imports from outside the working directory, and teammates who clone the repository won’t have the file. Claude Code docs
- An @ that reads as an importSuggestion@name outside backticks is read as an import of a file called name. Wrap a mention, a decorator or a package name in backticks to keep it literal. Claude Code docs
- Imports nested too deepWorth fixingClaude Code follows imports at most four hops deep, Gemini CLI five levels by default; deeper files are not loaded. Claude Code docs, Gemini CLI docs
- Imports go round in a circleWorth fixingTwo files import each other (directly or through others). Gemini CLI stops the loop; the second import does nothing. Gemini CLI docs
- Imports in AGENTS.mdSuggestionClaude Code expands @path imports in AGENTS.md, but the AGENTS.md format has no import syntax: Codex, Copilot and Cursor read the line as plain text. agents.md, Claude Code docs
- Import syntax this format doesn’t haveSuggestionGitHub Copilot’s instructions files have no import syntax: the agent sees the @path as text. Use a Markdown link, or paste what matters. GitHub Copilot docs
No secrets
- Looks like a secretFixInstruction files are committed and loaded into every session. A key here is in the repository’s history and in every prompt; revoke it, then remove it. GitHub token formats, AWS IAM docs, Claude Code docs
- Possible secretWorth fixingA name like token, secret or password is set to a long value. If it is real, revoke it and use an environment variable. Style suggestion.
No hidden characters
- Text direction controlsFixBidirectional control characters make text read differently to you than to the model. They have been used to hide instructions in rules files. Trojan Source, Unicode UAX #9, Pillar Security
- Hidden textFixUnicode tag characters spell out text that is invisible on screen but read by the model: a known way to hide prompt injections. Unicode Tags chart, Pillar Security
- Invisible charactersWorth fixingZero-width and other invisible characters do nothing for a reader and can hide or split words the model still reads. Pillar Security
- Look-alike lettersWorth fixingA word mixes Latin letters with Cyrillic or Greek ones that look the same, so it isn’t the word it appears to be. Trojan Source
Headings
- No headingsSuggestionGroup related instructions under Markdown headings and bullets. Claude Code docs
- More than one top headingSuggestionOne # title, then ## sections, keeps the outline clear (and the token bar readable). Style suggestion.
- Heading level skippedSuggestionA heading jumps more than one level (## to ####). Style suggestion.
- Empty sectionSuggestionA heading with nothing under it. Style suggestion.
- Same heading twiceSuggestionTwo sections share a name; merge them so related rules sit together. Style suggestion.
File names and format
- File name or placeWorth fixingAgents find these files by exact name and place. agents.md, Claude Code docs, Gemini CLI docs, GitHub Copilot docs, Cursor docs
- Frontmatter in a plain Markdown fileSuggestionAGENTS.md, CLAUDE.md, GEMINI.md and copilot-instructions.md have no frontmatter fields; agents read the block as ordinary text. agents.md
- Cursor rule without frontmatterWorth fixingCursor decides when to apply a rule from its description, globs and alwaysApply fields. Cursor docs
- Cursor rule that never applies by itselfWorth fixingWith alwaysApply off and no description or globs, the rule is used only when you @-mention it. Cursor docs
- Missing applyToFixA path-specific Copilot instructions file starts with frontmatter that has an applyTo glob, such as applyTo: "**/*.ts". GitHub Copilot docs
- Claude Code won’t read this AGENTS.mdWorth fixingWith a CLAUDE.md in the same folder (or above), Claude Code reads the CLAUDE.md files only, by default. Add @AGENTS.md to the CLAUDE.md to load both. Claude Code docs
- AGENTS.md mentioned, not importedWorth fixingTelling Claude in words to read AGENTS.md means it sees the file only if it decides to open it. Write @AGENTS.md instead. Claude Code docs
- Gemini CLI reads GEMINI.md, not AGENTS.mdSuggestionBy default Gemini CLI loads GEMINI.md only. To have it read AGENTS.md too, list both in context.fileName in .gemini/settings.json. Gemini CLI docs
How the score works
The score starts at 100. Each finding takes off points by how much it matters: 12 for a fix, 5 for one worth fixing and 2 for a suggestion. The same check counts at most 3 times, so one habit repeated across a long file isn’t punished ten times over.
A key that looks real, hidden text or text-direction controls cap the score at 40, whatever else the file gets right: those are a risk to your repository, not a matter of style.
The weights are our judgement. No study scores instruction files, so read the findings, not the number: 90 and up is ready, 75 to 89 good, 50 to 74 needs work, below 50 needs a rewrite.
How this works: Method, 16 sources, Checked against 6 worked examples,
How this works
Method
Each file is read in the browser as Markdown, line by line. The checks follow each format’s own docs (agents.md, Claude Code, Gemini CLI, GitHub Copilot, Cursor and Codex) and two 2026 studies of context files; checks no source covers are labelled style suggestions. Tokens are characters ÷ 4. The score starts at 100 and loses 12, 5 or 2 points per finding by severity (each check counts at most 3 times); a secret or hidden text caps it at 40. The weights are our judgement.
Sources
- AGENTS.md (Agentic AI Foundation (Linux Foundation), checked 2026-10-25)
- How Claude remembers your project (CLAUDE.md and AGENTS.md) (Anthropic, Claude Code docs, checked 2026-10-25)
- Provide context with GEMINI.md files (Google, Gemini CLI docs, checked 2026-10-25)
- Memory Import Processor (Google, Gemini CLI docs, checked 2026-10-25)
- Adding repository custom instructions for GitHub Copilot (GitHub Docs, checked 2026-10-25)
- Rules (Cursor Docs, checked 2026-10-25)
- Custom instructions with AGENTS.md (OpenAI, Codex docs, checked 2026-10-25)
- Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents? (Gloaguen, Mündler, Müller, Raychev and Vechev (ETH Zurich, LogicStar.ai), arXiv:2602.11988, checked 2026-10-25, 2026)
- On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents (Lulla, Mohsenimofidi, Galster, Zhang, Baltes and Treude, arXiv:2601.20404, checked 2026-10-25, 2026)
- Prompting best practices (Anthropic, Claude API docs, checked 2026-10-25)
- Trojan Source: Invisible Vulnerabilities (Boucher and Anderson, USENIX Security 2023 (CVE-2021-42574, CVE-2021-42694), checked 2026-10-25, 2023)
- UAX #9: Unicode Bidirectional Algorithm (Unicode Consortium, Unicode 18.0.0, revision 52, checked 2026-10-25)
- Tags (code chart E0000 to E007F) (Unicode Consortium, Unicode 18.0, checked 2026-10-25)
- New Vulnerability in GitHub Copilot and Cursor: How Hackers Can Weaponize Code Agents (Pillar Security, checked 2026-10-25, 2025)
- Behind GitHub’s new authentication token formats (GitHub Blog, checked 2026-10-25, 2021)
- IAM identifiers: unique ID prefixes (AWS Identity and Access Management docs, checked 2026-10-25)
How it’s tested
6 worked examples for this page are checked by automated tests before every release: given the inputs, the tool must show the expected answer.
Limits
A checklist from each format’s docs and published studies, not a promise of how any agent behaves.
Privacy
On your device. Nothing you enter or open leaves this browser. About privacy labels
Changes
- First published.
What belongs in an instruction file
An agent reads its instruction file at the start of every task, so the file is part of every prompt. The two studies so far agree on what earns its place. In the ETH Zurich study of SWE-bench Lite and 138 tasks from 12 repositories that ship their own context files, files written by an LLM lowered the resolve rate slightly (by 0.5 and 2 points) and raised cost by 20% and 23%. Files written by the developers did a little better, 2.4 points on average, at up to 19% more cost. Overviews of the repository, which most generated files open with, didn’t get agents to the right files any sooner.
What agents did do was follow concrete instructions: when a file named the uv tool, agents used it 1.6 times per task, against under 0.01 times when it didn’t. A second study of 124 pull requests found runs with an AGENTS.md took 28.64% less time at the median and used 16.58% fewer output tokens. So: exact build, test and lint commands; the rules your linter doesn’t enforce; the folders not to touch. Not a tour of the codebase.
Claude Code’s docs add the practical rules this checker applies: under 200 lines, instructions concrete enough to verify (“Use 2-space indentation”, not “Format code properly”), headings and bullets rather than paragraphs, and no contradictions, because Claude may follow either side.
Which agent reads which file
| File | Read by | Imports | For some files only |
|---|---|---|---|
| AGENTS.md | Codex, Copilot, Cursor, many others; Claude Code when there’s no CLAUDE.md; Gemini CLI if configured | None in the format (Claude Code expands @path) | A nested AGENTS.md in that folder (the closest wins) |
| CLAUDE.md | Claude Code; Copilot reads one at the root | @path, relative to the file, 4 hops deep | .claude/rules/*.md with paths |
| GEMINI.md | Gemini CLI; Copilot reads one at the root | @file.md, 5 levels by default | GEMINI.md files in subfolders, loaded as tools touch them |
| .github/copilot-instructions.md | GitHub Copilot | None | .github/instructions/*.instructions.md with applyTo |
| .cursor/rules/*.mdc | Cursor | None | globs, or a description Cursor matches |
Sources
- AGENTS.md (Agentic AI Foundation (Linux Foundation)). AGENTS.md is plain Markdown at the repository root, with more files in subprojects; the closest file to the edited file wins, and explicit chat prompts override it. It recommends build and test commands, code style, testing instructions and security notes, and says agents will try to run the checks it lists. Used by over 60,000 open-source projects.
- How Claude remembers your project (CLAUDE.md and AGENTS.md) (Anthropic, Claude Code docs). Target under 200 lines per CLAUDE.md; write instructions concrete enough to verify ("Use 2-space indentation", not "Format code properly"); group them under headers and bullets; contradicting instructions may be picked arbitrarily. @path imports resolve relative to the importing file, nest at most four hops, are skipped inside code spans and fenced blocks, and a quoted path is not imported. Block-level HTML comments are stripped before loading. Claude Code reads AGENTS.md only when there is no CLAUDE.md; a CLAUDE.md can import it with @AGENTS.md.
- Provide context with GEMINI.md files (Google, Gemini CLI docs). Gemini CLI loads ~/.gemini/GEMINI.md, then GEMINI.md files in the workspace and its parents, and concatenates them. context.fileName in settings.json can name AGENTS.md instead. Files can import others with @file.md.
- Memory Import Processor (Google, Gemini CLI docs). Imports take relative or absolute paths, nest up to 5 levels by default, circular imports are detected and stopped, and @ inside code blocks and inline code is ignored.
- Adding repository custom instructions for GitHub Copilot (GitHub Docs). Repository-wide instructions live in .github/copilot-instructions.md; path-specific ones in .github/instructions/NAME.instructions.md with an applyTo glob in frontmatter. Copilot also reads AGENTS.md files anywhere (the nearest wins) and a single CLAUDE.md or GEMINI.md at the root. Avoid conflicting instructions.
- Rules (Cursor Docs). Project rules are .mdc files in .cursor/rules with description, globs and alwaysApply frontmatter; a rule applies always, by description, by matching files, or only when @-mentioned. Keep rules under 500 lines. Cursor also reads AGENTS.md at the root and in subdirectories.
- Custom instructions with AGENTS.md (OpenAI, Codex docs). Codex reads AGENTS.override.md or AGENTS.md (one per directory) from the project root down to the working directory, joins them root first, and stops adding files once the combined size reaches project_doc_max_bytes, 32 KiB by default.
- Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents? (Gloaguen, Mündler, Müller, Raychev and Vechev (ETH Zurich, LogicStar.ai), arXiv:2602.11988, 2026). On SWE-bench Lite (300 tasks) and 138 tasks from 12 repositories with their own context files: LLM-generated files lowered the resolve rate by 0.5 and 2 points and raised cost by 20% and 23%; developer-written files raised it by 2.4 points on average (not significant) at up to 19% more cost. Repository overviews did not get agents to the right files sooner. Agents did follow named tools: uv was used 1.6 times per task when the file mentioned it, under 0.01 when it did not. The authors advise only non-standard, non-inferable instructions.
- On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents (Lulla, Mohsenimofidi, Galster, Zhang, Baltes and Treude, arXiv:2601.20404, 2026). Across 10 repositories and 124 pull requests, runs with an AGENTS.md had a 28.64% lower median runtime and used 16.58% fewer output tokens, with similar task completion.
- Prompting best practices (Anthropic, Claude API docs). Newer models follow instructions closely and can overtrigger: soften aggressive language such as "CRITICAL: You MUST use this tool when…" to "Use this tool when…".
- Trojan Source: Invisible Vulnerabilities (Boucher and Anderson, USENIX Security 2023 (CVE-2021-42574, CVE-2021-42694), 2023). Unicode bidirectional controls can make text read differently to a person than to a machine, and look-alike letters from other scripts can hide in identifiers.
- UAX #9: Unicode Bidirectional Algorithm (Unicode Consortium, Unicode 18.0.0, revision 52). The explicit directional formatting characters are U+202A to U+202E and U+2066 to U+2069; the implicit marks are U+200E, U+200F and U+061C.
- Tags (code chart E0000 to E007F) (Unicode Consortium, Unicode 18.0). Tag characters U+E0020 to U+E007E mirror printable ASCII, and draw as nothing in normal text.
- New Vulnerability in GitHub Copilot and Cursor: How Hackers Can Weaponize Code Agents (Pillar Security, 2025). The "Rules File Backdoor": zero-width joiners, bidirectional markers and other invisible characters in rules files carry instructions the reviewer never sees.
- Behind GitHub’s new authentication token formats (GitHub Blog, 2021). GitHub tokens start ghp_ (personal access), gho_ (OAuth), ghu_ (user-to-server), ghs_ (server-to-server) or ghr_ (refresh).
- IAM identifiers: unique ID prefixes (AWS Identity and Access Management docs). Access key IDs start AKIA; temporary (STS) access key IDs start ASIA.
Frequently Asked Questions
Is my file uploaded?
No. Files are read and checked in your browser, and nothing is sent anywhere. They stay in this tab so a reload keeps them, and are gone when you close it or press Reset. The address bar holds only which example is open, never your text.
What is the difference between AGENTS.md and CLAUDE.md?
Both are Markdown instructions a coding agent loads at the start of every session. AGENTS.md is the shared format read by Codex, GitHub Copilot, Cursor and many others; CLAUDE.md is Claude Code’s own, and adds @path imports and path-scoped rules in .claude/rules. Claude Code now reads AGENTS.md too, but only when there is no CLAUDE.md, so if you keep both, put @AGENTS.md in the CLAUDE.md.
How long should an AGENTS.md or CLAUDE.md be?
As short as it can be while still holding what an agent can’t work out for itself. Claude Code’s docs target under 200 lines per file, Cursor’s under 500 lines per rule, and Codex stops reading at 32 KiB across the AGENTS.md files it combines. Everything in it is loaded into every session, so each line costs tokens on every task.
Do AGENTS.md files actually help?
The evidence is mixed and recent. An ETH Zurich study found context files didn’t raise success rates on average and raised cost by over 20%, while agents did follow the specific tools a file named. A second study found runs with an AGENTS.md finished faster (28.64% lower median runtime) and used fewer output tokens. Both point the same way: keep the file to exact commands and the rules an agent can’t find in the code.
How are tokens counted?
Characters divided by 4, the same rule of thumb the site’s token budget calculator uses; real tokenizers differ by model, so treat it as an estimate. Block-level HTML comments in a CLAUDE.md aren’t counted, because Claude Code strips them before loading the file, and imported files are added when they are in the folder you opened.
Can it check that my links and @imports point at real files?
Yes, when you open or drop the repository folder: the checker then knows every file path (it reads only the instruction files and the Markdown they import) and flags links and imports to missing files. With a pasted file it can only say how many links it couldn’t check.
Why does hidden text matter?
Some Unicode characters draw as nothing but are still read by the model. Researchers have shown rules files that carry instructions this way, invisible in review. The checker finds them, shows the hidden text, and removes them in one click.
Claude Code, Codex, Gemini CLI, GitHub Copilot and Cursor are trademarks of their owners. This checker names them only to say which files it reads, and isn’t made by or affiliated with any of them.