The landscape of AI-assisted development needs for standardized ways to communicate with AI coding agents.

What is AGENTS.md?

AGENTS.md is a simple, open format for guiding coding agents. Think of it as a README file, but for AI Models. Rather than introducing another proprietary file, we chose a name and format that could work across multiple AI development tools and platforms.

While READMEs are optimized for developers—covering project introductions, contribution guidelines, and quick starts; AGENTS.md serves as a predictable, structured location for agent-specific instructions. These include setup commands, testing workflows, coding style preferences, and pull request guidelines. Think of AGENTS.md as a README for agents: a dedicated, predictable place to provide context and instructions to help AI coding agents work on your project.

VSCode’s Agent Mode Updates

Microsoft introduced agent mode in February 2025 with VSCode version 1.98 as a preview feature, and made it available in VSCode Stable with version 1.99 (March 2025). The feature received significant enhancements in May 2025 (version 1.101) with full MCP (Model Context Protocol) support becoming available to all users, making VSCode one of the most powerful AI-assisted development environments available.

The latest VSCode agent mode includes several groundbreaking features:

  1. AGENTS.md Support (August 2025): Copilot coding agent now supports AGENTS.md custom instructions, allowing you to create a single AGENTS.md file in the root of your repository or nested files for specific parts of your project

  2. Prompt Files (January 2025): Prompt files allow you and your team to build, store, and share reusable prompts with pre-defined instructions and context for GitHub Copilot Chat and Copilot Edits

  3. Autonomous Context Detection: In agent mode, Copilot will iterate on not just its own output, but the result of that output, and it will iterate until it has completed all the subtasks required to complete your prompt

  4. GitHub Integration: Launch Copilot coding agent tasks from anywhere on GitHub - just describe your goal in natural language and select the relevant repository

Integration with Development Tools

The beauty of AGENTS.md lies in its universal compatibility. The format is designed to be portable across the growing ecosystem of AI-assisted development tools, including OpenAI’s Codex, Google’s Jules, Cursor, Aider, RooCode, and Zenith.

This standardization means you can write one AGENTS.md file and use it across multiple AI development tools, eliminating the need for tool-specific configuration files.

Note on copilot-instructions.md: For GitHub Copilot, you may also use a .github/copilot-instructions.md file. This file is specific to Copilot and is only recognized by Copilot agents, whereas AGENTS.md is designed as a universal, cross-tool standard. You can include Copilot-specific rules and instructions in copilot-instructions.md, and use AGENTS.md for guidance that applies to all AI coding agents and tools.

Best Practices for AGENTS.md

Based on community feedback and real-world usage:

  1. Keep it focused: Unlike READMEs, AGENTS.md should be laser-focused on actionable instructions for agents
  2. Be explicit: Agents work better with precise, unambiguous instructions
  3. Include examples: Provide code examples and command samples where possible
  4. Update regularly: Keep the file current with your project’s evolution
  5. Test with agents: Regularly test your AGENTS.md file with actual AI coding assistants

Want to learn more about AGENTS.md? Visit agents.md for the latest specifications and examples. For VSCode agent mode documentation, check out the official VSCode documentation.