Making Sense of AGENTS.md
You may have noticed a new convention is emerging in software repositories. Alongside README.md and .gitignore, projects are adding instruction files explicitly written for AI coding agents. The most common is AGENTS.md.
As coding agents become more capable and more widely used, they need context about how each project works, such as which commands to run and which directories to avoid. A README can explain quite a bit about how someone can meaningfully contribute, while the purpose of an AGENTS.md is to tell an AI agent how to operate while working on a project.
I’ve been exploring this space over the past few months, trying to understand what works, what doesn’t, and which kinds of conventions are worth adopting in my workflows. So far, I’m cautiously optimistic! The ecosystem is still fragmented (multiple file formats, inconsistent tool support, best practices still forming), but the pace of experimentation is remarkable.
I plan to share what I’ve learned so that others exploring this space can benefit from the patterns and issues I’ve encountered. This first post covers what AGENTS.md is and why it exists. I’ll follow up with posts on managing multiple instruction files among several tools, and on what changes when many agents work on a codebase at the same time.
A Notable Start to 2026
Six months ago, you could get away with ad-hoc instructions. An agent would figure things out, you could correct it as needed, and you’d muddle through. That approach stopped working around the start of this year.
Ethan Mollick observed that working with agents is fundamentally a management problem.
“When you see how people use Claude Code/Codex/etc it becomes clear that managing agents is really a management problem. Can you specify goals? Can you provide context? Can you divide up tasks? Can you give feedback?”
These are teachable skills that need a home. In the first few weeks of January 2026, several developments made me realize how quickly the ecosystem is maturing.
The Agentic AI Foundation launched under the Linux Foundation, with OpenAI donating AGENTS.md, Anthropic donating the MCP protocol, and Block donating Goose. The foundation’s platinum members include AWS, Google, Microsoft, Bloomberg, and Cloudflare. What started as an informal convention now has institutional backing from the same organization that shepherds Linux and Kubernetes. AGENTS.md has crossed 60,000 project adoptions.
Steve Yegge released Gas Town on New Year’s Day, an orchestrator for running twenty to thirty Claude Code instances in parallel. Yegge built the entire system through agents he directed but never programmed himself, producing thousands of lines of Go without writing any of it directly. Tim Sehn from DoltHub described the experience as “riding a wild stallion that needed to be tamed.” When you have that many agents touching your code at once, every one of them benefits from having clear details on how the project works.
GitHub Copilot CLI added specialized agents on January 14th that can run in parallel, including Explore, Task, Plan, and Code-review. Each handles a discrete workflow, and all of them read your AGENTS.md to understand project conventions.
Vercel released agent-skills, described as “npm for AI agents.” One command installs ten years of React and Next.js optimization patterns into your coding agent. The react-best-practices skill compiles 40+ rules into an AGENTS.md that agents can query during code review.
Experimentation is accelerating, with more people using agents across more repositories, and instruction files have become the interface between what you want and what agents do.
The Format in Practice
The following example is from the official spec repository and shows a Next.js project.
# AGENTS Guidelines for This Repository
This repository contains a Next.js application in the root directory.
## Use the Development Server
- Always use `npm run dev` while iterating
- Do not run `npm run build` during agent sessions
## Useful Commands
| Command | Purpose |
|---------|---------|
| `npm run dev` | Start the dev server with HMR |
| `npm run lint` | Run ESLint checks |
| `npm run test` | Execute the test suite |
The format is free-form Markdown with no required schema, so any agent that supports the standard can read it and adjust its behavior accordingly. The spec originated from OpenAI’s work on Codex, but they designed the format to be vendor-neutral. GitHub Copilot, Cursor, Gemini CLI, and VS Code’s agent mode all read it.
Effective vs. Ineffective Instructions
GitHub analyzed over 2,500 AGENTS.md files to understand what separates adequate instructions from ineffective ones.
“Most agent files fail because they’re too vague. ‘You are a helpful coding assistant’ doesn’t work.”
Successful agents function as specialists with defined roles, not general helpers.
Specific instructions outperform general ones. An instruction like “follow our coding standards” gives the agent nothing to work with. An instruction like “2-space indentation, no semicolons, see src/api/routes.ts:15-40 for the route handler pattern” gives it something concrete. One code reference beats paragraphs of abstract description because examples are unambiguous in a way that descriptions are not.
Commands should come early and be exact. Put your build and test commands near the top of the file, wrapped in backticks so the agent can copy them directly. Include flags and options, not just tool names. pytest -v --tb=short is more useful than “run pytest.”
Boundaries are the most valuable section. In GitHub’s dataset, “never commit secrets” was the single most common constraint, and also the most helpful. Agents respect boundaries when you state them explicitly because they have no way to infer your institutional context. They don’t know that vendor/ contains vendored dependencies you never modify, or that migrations are append-only by convention.
Keep it under 150 lines. Longer files mean more context for the agent to parse, which can dilute the important information. If you need more detail, use scoped files in subdirectories (I plan to cover this in a future post).
Repositories Worth Studying
The best way to understand what works is to look at instruction files from projects that use agents heavily.
Vercel’s React Best Practices AGENTS.md (mentioned earlier as part of agent-skills) organizes its rules across eight priority tiers, from critical patterns like eliminating data waterfalls down to micro-optimizations. This ranked structure helps the agent know what to fix first.
The official AGENTS.md spec repository (where the example earlier in this post came from) includes additional examples and an active discussion about the developing format.
For Claude-specific configurations, ChrisWiles/claude-code-showcase shows how to structure a project with CLAUDE.md, agent definitions, and custom commands. Awesome Claude Code collects more examples.
These Claude-specific files exist because AGENTS.md isn’t the only instruction file format. The ecosystem fragmented early.
The Current Ecosystem
Each tool introduced its own convention before a standard emerged, so you’ll encounter multiple file formats depending on which agents you use.
Repository-Level Instruction Files
AGENTS.md — Codex, Copilot, Jules, VS Code, Cursor, Gemini CLI. The emerging cross-tool standard.
CLAUDE.md — Claude Code. Anthropic’s format.
GEMINI.md — Gemini CLI. Google’s format.
.github/copilot-instructions.md — GitHub Copilot. GitHub’s original format.
Tool-Specific Configuration Directories
.cursor/rules/*.mdc — Cursor. Replaced the deprecated
.cursorrulesfile..windsurfrules — Windsurf. Codeium’s format (company rebranded to Windsurf).
.factory/droids/*.md — Factory. Droid-specific instructions.
WARP.md — Warp. Terminal agent rules.
Skills as a Separate Pattern
Beyond instruction files, some tools support portable “skills” that teach agents specific tasks. Vercel’s agent-skills (mentioned earlier) pioneered this approach. VS Code’s Agent Skills use SKILL.md files that work across GitHub Copilot CLI, VS Code, and the Copilot coding agent. The openskills project aims to make skills installable across any agent that reads AGENTS.md.
Management Tools
The fragmentation has spawned tools like ai-rulez (a CLI that generates synchronized instructions for multiple tools from a single YAML file) and ClaudeMDEditor (a GUI for managing configuration across Claude, Cursor, Copilot, and Windsurf).
The good news is that most tools now read AGENTS.md alongside their native formats. GitHub Copilot reads AGENTS.md, CLAUDE.md, and GEMINI.md. Cursor reads AGENTS.md too. The convergence is happening, just slowly.
I recommend starting with AGENTS.md as it has the broadest support and institutional backing. You can add tool-specific files later if you hit edge cases where a single file doesn’t quite capture what you need.
How I’m Approaching My Repositories
If you maintain a project and want to add an instruction file, here’s the approach I’ve been taking.
Start by cloning your repository from scratch. Walk through your README as if you were a new contributor. Write down every command you actually run. You’ll often find implicit knowledge you’ve accumulated but never documented, like setup steps you’ve internalized over time.
Write exact commands, not descriptions.
This is vague.
Run the tests before committing.
This is useful.
Run `pytest -v --tb=short` before committing. The `-v` flag shows individual test names (helpful for debugging), and `--tb=short` keeps failure output readable.
The second version works because the agent doesn’t have to guess. It can copy the command directly. The clarifying statement explains why those flags exist, which helps the agent make similar decisions in related situations.
Add one boundary based on the most common mistake you’ve seen. For me, that’s usually “don’t modify anything in vendor/“ or “migrations are append-only.” One boundary is enough to start. Add more as you observe what the agents actually get wrong in your specific codebase.
Point to one example file that demonstrates your patterns. Include the path and specific line numbers.
See `src/api/routes.ts:15-40` for the route handler pattern this project uses.
Line numbers give the agent something concrete to reference. Abstract descriptions like “follow our API conventions” don’t help because the agent has no way to know what those conventions are.
Treat it like code. An outdated instruction file is worse than having none at all because it actively misleads the agent. Update it within the same pull request that changes the workflow it describes.
Open Questions
I’m experimenting with how much context I should include. Too little, and the agent asks additional questions or makes wrong assumptions. Too much, and instructions get buried. The GitHub research suggests 150 lines as an upper bound, but I’ve found that the structure matters more than the length. Well-defined sections with obvious headings help the agents find what they need.
I’m also watching how different agents interpret similar instructions. Claude Code and GitHub Copilot sometimes behave differently given identical AGENTS.md files. I’m still evaluating whether tool-specific overlays are worth the added complexity.
Where Are Things Heading?
The AGENTS.md standard is gaining momentum, with 60,000 projects, institutional backing from the Linux Foundation, and most major tools now supporting the format. But the ecosystem is still messy in ways that matter.
Tool-specific files aren’t going away. Claude Code still has behaviors that benefit from CLAUDE.md. Cursor’s .mdc rules enable features that AGENTS.md doesn’t support. We’ll have multiple files for the foreseeable future, and the real question is whether their boundaries remain clear or create confusion.
The multi-agent case is where the real pressure will come. When Gas Town coordinates thirty agents against your codebase, ambiguity in your instruction files multiplies, and soft boundaries that worked well with a single agent can become race conditions with a swarm. The projects that figure this out first will have a considerable edge in how much work they can delegate.
I’m also watching skills as a pattern. Vercel’s agent-skills and the openskills project suggest a future in which you install curated rule sets the way you install npm packages, rather than writing all your instructions from scratch. Whether that leads to better agents or just more abstraction for debugging remains to be seen, but I’m excited to keep exploring.
If you found this helpful, subscribe to follow along while I keep investigating this space.