Skip to main content

​
Create your AGENTS.md

Adding AGENTS.md to your project takes just a few minutes. Here’s everything you need to get started.
1

Create the file

Create a file named AGENTS.md at the root of your repository. The name is case-sensitive — agents look for exactly this filename.
touch AGENTS.md
Most coding agents can scaffold an AGENTS.md for you. Try asking your agent: “Create an AGENTS.md file for this project.”
2

Add a project overview

Start with a brief description of your project to orient the agent:
AGENTS.md
# AGENTS.md

## Project overview
This is a React + TypeScript frontend application using Vite for bundling
and Vitest for testing.
3

Add build and test commands

Provide the exact commands an agent should run. Agents will execute these automatically to verify their changes:
AGENTS.md
## Setup commands
- Install deps: `pnpm install`
- Start dev server: `pnpm dev`
- Run tests: `pnpm test`
- Lint: `pnpm lint`
Agents will attempt to run these commands automatically. Be explicit about what must pass before a change is considered complete.
4

Add code style guidelines

Tell the agent how your team writes code:
AGENTS.md
## Code style
- TypeScript strict mode
- Single quotes, no semicolons
- Use functional patterns where possible
- Prefer named exports over default exports
5

Add PR and commit instructions

Help the agent write commits and PRs that match your team’s conventions:
AGENTS.md
## PR instructions
- Title format: [<project_name>] <Title>
- Always run `pnpm lint` and `pnpm test` before committing.
- Keep commits focused — one logical change per commit.

​
A complete example

Here’s what a real, production-ready AGENTS.md looks like:
AGENTS.md
# Sample AGENTS.md file

## Dev environment tips
- Use `pnpm dlx turbo run where <project_name>` to jump to a package instead of scanning with `ls`.
- Run `pnpm install --filter <project_name>` to add the package to your workspace so Vite, ESLint, and TypeScript can see it.
- Use `pnpm create vite@latest <project_name> -- --template react-ts` to spin up a new React + Vite package with TypeScript checks ready.
- Check the name field inside each package's package.json to confirm the right name—skip the top-level one.

## Testing instructions
- Find the CI plan in the .github/workflows folder.
- Run `pnpm turbo run test --filter <project_name>` to run every check defined for that package.
- From the package root you can just call `pnpm test`. The commit should pass all tests before you merge.
- To focus on one step, add the Vitest pattern: `pnpm vitest run -t "<test name>"`.
- Fix any test or type errors until the whole suite is green.
- After moving files or changing imports, run `pnpm lint --filter <project_name>` to be sure ESLint and TypeScript rules still pass.
- Add or update tests for the code you change, even if nobody asked.

## PR instructions
- Title format: [<project_name>] <Title>
- Always run `pnpm lint` and `pnpm test` before committing.

​
Tips for a great AGENTS.md

Use real commands

Copy-paste commands directly from your Makefile, package.json, or CI config — don’t paraphrase them

Keep it updated

Treat AGENTS.md as living documentation — update it whenever your build or testing workflow changes

Be specific

The more specific your instructions, the better agents will follow them. Vague guidelines lead to vague results

Add security notes

Flag sensitive files or areas the agent should be careful about — especially for deployment or auth-related code

​
Next steps

What to include

Explore every section type and see detailed examples for each

Agent compatibility

See all 20+ agents that support AGENTS.md and any agent-specific configuration

Monorepos

Learn how to use nested AGENTS.md files in monorepo projects

Format reference

Complete specification for the AGENTS.md format

Build docs developers (and LLMs) love

Get started for freeTalk to us