# What Is AGENTS.md? The Instruction File AI Coding Agents Obey

URL: https://whatisagenticai.net/blog/what-is-agents-md/
Published: 2026-10-25
Publisher: Little Tough LLC, maker of AI Agent Assistant: Agentic AI (https://apps.apple.com/us/app/ai-agent-assistant-agentic-ai/id6761501260)

AGENTS.md is a plain text file that tells AI coding agents like Codex and Claude Code how to work in a folder. What it does, vs CLAUDE.md, and why it can be hijacked.

AGENTS.md is a file name you now see in thousands of code projects, and this week it showed up in a security headline too. If you have wondered what this file is, why coding agents care about it, and how it differs from CLAUDE.md or a skills file, this page gives you the short version.

The quick idea: AGENTS.md is a note left for the AI. When a coding agent starts work in a folder, it looks for that note and follows it. That is useful, and, as researchers showed on October 22, 2026, it is also a door someone else can walk through.

**TL;DR:** AGENTS.md is a plain Markdown file that gives AI coding agents instructions for a project: how to build it, how to run tests, and which rules to follow. OpenAI started the format, and since December 2025 it is run by the Agentic AI Foundation under the Linux Foundation. Codex, Cursor, Gemini CLI, GitHub Copilot’s coding agent and many others read it, and Claude Code reads it when there is no CLAUDE.md. Because agents trust it, a planted AGENTS.md can hijack them, so never start an agent in your Downloads folder.

## What is AGENTS.md?

Think of a README file. It tells a new human teammate what a project is and how to use it. AGENTS.md is the same thing for an AI. The official site at agents.md calls it "a simple, open format for guiding coding agents," a place for build steps, test commands and code style rules that would clutter a normal README.

There is no special syntax. It is regular Markdown with headings and bullet points. A tiny example:

# AGENTS.md
## Setup
- Install with: npm ci
## Tests
- Run npm test before every commit
## Style
- Use TypeScript, no default exports
When an agent opens the project, it reads this file and treats those lines as standing orders. You stop repeating the same instructions in every chat.

## Who made AGENTS.md, and who uses it?

The format came out of OpenAI’s Codex team working with other tool makers, and the agents.md site credits OpenAI Codex, Amp, Google’s Jules, Cursor and Factory. On December 9, 2025, the Linux Foundation announced the Agentic AI Foundation with three founding projects: Anthropic’s MCP, Block’s goose and OpenAI’s AGENTS.md. So today no single company owns it.

The agents.md site says the format is "used by over 60k open-source projects." Tools listed there include:

| Tool | Made by | Reads AGENTS.md? |
| --- | --- | --- |
| Codex | OpenAI | Yes, natively |
| Gemini CLI and Jules | Google | Yes |
| Cursor | Anysphere | Yes |
| GitHub Copilot coding agent and VS Code | GitHub / Microsoft | Yes |
| Devin and Windsurf | Cognition | Yes |
| Junie | JetBrains | Yes |
| Claude Code | Anthropic | Yes, from v2.1.277, when no CLAUDE.md is present |

Big projects often have more than one. The site notes that OpenAI’s main repository had 88 AGENTS.md files when the page was written. The rule is simple: the AGENTS.md closest to the file being edited wins, and what you type in the chat overrides everything.

## AGENTS.md vs CLAUDE.md

CLAUDE.md is Anthropic’s own name for the same idea, used by Claude Code. Since version 2.1.277, Claude Code’s official docs say it can read AGENTS.md "as your project instructions," so a repo set up for other agents works without changes. The details matter:

- **Only AGENTS.md in the folder:** Claude Code reads AGENTS.md and shows a line saying it loaded it.

- **Both files present:** by default it reads only CLAUDE.md. A setting called Project instructions can make it read both.

- **One shared file:** many teams put the line @AGENTS.md at the top of CLAUDE.md, which imports it, so every tool follows the same rules.

## AGENTS.md vs skills.md and copilot-instructions.md

These names get mixed up a lot, so here is the difference in plain words:

| File | What it is for | When it loads |
| --- | --- | --- |
| AGENTS.md | Project rules for any coding agent | Every session in that folder |
| CLAUDE.md | Project rules for Claude Code | Every Claude Code session |
| SKILL.md (agent skills) | A packaged how-to for one kind of task | Only when that task comes up |
| copilot-instructions.md | GitHub Copilot’s own repo instructions | Copilot sessions in that repo |

A good rule of thumb: AGENTS.md is the house rules, a skill is a recipe card. Google is moving the same way for regular users, with [Gemini Skills](https://whatisagenticai.net/blog/what-are-gemini-skills/) and custom agents built from Markdown files in [Gemini Managed Agents](https://whatisagenticai.net/blog/what-are-gemini-managed-agents/).

## The AGENTS.md Downloads folder attack

On October 22, 2026, Forever Security researchers Gal Weizman and Omer Samet published how a customer’s coding agent tried to install a known malicious npm package called function-color. The order came from an AGENTS.md sitting in the customer’s Downloads folder, which was also where the agent had been started. BleepingComputer covered it on October 25.

Here is why it works. Browsers like Chrome, Edge and Firefox save downloads into Downloads by default, and a web page can trigger a download. If you later open a coding agent in that folder, it finds the planted file and follows it like any other project note. In the researchers’ tests:

- **Codex** ran the payload in "more than 90% of attempts," after the file told it to add a malicious MCP server to its settings.

- **Claude Code** was harder to fool. Using a planted CLAUDE.md instead, the researchers say it followed through "about 50% of the time," redirecting its connection to a server they controlled.

These are lab results from one security firm, with no published attempt counts. The researchers argue there is nothing for OpenAI or Anthropic to patch, since an agent that obeys its folder’s instructions is working as designed. The fix is how you use it:

- Start agents only in the project folder you mean to work on, never in Downloads or your home folder.

- Read any AGENTS.md or CLAUDE.md you did not write before the agent does, especially one that says a "bypass" flag is required.

- Keep approval prompts and sandboxing on. Tools like [Anthropic Sandbox Runtime](https://whatisagenticai.net/blog/what-is-anthropic-sandbox-runtime/) limit what an agent can touch.

- If you find a strange file or MCP entry, treat the machine as exposed and change the passwords and tokens the agent could reach.

## What this means for you

AGENTS.md is a small file with a big lesson: AI agents do what their instructions say, so where those instructions come from matters. For developers, it is a handy way to keep every coding tool on the same page. For everyone else, it is a reminder that setting up agents by hand means managing files, folders and risks.

If you just want tasks done, **Agentic AI** skips all of that. You describe the job on your iPhone or iPad, a team of up to four expert agents works on it, and you get the result back. No account and no setup, and the first 3 tasks are free.

## Quick answers

**What is an AGENTS.md file used for?** It gives AI coding agents standing instructions for a project, such as setup commands, how to run tests and code style rules, so you do not repeat them in every chat.

**Is it AGENTS.md or agent.md?** The official name is AGENTS.md, plural and usually in capital letters, placed at the root of a project or in subfolders.

**Does Claude read AGENTS.md?** Yes. Claude Code v2.1.277 and later reads AGENTS.md when there is no CLAUDE.md in the folder. If both exist, it reads CLAUDE.md, unless you import AGENTS.md or change the Project instructions setting.

**What is the difference between AGENTS.md and skills.md?** AGENTS.md loads every session as general project rules. A skill (SKILL.md) is a focused how-to that loads only when a matching task comes up.

**Can an AGENTS.md file be dangerous?** Yes. An agent follows whatever the file says, so a planted file can push it to install malware or leak tokens. Only run agents in folders you trust.

**Who owns AGENTS.md?** OpenAI created it, and since December 2025 it is stewarded by the Agentic AI Foundation under the Linux Foundation, alongside MCP and goose.

New to these terms? Our [agentic AI glossary](https://whatisagenticai.net/agentic-ai-glossary/) explains MCP, agent skills and sandboxes in plain English, and [how AI agents work](https://whatisagenticai.net/blog/how-ai-agents-work/) covers the loop that reads files like this one.

**Sources:** [agents.md](https://agents.md/) · [Linux Foundation: Agentic AI Foundation](https://www.linuxfoundation.org/press/linux-foundation-announces-the-formation-of-the-agentic-ai-foundation) · [SD Times](https://sdtimes.com/ai/linux-foundation-forms-agentic-ai-foundation-to-be-new-home-for-mcp-goose-and-agents-md/) · [Claude Code docs: memory and AGENTS.md](https://code.claude.com/docs/en/memory) · [Forever Security](https://forever.security/blog/hijacking-ai-agents-via-downloads-folder/) · [BleepingComputer](https://www.bleepingcomputer.com/news/security/ai-coding-agents-hijacked-using-agentsmd-file-in-downloads-folder/)