What is AGENTS.md?
AGENTS.md has become the most practical upgrade you can make to any codebase in 2026 if you regularly use AI coding tools.
The idea behind AGENTS.md is that if AI makes use of your code proect it will understand exactly what the rules, style, test and other parameters and requirements are.
Apparently most developers who add it report noticeably fewer hallucinations and corrections needed within the first session.
In Short
Spend 8–12 minutes writing AGENTS.md today and every AI Agent that opens your repository will instantly understand exactly how you want code written, tested and reviewed — without you repeating instructions ever again.
Before AGENTS.md
I it my understanding taht before AGENTS.md, most popular AI coding tools each demanded their own configuration file:
Cursor → `.cursorrules`
Claude Code → `CLAUDE.md`
Gemini → `GEMINI.md` or `.gemini`
Copilot workspace → custom workspace instructions or `.github/copilot-instructions.md`
Continue → `.continue/config.json` snippets
So I guess there was a danger in maintaining four to six overlapping files in terms of creating duplication, version drift or general confusion.
New contributors or new tools had to hunt for the “real” rules. Instructions frequently became outdated → agent performance degraded over weeks.
What AGENTS.md Changed
In mid-2025 the community converged on one convention…
A single plain-Markdown file called AGENTS.md placed in the repository root.
Seemingly adoption accelerated because:
Cursor added native support
GitHub Copilot agent mode reads it automatically
Anthropic recommends it for Claude Code & Computer Use
Continue.dev, Aider, OpenHands and Windsurf default to looking for AGENTS.md first
Most other tools now fall back to it when their proprietary file is missing
AGENTS.md has no JSON schema, no YAML, no special syntax — just Markdown that humans and AI Agents can both read.
Typical Sections That Deliver the Biggest Contributions
Preferred language version and runtime
Exact dev, build, test and lint commands
Formatting, naming and typing conventions
Testing expectations (framework, coverage target, slow vs fast tests)
Pull request title / body template
Explicit boundaries (“never commit credentials”, “no telemetry”, “prefer async in this module”)
Project-specific warnings (“this legacy folder still uses callbacks”)
Does it work?
Public data I could find from late 2025 to January 2026 shows:
More than 60,000 repositories now contain AGENTS.md
Projects with a detailed AGENTS.md average 35–55 % fewer agent-generated bugs in community leaderboards. (This seems a big high…)
Teams switching to a single AGENTS.md report cutting setup time for new AI coding sessions from 20–40 minutes to under 2 minutes
As always, I don’t feel that I fully understand a technology until I have some low fidelity prototype running…
So below is a simple working example of a project that makes use of the xAI SDK, has an main AI Agent defined and written in Python.
And. then an AGENTS.md file that describes the AI Agent…
The file structure:
my-grok-project/
├── AGENTS.md
├── main.py
└── requirements.txtAGENTS.md file contents:
# AGENTS.md - Instructions for AI coding agents
You are working in a Python project that uses the official xAI SDK to interact with Grok models.
## Core Rules
- Always use `xai_sdk` (official package) — never use unofficial wrappers.
- Import like: `from xai_sdk import Client` and `from xai_sdk.chat import user, system`
- Load API key only via `os.getenv(”XAI_API_KEY”)`
- Prefer `grok-4` or `grok-4-1-fast-reasoning` models when possible.
## Code Style
- Use modern Python 3.10+
- Type hints on all functions
- Short functions, clear names
- Add docstrings for public functions
## Testing
- Use pytest
- Place tests in tests/
- Run: pytest
## When suggesting changes
- Output full file content when editing
- Use triple backticks with language specifier
- Explain reasoning before code
## Boundaries
- Never assume or hard-code API keys
- Never suggest pip install inside code
- Do not invent xAI API endpointsmain.py
import os
from xai_sdk import Client
from xai_sdk.chat import user, system
def main():
api_key = os.getenv(”XAI_API_KEY”)
if not api_key:
print(”Error: XAI_API_KEY environment variable not set”)
return
client = Client(api_key=api_key)
chat = client.chat.create(model=”grok-4”)
chat.append(system(”You are Grok, a helpful and truthful AI built by xAI.”))
chat.append(user(”Explain in one paragraph how AGENTS.md improves AI-assisted development.”))
response = chat.sample()
print(”Grok response:”)
print(response.content)
if __name__ == “__main__”:
main()requirements.txt file
xai-sdkpip install xai-sdk
Running the xAI AI Agent:
python main.py
And the output.
Grok response:
AGENTS.md serves as a centralized, comprehensive documentation file in AI development projects, outlining the architecture, functionalities, integration methods, and best practices for building and deploying autonomous AI agents. By providing clear, accessible guidelines—such as agent roles, decision-making algorithms, tool integrations, and error-handling strategies—it streamlines AI-assisted development, enabling developers to quickly onboard, collaborate, and iterate on complex systems without reinventing the wheel. This reduces debugging time, minimizes integration errors, fosters reusability across projects, and empowers teams to leverage AI agents for tasks like automation, data analysis, and decision support, ultimately accelerating innovation and improving overall efficiency in creating intelligent, scalable applications.
(gen) cobusgreyling@Cobuss-MacBook-Pro-2 xAI_Agent % 
Chief Evangelist @ Kore.ai | I’m passionate about exploring the intersection of AI and language. Language Models, AI Agents, Agentic Apps, Dev Frameworks & Data-Driven Tools shaping tomorrow.
Where AI Meets Language | Language Models, AI Agents, Agentic Applications, Development Frameworks & Data-Centric…www.cobusgreyling.com
GitHub - agentsmd/agents.md: AGENTS.md - a simple, open format for guiding coding agents
AGENTS.md - a simple, open format for guiding coding agents - agentsmd/agents.mdgithub.com