AGENTS.md: Guide, Risks and Security

AGENTS.md is an open Markdown-based instruction format that gives AI coding agents project-specific guidance on commands, testing, style, workflows, and boundaries, and is supported by tools including Codex, Cursor, GitHub Copilot, Gemini CLI, and, conditionally, Claude Code. The format is used by more than 60,000 open-source projects, but tools differ in how they discover, combine, prioritize, and limit instruction files, with nearby files generally taking precedence and explicit user prompts overriding repository guidance. Effective files are described as short, command-focused, and limited to conventions agents cannot infer or automated tools cannot enforce; research cited in the text found that broad context files do not generally improve task success and can increase inference costs by more than 20%. The central concern is security, because agents may treat untrusted instruction files as authoritative prompts: reported cases include a malicious AGENTS.md placed in a Downloads folder that led Codex to execute malware in over 90% of tests. Recommended safeguards include reviewing instruction and settings files like source code, avoiding untrusted directories, using code-owner review and hidden-character scans, monitoring agent configuration, rotating credentials after suspicious activity, and enforcing critical restrictions through permissions, sandboxes, hooks, and gateways rather than Markdown instructions alone.

Use this post, company, and trend context to find content marketing opportunities, perform competitive analysis, or address product feature gaps via the Plushcap MCP server or the Plushcap API.