# AGENTS.md

> One instruction file that every coding agent agrees to read

Category: Agent skills and instruction sets (https://aiarabicdev.com/skills)
Canonical page: https://aiarabicdev.com/skills/agents-md
Tags: skills, conventions, instructions, agents

AGENTS.md is a convention rather than a tool: a single markdown file at the root of a repository holding the instructions a coding agent needs. A growing number of agents read it, which means one file instead of one per vendor.

## Facts

- Licence: Open convention, no license required
- Cost: Free and open source
- Self hostable: yes
- Added: 2026-08-23
- Last checked: 2026-08-23

## Links

- Website: https://agents.md

## Why a convention beats a feature

Every coding tool invented its own instruction file, so a repository accumulated several copies of the same rules that then drifted apart. A shared filename fixes that with no code at all.

The practical benefit is that the rules stay true. One file gets updated when a convention changes; four files get updated once and then quietly rot.

## What belongs in it

Commands, the architecture in one paragraph per area, and the rules that are not discoverable from the code. Which command verifies a change is the single most valuable line in the file.

What does not belong is anything the agent can read for itself. Describing the folder structure wastes context that the file listing already provides.

## Reach for it when

- more than one coding agent touches the repository
- there are conventions an agent cannot infer from the code
- you are tired of maintaining several instruction files

## Watch out for

- adoption is a convention, not a guarantee, so check what your tool reads
- a long file eats the context your task needs
- instructions that contradict the code get followed, which is worse than no instructions

---

aiarabicdev is a free directory of open source tools. No affiliate links, no sponsored placements.
New entries are announced at https://t.me/arabic_Intelligence