Embedding Generation for AI Search
Relevant source files
The following files were used as context for generating this wiki page:
- packages/webapp/src/app/blog/agents-md-deep-dive/page.tsx
- packages/converters/src/tests/from-agents-md.test.ts
- packages/webapp/src/app/blog/format-specifications-guide/page.tsx
- packages/webapp/src/app/blog/copilot-deep-dive/page.tsx
- packages/webapp/src/app/blog/openskills-cross-ide-compatibility/page.tsx
- packages/webapp/src/app/blog/write-once-distribute-everywhere/page.tsx
- packages/webapp/src/app/blog/distributable-intelligence/page.tsx
agents.md is an open, tool-agnostic format for providing project-specific guidance to AI coding agents. Created through a collaboration involving OpenAI and Google, it aims to standardize how developers communicate project context, conventions, and constraints to AI tools, moving away from a fragmented ecosystem of proprietary formats. Its design philosophy is "radical simplicity," prioritizing a human-first, markdown-based approach that works across multiple platforms.
This standard provides a neutral ground that various AI tools can support, promoting interoperability and preventing vendor lock-in. For developers, this means writing guidance once and having it understood by any compatible tool. For open-source projects, it offers a way to welcome contributors using diverse AI assistants by providing a single, universal set of instructions.
Sources: packages/webapp/src/app/blog/agents-md-deep-dive/page.tsx
Design Philosophy
The core of agents.md is its simplicity. It is designed to be a single, plain markdown file with no special requirements.
- Single File: All guidance is contained within one
AGENTS.mdfile. - Plain Markdown: Uses standard markdown syntax without custom extensions.
- Optional Metadata: Frontmatter is not required but can be used for additional context.
- Human-First: The format is easily readable and writable by developers.
- Tool-Agnostic: Designed to work everywhere, not for a specific tool.
The format's power lies in what it doesn't require: no mandatory frontmatter, no specific section structure, and no special syntax.
Sources: packages/webapp/src/app/blog/agents-md-deep-dive/page.tsx
Format Specification
File Location and Structure
The agents.md file is typically placed at the project root. It is a standard markdown file with no required sections or structure, allowing authors to organize content as they see fit.
Sources: packages/webapp/src/app/blog/agents-md-deep-dive/page.tsx
Optional Frontmatter
While not required by the specification, agents.md can include YAML frontmatter for additional metadata. The PRPM parser specifically recognizes project and scope fields.
| Field | Type | Description |
|---|---|---|
project | string | An identifier for the project. |
scope | string | The specific area the guidance applies to (e.g., api, testing). |
Sources: packages/converters/src/tests/from-agents-md.test.ts:71-100
Recommended Content
Although the format is free-form, the specification recommends several sections to provide comprehensive guidance to AI agents.
| Section | Description |
|---|---|
| Project Overview | Explains what the project does and its purpose. |
| Development Environment | Provides setup instructions and lists dependencies. |
| Build & Test Commands | Lists specific commands for building and testing the project. |
| Code Style Guidelines | Details the coding conventions the AI should follow. |
| Testing Instructions | Explains how to write and run tests. |
| Contribution Guidelines | Outlines the process for contributing code. |
| Security Considerations | Describes security practices and potential concerns. |
Sources: packages/webapp/src/app/blog/agents-md-deep-dive/page.tsx
Real-World Example
The following is a practical example of an AGENTS.md file for a TypeScript web application.
# Project: TaskManager Web App
## Overview
This is a TypeScript-based task management application using React,
Next.js 14 (App Router), and PostgreSQL. The app allows teams to
create, assign, and track tasks with real-time updates.
## Tech Stack
- **Frontend**: React 18, Next.js 14, TailwindCSS
- **Backend**: Next.js API Routes, Prisma ORM
- **Database**: PostgreSQL 15
- **Testing**: Vitest, React Testing Library
- **Type Safety**: TypeScript strict mode
## Development Setup
```bash
npm install
cp .env.example .env.local
npm run db:migrate
npm run dev
Code Style Guidelines
- Use TypeScript strict mode for all files
- Prefer functional components with React hooks
- Use async/await over promise chains
- Follow the existing ESLint configuration
- Use Prettier for formatting (runs on pre-commit)
- Name files using kebab-case:
user-profile.tsx - Use named exports over default exports
Testing Requirements
- Write unit tests for all utility functions
- Write integration tests for API routes
- Maintain >80% code coverage
- Run tests before committing:
npm test
*Sources: [packages/webapp/src/app/blog/agents-md-deep-dive/page.tsx](https://github.com/pr-pm/prpm/blob/HEAD/packages/webapp/src/app/blog/agents-md-deep-dive/page.tsx)*
## Tool Support and Compatibility
`agents.md` is the only format designed for cross-tool compatibility, making it a portable standard.
*Sources: [packages/webapp/src/app/blog/agents-md-deep-dive/page.tsx](https://github.com/pr-pm/prpm/blob/HEAD/packages/webapp/src/app/blog/agents-md-deep-dive/page.tsx)*
### Compatible Tools
* **OpenAI Codex:** The foundational model that powers many AI coding tools.
* **GitHub Copilot:** Reads `agents.md` in addition to its native `.github/copilot-instructions.md`.
* **Google Gemini Code Assist:** Committed to supporting the open standard.
* **Any future tool** that adopts the standard.
*Sources: [packages/webapp/src/app/blog/agents-md-deep-dive/page.tsx](https://github.com/pr-pm/prpm/blob/HEAD/packages/webapp/src/app/blog/agents-md-deep-dive/page.tsx), [packages/webapp/src/app/blog/copilot-deep-dive/page.tsx](https://github.com/pr-pm/prpm/blob/HEAD/packages/webapp/src/app/blog/copilot-deep-dive/page.tsx)*
### OpenAI Codex: Hierarchical System
OpenAI Codex extends the standard with a hierarchical file system, allowing for global, project-level, and override instructions. It searches from the current directory upwards, merging instructions.
The diagram below shows the precedence of different `AGENTS.md` files in the Codex system.
Global Guidance:* ~/.codex/AGENTS.md is loaded for all projects.
- Standard Behavior:
AGENTS.mdfiles are merged with instructions from parent directories. - Override:
AGENTS.override.mdis a Codex-specific extension that replaces all parent instructions, which is useful in monorepos.
Sources: packages/webapp/src/app/blog/agents-md-deep-dive/page.tsx
Format Comparison
The following table compares agents.md with other proprietary formats.
| Format | File Location | Structure | Cross-Tool |
|---|---|---|---|
| agents.md | AGENTS.md | Flexible markdown | ✅ Yes |
| Cursor | .cursor/rules/ | Plain text rules | ❌ Cursor only |
| GitHub Copilot | .github/copilot-instructions.md | Markdown with frontmatter | ⚠️ Partial (also reads agents.md) |
| Claude | .claude/skills/*.md | Directory of skills | ❌ Claude only |
| Continue | .continue/rules/*.md | Directory of rules | ❌ Continue only |
| Windsurf | .windsurf/rules/ | Directory of rules | ❌ Windsurf only |
Sources: packages/webapp/src/app/blog/agents-md-deep-dive/page.tsx, packages/webapp/src/app/blog/format-specifications-guide/page.tsx
PRPM Integration
PRPM treats agents.md as a first-class format, providing tools for parsing, management, and conversion.
Sources: packages/webapp/src/app/blog/distributable-intelligence/page.tsx, packages/webapp/src/app/blog/write-once-distribute-everywhere/page.tsx
Parsing Logic (fromAgentsMd)
When processing an agents.md file, PRPM's fromAgentsMd converter performs several steps to create a structured representation.
This flowchart illustrates the parsing pipeline for an agents.md file within PRPM.
Optional Frontmatter:* It checks for and parses YAML frontmatter, looking for project and scope fields.
- Auto-Description Extraction: If no description is provided in metadata, it is automatically extracted from the first paragraph of the content.
- Section Type Inference: It infers semantic types for sections based on titles (e.g., "Examples", "Rules", "Background") or content structure. Sections that cannot be inferred default to the
instructionstype. - Auto-Tag Inference: It automatically detects and adds technology tags (e.g.,
typescript,testing,codex) based on the file's content.
Sources: packages/converters/src/tests/from-agents-md.test.ts, packages/webapp/src/app/blog/agents-md-deep-dive/page.tsx
Package Management and Conversion
PRPM enables the discovery, installation, and sharing of agents.md packages.
- Installation: Users can install packages with
prpm install <package-name>. - Publishing: Authors can publish their own
agents.mdfiles to the registry withprpm publish. - Cross-Format Conversion: PRPM can automatically convert
agents.mdpackages to other formats (like Cursor or Claude) during installation using the--asflag. This "write once, distribute everywhere" capability is a core feature of PRPM.
Sources: packages/webapp/src/app/blog/agents-md-deep-dive/page.tsx, packages/webapp/src/app/blog/write-once-distribute-everywhere/page.tsx, packages/webapp/src/app/blog/openskills-cross-ide-compatibility/page.tsx
Best Practices
To create effective agents.md files, follow these guidelines:
- Be Specific and Actionable: Avoid vague instructions like "Write clean code." Instead, provide concrete rules like "Use async/await over promise chains."
- Complement README, Don't Duplicate: Use
README.mdfor human-centric information (project features, installation) andAGENTS.mdfor AI-centric guidance (coding patterns, technical constraints). - Update Regularly: Keep the file in sync with your codebase to prevent AI from generating outdated code.
- Organize by Concern: Group related guidelines into logical sections (e.g., Code Style, Testing, Security) to help the AI find relevant information quickly.
Sources: packages/webapp/src/app/blog/agents-md-deep-dive/page.tsx
Conclusion
agents.md is a pivotal open standard aimed at unifying the fragmented AI coding assistant landscape. Its philosophy of simplicity and tool-agnosticism makes it a powerful format for developers and teams. By providing a universal method for communicating project-specific knowledge, it enables AI tools to compete on features rather than on proprietary format lock-in. PRPM fully embraces this standard, offering robust support for parsing, conversion, and package management, furthering the vision of a composable and interoperable AI development ecosystem.
Sources: packages/webapp/src/app/blog/agents-md-deep-dive/page.tsx, packages/webapp/src/app/blog/distributable-intelligence/page.tsx