Skip to content
Get packs

Guide · Open source

How to use agents.md: write an AGENTS.md file for coding agents

Updated · written with AI from the project's own documentation and checked against our catalogue data

AGENTS.md is an open, simple format for a file that sits in a code project and gives AI coding agents context and instructions for working on it. This guide explains what the format is, what goes in it, and how to read and adapt the sample file in the agentsmd/agents.md repository. It is written for maintainers and developers who want consistent agent guidance without repeating it in every chat.

AGENTS.mdagentsmd/agents.md · ★ 25.3k · MIT

Quick start

  1. 1Clone the repository. Run git clone on agentsmd/agents.md to get the sample file and the format's website source.
  2. 2Read the sample. Open the sample AGENTS.md in the README and note the three sections: dev environment tips, testing instructions and PR instructions.
  3. 3List your project's real commands. Write down the install, test, lint and build commands your project actually uses, and where CI is defined.
  4. 4Create AGENTS.md in your project. Add a Markdown file named AGENTS.md to the project and write each instruction as a short, specific bullet.
  5. 5Add conventions. Include pull request title formats and checks to run before committing, if your team uses them.
  6. 6Check the file against your workflow. Ask a coding agent to perform a small task and see whether it follows the instructions. Adjust the file where it misses.

What is AGENTS.md?

AGENTS.md is described as a README written for agents. A README tells people how a project works; an AGENTS.md file gives AI coding agents a dedicated, predictable place to find context and instructions for the same project.

The format is about guidance, not enforcement. The README presents the file as guidance to help agents work on your project, not as a guarantee of how an agent will behave.

  • Typical contents named in the source: setup commands, test steps, and pull request conventions.
  • The file only has an effect when you use AI coding agents that read it.

Get the agents.md repository

The source README lists one install command: cloning the repository. The repository hosts the format's website and a sample file. The README shown does not describe a separate tool to install, so there is no program to run for the format itself.

git clone https://github.com/agentsmd/agents.md

Read the sample AGENTS.md file

The README includes a minimal example. It is a Markdown file with short sections for dev environment tips, testing instructions and PR instructions. Each section is a list of plain-language instructions with the exact commands an agent should run.

The sample is written for a pnpm and Turborepo style monorepo with a Vite and TypeScript package, so its specific commands only apply if your project uses the same tools. Use it as a pattern, not as a template to copy unchanged.

  • Dev environment tips: how to find and set up a package in a monorepo.
  • Testing instructions: where the CI plan lives, which commands run tests and lint, and what must pass before merging.
  • PR instructions: the title format and the checks to run before committing.
# 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`. ## 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. ## PR instructions - Title format: [<project_name>] <Title> - Always run `pnpm lint` and `pnpm test` before committing.

Write your own AGENTS.md for your project

Start from what an agent would otherwise get wrong. Write down the setup commands, the commands that run tests and lint, where CI is defined, and any conventions for commits or pull requests. Keep each instruction short and specific so an agent can act on it.

For monorepos, the sample shows the kind of detail that helps: how to jump to a package, how to add a package to the workspace, and how to confirm the package name in each package.json rather than relying on the top-level one.

  • Use exact commands from your project, not general descriptions.
  • Name the files and folders agents should check, such as CI workflow folders.
  • State pass conditions, for example that tests must pass before merging.
  • Keep one predictable file in the project root so agents know where to look.

Run the website locally (optional)

The repository includes a basic Next.js website that explains the project's goals and shows examples. You only need this if you want to work on the site itself. The README lists three steps: install dependencies, start the development server, and open the local address in a browser.

pnpm install pnpm run dev # then open http://localhost:3000

What people use it for

  • Telling an agent which pnpm filter command runs tests for one package in a monorepo.
  • Pointing agents to the CI workflow folder so they know which checks to run.
  • Setting a pull request title format so agent-made changes match team conventions.
  • Giving new agent sessions the same setup steps instead of repeating them in each chat.

Frequently asked questions

Is AGENTS.md a program I can install?

No. According to the README, AGENTS.md is a format and a website, not an application. The only install step in the source is cloning the repository, which holds the website and a sample file.

Is agents.md free to use?

The repository is licensed under MIT, as listed on the project page. You should check the repository's license file for the full terms before reusing material.

What language is agents.md written in?

The repository is listed as TypeScript. The website is a Next.js app, and it runs with pnpm according to the README.

What does the AGENTS.md file need to contain?

The source does not set a required structure. It shows a sample with sections for dev environment tips, testing instructions and PR instructions, and says the file can hold setup commands, test steps and pull request conventions.

Will AI agents always follow my AGENTS.md?

Not guaranteed. The README presents the file as guidance rather than enforcement, so you should check agent output and keep instructions specific.

Are there alternatives or comparable projects?

The project page lists no comparable projects. For your own setup, a README or a team wiki can hold similar information, but agents read the AGENTS.md file in a predictable place by design.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

AGENTS.md suits maintainers and teams who use AI coding agents and want one predictable file with consistent setup, test and pull request instructions. It is not a runnable tool and does nothing without an agent that reads it, so skip it if your project does not use coding agents or if you need enforced behavior.

Install options & downloads