85 agentic tools audited for security incidents · Talk to the lab →
MotionticBook a call
Glossary

What is AGENTS.md?

AGENTS.md is a markdown file placed in a code repository that gives coding agents project-specific guidance, such as how to build, test and follow the codebase's conventions, and is an open project under the Linux Foundation.

Checked

A README is written for people. AGENTS.md is written for the coding agents that now open pull requests: how to install and run the project, which commands prove a change works, which conventions to follow, and where the deeper documentation lives.

The format is plain markdown with no required schema. Its value comes from being a shared convention, so one file serves several coding agents instead of each tool needing its own.

Where it came from

AGENTS.md originated at OpenAI. On 2025-12-09 the Linux Foundation announced the Agentic AI Foundation (AAIF) with three founding projects: AGENTS.md, Anthropic's Model Context Protocol and Block's goose. The foundation's platinum members include AWS, Anthropic, Block, Bloomberg, Cloudflare, Google, Microsoft and OpenAI.

Claude Code reads a similar file called CLAUDE.md, which Anthropic's guidance describes as project memory. Some teams keep one file and point the other at it.

What goes in a useful AGENTS.md

  • Commands that prove a change

    Install, build, test, lint and type-check commands, exactly as the agent should run them.

  • Conventions and hard rules

    Naming, structure, banned patterns and anything that must never happen, such as committing from the wrong directory.

  • A map, not a manual

    Short pointers to where architecture notes, API docs and decisions live, so the agent loads detail only when it needs it.

  • Current gotchas

    Framework versions that differ from what a model was trained on, generated files to leave alone, flaky tests to ignore.

How Motiontic's engineers apply it

On a client repo, Motiontic's engineers write the root file early and keep it short, with links into a docs folder that holds the detail. OpenAI's guidance for its newer models points the same way: keep the file's pointers contextual and replace rigid recipes with higher-level guidance.

The file is reviewed like code. When an agent repeats a mistake, the fix is often a single line added to AGENTS.md or a check added to the test suite.

AGENTS.md compared with a README and an Agent Skill

AGENTS.md compared with a README and an Agent Skill
READMEAGENTS.mdAgent Skill (SKILL.md)
Written forPeopleCoding agentsAny agent that supports skills
LoadedWhen someone opens itAt the start of a session in the repoName and description first, full body on demand
HoldsOverview and setupProject rules, commands and pointersA reusable procedure, often with scripts
ScopeOne projectOne repo or folderPortable across projects

Common questions

What is AGENTS.md used for?

AGENTS.md tells coding agents how to work in a specific repository: which commands to run, which conventions to follow and where the detailed documentation lives, so agent-written changes match the project.

Who maintains the AGENTS.md standard?

AGENTS.md is one of the founding projects of the Agentic AI Foundation, a directed fund under the Linux Foundation announced on 2025-12-09, alongside the Model Context Protocol and goose.

What is the difference between AGENTS.md and CLAUDE.md?

Both are root instruction files for coding agents. AGENTS.md is the cross-tool convention under the Linux Foundation; CLAUDE.md is the file Claude Code reads as project memory. Many repos keep one and reference it from the other.

How long should an AGENTS.md file be?

Short enough to read in full every session. Guidance from the labs favours a brief map of commands, rules and pointers, with longer procedures moved into linked docs or skills.

Running agents that have to hold up?

Describe the agent, the systems it touches and what it must never get wrong. The first call is with a lab engineer, who will say plainly whether it is ready for production, and whether Motiontic is the right team.