Skip to Content

AGENTS.md: OpenAI's Tiny File Trying To Standardize Agentic Coding

Inside OpenAI's Evolving Open Format For Agent Instructions
openai

Every now and then, a small convention quietly moves an ecosystem forward. AGENTS.md, a single markdown file placed in a repo, aims to give coding agents consistent, project-specific guidance without bespoke integrations. 

Since my last analysis, the openai/agents.md repository has exploded with community activity: 4,378 stars, 313 forks, and a wave of tool integrations. Here's what the latest momentum tells us about the future of agentic coding.

What problem it solves

Agentic coding tools need context: how to run, lint, test, which frameworks and conventions to respect, and what to avoid. Historically, each tool invented its own format. That fragments developer workflows and makes instructions hard to share between tools and teams.

 AGENTS.md proposes a lowest-common-denominator: a human-readable, tool-agnostic file that agents can load automatically to guide behavior within a project.

What's new in the latest version

The repository now includes a much richer README.md with detailed development workflow examples, showing how teams can document everything from monorepo navigation to test patterns. 

The sample AGENTS.md has evolved to include practical guidance like using pnpm dlx turbo run where for package discovery and pnpm vitest run -t for focused testing. 

The project-local AGENTS.md now includes a comprehensive table of commands and emphasizes avoiding production builds during agent sessions.

Sample workflow guidance

This illustrates the evolved format showing real-world monorepo patterns and modern tooling.

# Sample AGENTS.md file

## Dev environment tips
- Use: pnpm dlx turbo run where <project_name> to jump to a package
- Run: pnpm install --filter <project_name> to add to workspace
- Create: pnpm create vite@latest <project_name> -- --template react-ts

## Testing instructions
- Find CI plan in .github/workflows folder
- Run: pnpm turbo run test --filter <project_name> for full checks
- Focus: pnpm vitest run -t "<test name>" for specific tests
- Always add tests for code changes, even if not requested

## PR instructions
- Title format: [<project_name>] <Title>
- Always run pnpm lint and pnpm test before committing

Why this resonates with developers

The format succeeds because it's deliberately constrained. By anchoring on a plain markdown file, AGENTS.md keeps human readability high and avoids locking developers into one tool's configuration grammar. 

The site documents compatibility with an expanding list of tools and IDEs, now including major players like GitHub Copilot, Android Studio, Warp, and Zed. That clarity helps the ecosystem coordinate without a heavyweight specification.

Under the hood: repo and tech details

The AGENTS.md website is built with Next.js and TypeScript, structured as a straightforward static site. The core application lives in pages/index.tsx, which composes the main sections from React components in the components directory

The development workflow documented in the local AGENTS.md reflects their philosophy, recommending the dev server for agent work while explicitly warning against production builds during agent sessions to maintain fast iteration cycles.

Community momentum and tool ecosystem

The real story is rapid adoption across the development tool ecosystem. The repository now shows explosive growth with 4,378 stars and 313 forks, along with active community engagement through 21 open issues and 8 pull requests. 

Recent integrations include official GitHub Copilot support (launched August 28, 2024) and Android Studio Agent Mode integration. Major development tools like Warp terminal and Semgrep have also been added to the compatibility list, showing broad industry adoption.

What makes this momentum particularly compelling is the standardization discussions happening in parallel. Issue #24 proposes RFC 2119 compliance for the specification language, ensuring consistent interpretation of requirements. 

Issue #33 discusses standardizing .agentignore files for unified ignore patterns across tools.

Issue #23 explores user-level configuration options, allowing developers to set global preferences while maintaining project-specific overrides. 

These initiatives suggest the community is moving beyond simple file adoption toward a comprehensive agent guidance standard.

Inside the repo, community proposals push the standard forward: a formal compliance definition using RFC 2119 language (Issue #24), a unified .agentignore to avoid tool-specific ignore files (Issue #33), directory-based modular rules (Issue #9), and frontmatter for triggers/globs (Issue #10). There is even housekeeping about keeping the "used by" count honest by using a stricter GitHub query (PR #30). It's a healthy signal: people care enough to refine the edges.

Use cases

Teams with multiple AI tools can centralize guidance in one place so editors and command-line agents behave consistently. Onboarding is faster: new contributors get reproducible "how to run" and "how to test" instructions the agent will follow. 

For larger codebases, pairing a root AGENTS.md with optional sub-project rules (if your tool supports directory traversal) gives you a gentle hierarchy without inventing a new DSL. And in regulated environments, AGENTS.md can capture guardrails like dependency policies or privacy guidance so automated edits stay inside the lines.

Impact on the agent ecosystem

Standardization here rhymes with prior wins like EditorConfig and LSP. A common rule file lowers switching costs between tools, improves portability of institutional knowledge, and clarifies what "project memory" means. It also complements the Model Context Protocol, which focuses on connecting apps to tools and data sources; AGENTS.md focuses on the local project instructions those agents should respect (Model Context Protocol, 2025). The net effect is less glue code and fewer bespoke settings when moving between Cursor, Zed, Copilot, Gemini CLI, or terminal-first agents.

Limitations and open questions

By design, AGENTS.md is minimal, which raises scope questions the community is actively debating: 

  • Should there be frontmatter for metadata, globs, or auto-apply behavior? 
  • Should we standardize imports among rule files? 
  • How should user-level rules (like ~/.agents.md) interact with repo rules? 

The issues linked above reflect a preference to keep v1 simple and layer optional enhancements later, so most tools can comply by just reading a file and treating it as guidance.

License and governance

The repository is MIT-licensed (LICENSE), which permits reuse and modification with attribution and warranty disclaimers. Several issues suggest moving stewardship to a neutral organization long term to keep the standard open and vendor-neutral (Issue #15).

About OpenAI

OpenAI maintains the project on GitHub and positions AGENTS.md as an open, lightweight convention rather than a proprietary format. You can explore the org's public work at github.com/openai.

Try it

Add an AGENTS.md at the root of your project with run, test, and style conventions; then enable it in your preferred editor or agent. If your tool needs a different filename, point it at the same content. The benefit compounds when your whole team (and your agents) align on one source of truth.

References and further reading

Repo files referenced: README.md, AGENTS.md, pages/index.tsx, components/, LICENSE.


Authors:
openai
AGENTS.md: OpenAI's Tiny File Trying To Standardize Agentic Coding
Joshua Berkowitz September 27, 2025
Views 3014
Share this post