AGENTS.md: Guide, Risks and Security

Last updated: November 5, 2026

What is AGENTS.md? AGENTS.md is a plain Markdown file, usually at the repository root, that tells AI coding agents how to build, test and behave in your project. Think of it as a README for agents. Codex, Cursor, GitHub Copilot and Gemini CLI read it, and Claude Code now does too. Because agents obey it, a planted AGENTS.md is also an attack path.

TL;DR: Key Takeaways

• AGENTS.md has no required fields and is used by over 60,000 open-source projects, with the Agentic AI Foundation under the Linux Foundation as steward (AGENTS.md).
• Claude Code reads AGENTS.md directly from version 2.1.277, but only when no CLAUDE.md sits in or above your working directory (Claude Code docs, 2026).
• Codex stacks instruction files from the project root down and stops at 32 KiB by default (OpenAI, 2026), while Copilot gives the nearest file priority (GitHub Docs, 2026).
• A study revised on September 29, 2026 found context files did not generally improve task success and raised inference cost by over 20% (Gloaguen et al., 2026).
• On October 22, 2026, Forever Security reported a malicious AGENTS.md in a customer's Downloads folder, and Codex ran the malware in over 90% of its test attempts (Forever Security, 2026).
• Anthropic's docs say Claude treats these files as context, not enforced configuration, and recommend a PreToolUse hook to block an action (Claude Code docs, 2026).

At a glance: the key facts in one table

Quick Answer

What should an AGENTS.md contain, and what can go wrong?

Put commands, code style, testing steps and clear boundaries in a short file at the repository root, and add nested files for packages that differ. The risk is trust. Agents follow the file they find, so review it like code and enforce safety rules in permissions, not in prose.

How we researched

On November 5, 2026 we read the AGENTS.md site and the current Codex, Claude Code, Cursor and GitHub Copilot documentation. We also read the arXiv study on context files, the Forever Security report and the Cloud Security Alliance note on instruction-file poisoning. The tool table and the lockdown checklist are our synthesis.

What Is AGENTS.md and Which Tools Read It

AGENTS.md is an open format for giving coding agents the context a README leaves out: build steps, test commands and team conventions. According to the AGENTS.md site (2026), it works across Codex, Cursor, Gemini CLI, GitHub Copilot, Aider, Windsurf, Devin and more, so one file can serve every agent your team uses.

The format started as a cross-vendor effort between OpenAI Codex, Google Jules, Cursor, Amp and Factory. According to the Cloud Security Alliance (2026), OpenAI donated it to the Linux Foundation's Agentic AI Foundation in December 2025, and the site now reports over 60,000 projects using it.

For Claude Code the default matters. A repository with both files makes Claude read only CLAUDE.md. Teams that want one shared file put @AGENTS.md at the top of their CLAUDE.md, a pattern we also cover in our Claude Code skills guide.

How to Set Up Your File Step by Step

Create AGENTS.md at the repository root, keep it short, and write only what an agent cannot infer from your code. Start with the commands it must run, then conventions and boundaries. Add nested files only where a package truly differs, and test the result by asking the agent which instructions it loaded.

1. Create AGENTS.md at the repository root. Most agents can scaffold a first draft if you ask.
2. List exact commands with flags, such as install, test and lint, near the top.
3. Add code style rules that differ from the defaults, and one short code example.
4. Add boundaries: what the agent may do freely, what needs approval and what it must never touch.
5. For a monorepo, place another AGENTS.md in each package. The closest file to the edited code wins.
6. Check loading. In Codex run it with a prompt asking to list the instruction sources. In Claude Code run /memory and look for the path.

Precedence rules at a glance

Each tool resolves conflicts a little differently, so check which file your agent actually loaded before you trust it.

If your team already has an AGENT.md file, the AGENTS.md site suggests renaming it to AGENTS.md and keeping a symbolic link under the old name.

Examples That Work, and What to Leave Out

The best AGENTS.md files are short, specific and command-first. GitHub's analysis of more than 2,500 agent files in 2025 found that the strongest ones cover six areas: commands, testing, project structure, code style, git workflow and boundaries. It also found that one real code snippet beats paragraphs of explanation.

Less is often more. According to Gloaguen et al. (2026), context files did not generally improve task success and raised inference cost by over 20% on average. Agents followed the instructions well, but repository overviews were not helpful. The authors conclude these files are useful for non-standard practices, so skip the tour of your folder tree.

AGENTS.md Security Risks and How to Lock Them Down

AGENTS.md is a trusted instruction channel that anyone who can place a file in your folder can write to. Agents follow it by design, so a poisoned file can make an agent install packages, rewrite its own settings or leak credentials without any software bug. This is prompt injection delivered as a file.

A planted file hijacked Codex in tests

On October 22, 2026, Forever Security reported finding an AGENTS.md in the Downloads folder of a real customer. It told the agent to register a server and install function-color, a known malicious npm package. The company stopped the agent before any code ran and could not tell how the file got there, as The Hacker News also reported.

The researchers then showed the full path works. A web page can save a file to Downloads without a click, and Codex follows an AGENTS.md in a folder it trusts. According to Forever Security (2026), Codex ran the malware in more than 90% of attempts. The researchers' own CLAUDE.md redirected Claude Code's API traffic about half the time, which exposes the login token. The researchers argue there is nothing for vendors to patch, because the agent did what it was built to do.

The pattern is older than one incident

According to the Cloud Security Alliance (2026), instruction and settings files have been abused since 2025, and the newest cases persuade the agent instead of exploiting a load-time bug.

Written rules do not close the gap. The CSA note cites an August 2026 preprint, not peer reviewed, that studied 481 public CLAUDE.md files. It found only about 4% to 16% of the security rules developers wrote matched a built-in control that could enforce them. Our MCP tool poisoning guide covers the same trust problem for tool descriptions.

How to lock down your AGENTS.md

The goal is to treat instruction files as code and move safety rules into controls the agent cannot talk its way past. Our OWASP Top 10 for Agentic Applications guide shows how these agent risks are ranked.

Controls on the developer machine are only one layer. Agent Gateway (TrustGate) sits between coding agents and the models and tools they use. NeuralTrust's secure coding assistants page describes scanning every input for hidden instructions before it reaches the model, approving MCP servers per team and logging every prompt and tool call. A gateway sees model and tool traffic, so it does not replace blocking writes to local config files. Agent Runtime Security (TrustGuard) adds inline enforcement on that traffic. For the MCP side, see our Claude Code and Cursor MCP security guide.

Shared File or Tool-Specific Rules: Which Should You Choose?

Use AGENTS.md as the shared source of truth when several agents touch one repository, and add a short CLAUDE.md or .cursor/rules file only for tool-specific behavior. Keep one canonical file, so the instructions your agents follow cannot drift apart between tools or teams.

Conclusion

AGENTS.md is the closest thing coding agents have to a shared standard, and a short, command-first file pays off across Codex, Cursor, Copilot and Claude Code. Its trust model is also its weakness, as the October 2026 Downloads-folder case showed. Treat every AGENTS.md as code, keep agents out of folders you do not control, and enforce your security rules in permissions, hooks and a gateway, not in Markdown.

Secure Coding Agents in Production with NeuralTrust

Put a gateway between Claude Code, Codex and Cursor and your models and tools, so hidden instructions, unapproved MCP servers and leaked secrets are caught before they cause damage.

Related Comparisons

• Claude Code Skills
• Codex vs Claude Code: Benchmark Comparison 2026
• Claude Code vs Cursor: Benchmark Comparison 2026
• MCP Security Best Practices

FAQs about AGENTS.md

1. What is AGENTS.md?

AGENTS.md is a plain Markdown file that gives AI coding agents project instructions such as build steps, test commands and conventions. It has no required fields and sits at the repository root, with optional nested files. Codex, Cursor, GitHub Copilot, Gemini CLI and Claude Code can read it.

2. Where do I put AGENTS.md?

Put it at the repository root. For a monorepo, add another AGENTS.md inside each package that needs different rules. Most agents read the nearest file to the code they edit, and Codex also reads a global one from its home directory. Keep each file short and specific.

3. Does Claude Code read AGENTS.md?

Yes, from version 2.1.277, but only when there is no CLAUDE.md or CLAUDE.local.md in or above your working directory. If you have a CLAUDE.md, add @AGENTS.md at the top to import it, or change the Project instructions setting to read both files.

4. What happens when instructions conflict?

The closest AGENTS.md to the edited file wins, and your own chat prompt overrides everything. Codex combines files from the root down so later, closer files override earlier ones, and it checks AGENTS.override.md first in each directory. Conflicting guidance still wastes context, so remove duplicates.

5. Is AGENTS.md safe?

The file is safe when you wrote and reviewed it. The risk is a file you did not write. Agents trust the file in their folder, and Forever Security showed a planted AGENTS.md making Codex install malware in over 90% of test attempts. Review these files like code and never run agents in untrusted folders.

6. Does AGENTS.md improve agent results?

Not automatically. A study revised on September 29, 2026 found context files did not generally improve task success and raised inference cost by over 20% on average. They help most for non-standard practices, such as unusual build steps. Keep the file short and test whether it actually changes results.

7. How do I secure AGENTS.md in my team?

Put instruction and agent settings files under code-owner review, scan for hidden Unicode, and keep agents out of untrusted folders. Enforce safety rules with permissions, sandboxes and hooks instead of Markdown sentences. Route agent traffic through a gateway that scans inputs and logs tool calls, and rotate tokens if a planted file ran.

About the Author

Roger Howroyd is Head of Global SEO and AI at NeuralTrust, where he leads the company's search strategy across SEO, AEO, GEO, and LLM optimization. He specializes in AI-powered search, content strategy, and SEM. Connect on LinkedIn.

NeuralTrust is the leading platform for securing and scaling AI agents. Named a Pioneer in the Gartner Emerging Market Quadrant for AI Application Security 2026, recognized across four Gartner Hype Cycle reports in 2026, and featured in the Gartner Market Guide for Guardian Agents 2026, the Gartner Market Guide for AI Gateways 2025 and the KuppingerCole Leadership Compass for Generative AI Defense 2025. Headquartered in Barcelona with offices in London and New York. ISO 27001 certified.

Sources

Accessed on November 5, 2026.

1. AGENTS.md, "AGENTS.md: a simple, open format for guiding coding agents", 2026.
2. OpenAI, "Custom instructions with AGENTS.md", Codex documentation, 2026.
3. Anthropic, "How Claude remembers your project", Claude Code documentation, 2026.
4. Cursor, "Rules", Cursor documentation, 2026.
5. GitHub, "Adding repository custom instructions for GitHub Copilot", GitHub Docs, 2026.
6. Gloaguen et al., "Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?", arXiv, February 12, 2026 (v3 September 29, 2026).
7. GitHub Blog, "How to write a great agents.md: Lessons from over 2,500 repositories", November 19, 2025.
8. Forever Security, "Markdown Is the New Executable: Attackers Are Dropping Agent Instructions Into Your Downloads Folder From the Web", October 22, 2026.
9. Cloud Security Alliance, "Markdown Is the New Executable: Instruction-File Poisoning of AI Coding Agents", October 27, 2026.
10. The Hacker News, "Malicious File in Downloads Folder Tries to Trick AI Coding Agent Into Installing Malware", October 26, 2026.