# AGENTS.md generator and checker

Fill in your commands, rules and folders and get a short AGENTS.md that Codex, Cursor, GitHub Copilot and Claude Code can read. Or paste the file you have to see what to fix and which agents load it. It runs in your browser and stores nothing.

Use the tool: https://agentshandbook.com/tools/agents-md-generator (runs in the browser).

## How to use it

1. **Fill in what an agent can't guess.** Pick a stack to fill in the usual commands, then edit them to match your repo. Add style rules, folders to leave alone and the safety rules you want. Skip anything the agent can read from the code.
2. **Save it at the repo root.** Copy or download the file and commit it as AGENTS.md. In a monorepo, add another AGENTS.md inside each package. The closest file to the code wins.
3. **Check that it loads.** In Codex, run codex --ask-for-approval never "Summarize the current instructions." In Claude Code, look for the AGENTS.md loaded line at the start of the session. Then paste the file into the checker here.

## Questions

### What is an AGENTS.md file?

AGENTS.md is a plain markdown file at the root of a repo that tells coding agents how to work on the project. It holds setup, build and test commands, code style and project rules. It has no required fields or headings. The format is open and is now stewarded by the Agentic AI Foundation under the Linux Foundation.

### What is the difference between AGENTS.md and CLAUDE.md?

AGENTS.md is the shared file that Codex, Cursor, GitHub Copilot and many other agents read. CLAUDE.md is Claude Code's own file, with extras like @path imports, CLAUDE.local.md and .claude/rules/. Claude Code v2.1.277 and later reads AGENTS.md when the repo has no CLAUDE.md. When both exist, it reads only CLAUDE.md unless CLAUDE.md imports AGENTS.md.

### Which coding agents read AGENTS.md?

Codex, Cursor and GitHub Copilot cloud agent read it, per their own docs. Claude Code reads it when there is no CLAUDE.md. Gemini CLI reads GEMINI.md unless you add AGENTS.md to context.fileName in .gemini/settings.json. The agents.md site lists more, including Jules, Aider, Zed, Warp, Devin and Windsurf.

### Where does Codex look for AGENTS.md?

Codex first reads ~/.codex/AGENTS.md, or AGENTS.override.md there if it exists. Then it walks from the repo root down to your current folder and takes one file per folder: AGENTS.override.md, then AGENTS.md. Files closer to you appear later and win. It stops at 32 KiB combined by default, set by project_doc_max_bytes.

### How do I use AGENTS.md in a monorepo?

Put one AGENTS.md at the root for shared rules and another inside each package for its own commands. The agents.md site says the closest file to the edited code wins, and a chat prompt overrides them all. Cursor applies a nested file to its folder and children. Copilot uses the nearest one.

### What should an AGENTS.md include?

Include the exact commands to install, build, test and lint, plus code style, project layout and rules for commits and pull requests. The agents.md site also suggests security notes. Write rules an agent can check, such as "Run `pnpm test` before committing", and leave out what the agent can read from the code.

### What does the AGENTS.md checker look for?

It flags files over 200 lines or 32 KiB, API keys and tokens, vague rules with no command, a missing test command, no approval or safety rules, and repeated rules. It also lists which agents will load the file, given its name and folder. The check runs in your browser and sends nothing.

## Sources

- [AGENTS.md: a simple, open format for guiding coding agents](https://agents.md) (checked 2026-10-30)
- [Codex: Custom instructions with AGENTS.md](https://developers.openai.com/codex/guides/agents-md) (checked 2026-10-30)
- [Claude Code: How Claude remembers your project (CLAUDE.md and AGENTS.md)](https://code.claude.com/docs/en/memory) (checked 2026-10-30)
- [Cursor: Rules and AGENTS.md](https://cursor.com/docs/rules) (checked 2026-10-30)
- [GitHub Copilot: Adding repository custom instructions](https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions) (checked 2026-10-30)
- [Gemini CLI: Provide context with GEMINI.md files](https://geminicli.com/docs/cli/gemini-md) (checked 2026-10-30)

## Related playbooks

- [Map an unfamiliar codebase into a checked architecture document before you change it](https://agentshandbook.com/p/map-an-unfamiliar-codebase-before-you-change-it.md)
- [Upgrade a framework across a repo with a coding agent and the test suite as the gate](https://agentshandbook.com/p/upgrade-a-framework-across-a-repo-with-tests-as-the-gate.md)
- [Turn small tracker issues into reviewed pull requests with cloud coding agents](https://agentshandbook.com/p/turn-issues-into-pull-requests-with-cloud-agents.md)
- [Triage a production error from Sentry or logs into a tested fix pull request](https://agentshandbook.com/p/triage-production-error-into-a-fix-pr.md)

## Lessons

- [Agents act before you approve, even when you told them to ask first](https://agentshandbook.com/lessons/agents-act-before-you-approve.md)
- [Desktop and terminal agents delete files while they tidy up](https://agentshandbook.com/lessons/agents-delete-files-while-organizing.md)
- [Coding agents write code for old library versions or invent APIs](https://agentshandbook.com/lessons/coding-agents-use-outdated-library-apis.md)
- [Coding agents change, skip or misreport tests to reach a green run](https://agentshandbook.com/lessons/coding-agents-weaken-tests-to-pass.md)
- [An email can carry hidden instructions to the agent that reads it](https://agentshandbook.com/lessons/email-can-carry-instructions-to-your-agent.md)

More free tools: https://agentshandbook.com/tools.md