How to write an AGENTS.md: sections, examples and checks
· 4 min read
AGENTS.md is the file AI coding tools read before they touch your repository: what the project is, how to build and test it, and the rules to follow. Write it well and every AI tool starts each task knowing what a new teammate learns in their first week. This guide covers what goes in it, an example, and how to check it.
The format is described at agents.md. Claude Code reads CLAUDE.md instead, which can import AGENTS.md (Claude Code memory), so one file serves every tool. See AGENTS.md vs CLAUDE.md for that setup.
Where the file goes
Put AGENTS.md at the root of the repository, next to README.md. Add a CLAUDE.md beside it that imports it:
# CLAUDE.md
Project instructions for every AI tool live in [AGENTS.md](AGENTS.md).
@AGENTS.md
Tools change how they find these files, so check each tool’s documentation for the current behaviour.
The sections that matter
AI tools read the whole file in every conversation, so each line should earn its place. These sections cover what they need most:
| Section | What to write |
|---|---|
| Overview | Two or three sentences: what the project is, who it is for, where the main parts live. |
| Tech stack | Languages, frameworks and main libraries, with versions that change how code is written. |
| Commands | Install, run, build, test and lint, exactly as typed, in a code block, each with a comment. |
| Project structure | The main folders and what lives in each. |
| Code style | Conventions an AI can follow: naming, formatting, patterns to use and to avoid. |
| Architecture | Decisions to respect, such as which layer may call which. |
| Testing | How tests are written and what must pass before a change is done. |
| Git | Branch names, commit messages, what a pull request needs. |
| Security | Secrets stay out of the code; what data must never be logged. |
| Boundaries | What the AI always does, asks about first, and never does. |
| Skills and agents | The skills and agents the project has, and when to use each. |
Leave out any section you have nothing true to say in. An empty heading is noise.
An example
# Acme shop
A Vue storefront and a Node API for Acme's online shop. The API lives in `server/`.
## Commands
```bash
npm install # install dependencies
npm run dev # start the app and the API
npm test # unit tests
npm run lint # ESLint and Prettier
```
## Code style
- TypeScript strict mode; no `any`.
- Vue components use `<script setup>` and live in `src/components/`.
## Boundaries
**Ask first**
- Adding a dependency or changing the database schema.
**Never**
- Edit files in `dist/` by hand.
## Skills and agents
Load a skill when the task matches its description.
- `release-notes`: Writes release notes from merged pull requests. Use when preparing a release.
Be specific
“Follow best practices” and “write clean code” give an AI nothing to act on. Say which practice: “run npm run lint before finishing”, “components are PascalCase”. A rule the AI can check is a rule it will follow.
Keep the file well under 300 lines. A long playbook for one kind of task belongs in a skill, which loads only when that task comes up; AGENTS.md just says when to use it.
List your skills and agents
When the project has skills and agents, list each with one line on when to use it. The AI then knows they exist and picks the right one. List names and descriptions only: the instructions stay in the skill.
Build it in Skill Builder
In Skill Builder, open a project and choose Create AGENTS.md under Project instructions. It starts from the sections above, fills in the project’s name and description, and lists its skills and agents, kept up to date as they change. Each section is a block you can fill in, reorder or remove, and the export adds AGENTS.md and CLAUDE.md to the zip.
With Connect AI turned on, run /init-agents-md in your AI tool instead: like /init, the AI reads your repository (commands, folders, conventions, installed skills) and fills in the project’s instructions in Skill Builder, keeping the sections you already wrote. Skills you share from Skill Builder are listed with a note telling AI tools to load them through Connect AI when they are not installed in the repository.
Check it
The validator checks an AGENTS.md or CLAUDE.md: length, headings, empty and repeated sections, missing commands, vague advice, unfinished text, paths that only work on one computer, @imports, and the same security scan as skills (secrets, injected instructions, hidden text).
A quick checklist
- At the root, with a
CLAUDE.mdthat imports it. - Commands are exact and copy-pasteable.
- Every rule is specific enough to check.
- Under 300 lines; long playbooks are skills.
- No secrets, no personal paths.
- Skills and agents listed with when to use each.