AGENTS.md generator
Fill in one form and get an AGENTS.md with your commands, conventions and hard limits. You also get one path-scoped rule written out for Cursor, GitHub Copilot, Claude Code, Cline and Devin Desktop, plus bridge files for tools that don't pick up AGENTS.md by default.
Where each tool looks for its instruction files →
# Acme web app
A customer-facing web app with an admin area and a small REST API.
## Stack
Next.js, React, TypeScript, pnpm
## Commands
- Install: `pnpm install`
- Run locally: `pnpm dev`
- Test: `pnpm test`
- Lint and type-check: `pnpm lint && pnpm tsc --noEmit`
- Build: `pnpm build`
## Code style
- Follow the formatting the linter enforces and leave untouched files as they are.
- Prefer small functions with clear inputs and outputs; keep side effects at the edges.
- Ask before adding a new dependency.
- Comment the reason behind non-obvious code, not what each line does.
## Testing
- Add or update a test for every behaviour you change.
- Run the test command and fix failures before you say you are done.
- Don't delete or skip a failing test to get the suite green.
## Commits and pull requests
- Write commit subjects in the imperative mood, under 72 characters.
- Keep each pull request to one change and say in the description how you tested it.
- Run lint and tests before every commit.
## Never
- Never commit secrets, API keys or .env files.
- Never hand-edit generated files under src/generated/; regenerate them instead.
- Never run destructive database commands against production.
- Never force-push to main or rewrite shared history.
The same rule for five tools
---
description: Conventions for files that match this glob
globs: app/**/*.tsx
alwaysApply: false
---
Follow the patterns already used by neighbouring files in this folder. Every exported function needs a docstring and a test in the matching test file.
---
applyTo: "app/**/*.tsx"
---
Follow the patterns already used by neighbouring files in this folder. Every exported function needs a docstring and a test in the matching test file.
---
paths:
- "app/**/*.tsx"
---
Follow the patterns already used by neighbouring files in this folder. Every exported function needs a docstring and a test in the matching test file.
---
paths:
- "app/**/*.tsx"
---
Follow the patterns already used by neighbouring files in this folder. Every exported function needs a docstring and a test in the matching test file.
---
trigger: glob
globs: app/**/*.tsx
---
Follow the patterns already used by neighbouring files in this folder. Every exported function needs a docstring and a test in the matching test file.
What makes an instruction file work
Put exact commands near the top
List the real install, test and lint commands with their flags, early in the file. Name the stack and versions precisely, and show a short code sample where prose would be vague.
Write explicit never rules
State plainly what the agent must not do, such as touching secrets, vendored code or production. Never commit secrets was the most common helpful constraint in the files GitHub reviewed.
Make each instruction checkable
Run npm test before committing can be verified; test your changes cannot. Remove contradictions, because when two lines disagree the model may follow either one.
Stay short and split by path
Anthropic suggests under 200 lines per file and Cursor under 500 per rule. Move guidance for one area into a path-scoped rule so it loads only when those files are in play. Imports tidy a file but don't cut context cost.
Skip what the agent already knows
In a study of four coding agents, context files did not reliably raise task success and added more than 20% to inference cost. LLM-written files slightly hurt and repository overviews didn't help, so keep the file to non-obvious requirements such as specific tooling.
Add rules when mistakes repeat
Start small and add a line when you see the agent make the same mistake more than once. Point to an existing file as the pattern instead of pasting a whole style guide.
AGENTS.md questions
Does Claude Code read AGENTS.md?
Yes, from v2.1.277. By default it reads AGENTS.md or .claude/AGENTS.md only when there is no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in the working directory or above. The claude-md-and-agents-md setting loads both, and a CLAUDE.md containing @AGENTS.md works on any version.
Does AGENTS.md need frontmatter or specific headings?
No. AGENTS.md is plain Markdown with no required fields and any headings you like. The agents.md site suggests sections such as a project overview, build and test commands, code style, testing, security notes and pull request guidelines.
How do I use AGENTS.md in a monorepo?
Put one AGENTS.md at the root and another inside each package that needs its own rules. Agents read the file nearest to the code being edited, and that file wins on conflicts. The OpenAI main repository had 88 of them when agents.md documented this.
How do I make Gemini CLI read AGENTS.md?
Gemini CLI still defaults to GEMINI.md. Add AGENTS.md to context.fileName in .gemini/settings.json, for example ["AGENTS.md", "GEMINI.md"]. Run /memory show to check what was loaded.
Which coding agents support AGENTS.md?
We checked the docs of OpenAI Codex, Claude Code, Cursor, GitHub Copilot, Devin Desktop, Cline and OpenClaw, which all read it natively, while Gemini CLI and Aider need one line of config. The agents.md site lists 23 compatible tools in total, including Zed, Warp, goose, opencode, Jules and JetBrains Junie.
Who maintains the AGENTS.md format?
OpenAI contributed AGENTS.md to the Agentic AI Foundation, a Linux Foundation directed fund announced on 2025-12-09 alongside MCP and goose. The agents.md site says over 60k open-source projects use it.