AGENTS.md

AGENTS.md is a plain Markdown file placed in a code repository that tells AI coding agents how to work on that project: which commands build and test it, which code style to follow, and which conventions or security rules apply. The project site describes it as "a simple, open format for guiding coding agents" and positions it as a README for agents, a predictable place for context that would otherwise clutter the human-facing README 1.

What goes in an AGENTS.md file

There is no required schema. AGENTS.md is standard Markdown, and you can use any headings you like 1. The sections the format's site lists as common are:

• Project overview: what the code does and how it is laid out
• Build and test commands: the exact commands to install dependencies, run the dev server and run the test suite
• Code style guidelines: formatting, naming and language conventions
• Testing instructions: what has to pass before a change is considered done
• Security considerations: secrets handling, files that must not be touched

Because agents actually run the commands they find, the most useful entries are concrete ones: the exact test command, the linter to run before a commit, the directories that are generated and should not be edited by hand.

How agents find and apply it

The file usually lives at the repository root. Large repositories and monorepos can add further AGENTS.md files inside subprojects. The precedence rule in the spec is simple: the AGENTS.md closest to the file being edited wins, and explicit instructions the user types in chat override everything 1. The format itself is developed in the open on GitHub 2.

Which tools support AGENTS.md

The agents.md site lists compatible agents and editors including OpenAI Codex, Google Jules, GitHub Copilot, Cursor, Windsurf, VS Code, Zed, Warp, Devin, Aider, goose, Amp, Factory, JetBrains Junie, Google Gemini CLI, RooCode, Kilo Code and Augment Code, and says the format is used by more than 60,000 open-source projects 1. The list changes often, so check the site for the current set.

Some tools read AGENTS.md next to their own instruction files. Claude Code uses CLAUDE.md, but reads AGENTS.md when a repository has no CLAUDE.md, and a CLAUDE.md can also import AGENTS.md so both tools share one file 3. Cline detects AGENTS.md alongside its own .clinerules and shows it in its Rules panel 4.

Governance

In December 2025 the Linux Foundation announced the Agentic AI Foundation (AAIF), launched with three founding project contributions: Anthropic's Model Context Protocol, Block's goose and OpenAI's AGENTS.md 5. The agents.md site now states that the format is stewarded by the AAIF under the Linux Foundation 1.

AGENTS.md compared with other instruction files

• README.md is written for people: what the project is, how to get started, how to contribute.
• Tool-specific files such as CLAUDE.md or .clinerules do the same job as AGENTS.md but for one product 3 4.
• AGENTS.md aims to be the single file that many different agents read, so a team using several tools does not have to maintain several copies of the same rules.

Using agent instruction files for social publishing

The same idea works outside pure coding. When a team lets an AI agent draft or schedule social posts through an MCP server, the instruction file in the working repository is a natural place to write down the rules the agent should follow. Publora, a social media scheduler and publishing API, runs an MCP server with 18 tools covering 10 platforms that clients such as Claude Code, Cursor and Windsurf can connect to 6. A content repository used with a setup like that might carry an AGENTS.md section covering:

• Brand voice: tone, words to avoid, how the product name is written
• Per-platform rules: character limits, hashtag policy, whether links go in the post or the first comment
• Review: create posts as drafts and wait for a person to approve them before scheduling (see human-in-the-loop)
• Scheduling conventions: time zone, posting windows, which accounts are in scope

Keep in mind that these files are guidance, not enforcement. Claude Code's documentation says it treats instruction files as context rather than enforced configuration, and recommends hooks when an action has to be blocked no matter what 3. Hard limits, such as who can publish to which account, belong in the publishing tool's own permissions.