Shared Types
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
- AGENTS.md
- packages/webapp/src/app/blog/format-specifications-guide/page.tsx
- packages/webapp/src/app/blog/copilot-deep-dive/page.tsx
- packages/cli/src/commands/init.ts
- packages/webapp/src/app/blog/openskills-cross-ide-compatibility/page.tsx
- packages/converters/schemas/README.md
agents.md is an open, tool-agnostic format for providing project-specific guidance to AI coding agents. Created through a collaboration involving major players like OpenAI and Google, it aims to standardize how developers communicate context and conventions to AI tools, moving away from a fragmented ecosystem of proprietary configuration files.
The core philosophy of agents.md is radical simplicity. It is designed to be a single, human-first markdown file with no required directory structure, special syntax, or custom extensions. This approach ensures that the instructions are easy to write, read, and maintain, while promoting interoperability and preventing vendor lock-in.
Sources: packages/webapp/src/app/blog/agents-md-deep-dive/page.tsx
Format Specification
The agents.md format is intentionally minimal, prioritizing flexibility and ease of use over a rigid structure.
Core Principles
- Single File: All instructions are contained within a single
AGENTS.mdfile. - Plain Markdown: The content is standard markdown, with no special syntax.
- Optional Metadata: While the base specification does not require frontmatter, PRPM's implementation can parse optional YAML frontmatter for additional context.
- Human-First: The file is designed to be as readable for humans as it is for machines.
- Tool-Agnostic: The format is not tied to any specific AI tool, enabling broad compatibility.
Sources: packages/webapp/src/app/blog/agents-md-deep-dive/page.tsx, packages/converters/src/tests/from-agents-md.test.ts
File Location and Precedence
The standard location for the agents.md file is the project root. However, some tools like OpenAI Codex extend this with a hierarchical system that merges instructions from different levels.
project-root/
├── AGENTS.md # Standard location for project-level guidance
├── src/
│ └── components/
│ └── AGENTS.md # Component-level guidance (merged with parents)
└── package.json
The diagram below illustrates the hierarchical loading and precedence system used by OpenAI Codex.
This diagram shows that more specific or overriding files take higher precedence.
Sources: packages/webapp/src/app/blog/agents-md-deep-dive/page.tsx
Recommended Structure
While agents.md has no required fields, the specification recommends several sections to provide comprehensive context to AI agents.
| Section | Purpose |
|---|---|
| Project Overview | High-level summary of the project's purpose and functionality. |
| Tech Stack | Key technologies, frameworks, and libraries used. |
| Development Setup | Instructions for setting up the local development environment. |
| Build & Test Commands | Specific CLI commands for building, testing, and linting the project. |
| Code Style Guidelines | Conventions for formatting, naming, and writing code. |
| Component Structure | Rules for organizing files and directories. |
| Testing Requirements | Guidelines for writing and running tests, including coverage goals. |
| Security Practices | Security-related considerations and rules. |
Sources: packages/webapp/src/app/blog/agents-md-deep-dive/page.tsx
Tool Compatibility
agents.md is the only format in the ecosystem designed from the ground up to work across multiple AI tools. This makes it the ideal choice for open-source projects and teams that use a variety of AI assistants.
Compatible Tools:
- OpenAI Codex
- GitHub Copilot (reads
agents.mdin addition to its own format) - Google Gemini Code Assist
- Any future tool that adopts the open standard.
The following table compares agents.md to other proprietary formats.
| Format | File Location | Structure | Cross-Tool Support |
|---|---|---|---|
| agents.md | AGENTS.md | Flexible markdown | ✅ Yes |
| Cursor | .cursor/rules/ | Plain text rules | ❌ No |
| GitHub Copilot | .github/copilot-instructions.md | Markdown with frontmatter | ⚠️ Partial |
| Claude | .claude/skills/*.md | Directory of skills | ❌ No |
| Continue | .continue/rules/*.md | Directory of rules | ❌ No |
| Windsurf | .windsurf/rules | Plain markdown | ❌ No |
Sources: packages/webapp/src/app/blog/agents-md-deep-dive/page.tsx, packages/webapp/src/app/blog/copilot-deep-dive/page.tsx, packages/webapp/src/app/blog/format-specifications-guide/page.tsx
PRPM Implementation
PRPM fully embraces the flexibility of agents.md and provides robust support for parsing, converting, and scaffolding packages in this format.
Parsing and Conversion
The fromAgentsMd converter in PRPM processes agents.md files with a set of smart inference capabilities.
The following diagram illustrates the parsing flow.
This process allows PRPM to create a structured, canonical representation from a flexible, unstructured source file.
Sources: packages/converters/src/tests/from-agents-md.test.ts
Scaffolding with prpm init
The prpm init command can scaffold a new agents.md package, including an example file to get started.
// packages/cli/src/commands/init.ts
const EXAMPLE_TEMPLATES: Record<string, Record<string, string>> = {
// ... other formats
"agents.md": {
"agents.md": `# Project Coding Guidelines
Project-specific instructions for AI coding agents (OpenAI Codex, etc.).
## TypeScript Conventions
- Use strict mode for type safety
- Prefer interfaces over types for object shapes
- Use const assertions where appropriate
## Testing Requirements
- Write tests for all public APIs
- Maintain >80% code coverage
- Use descriptive test names
## Code Examples
### Preferred: Async/Await
\`\`\`typescript
async function fetchData() {
const response = await fetch('/api/data');
return response.json();
}
\`\`\`
`,
},
// ... other formats
};
Sources: packages/cli/src/commands/init.ts
Universal Target for Composition
agents.md serves as a universal output format for tool composition workflows. For example, the Ruler tool can combine multiple markdown files from a .ruler/ directory into a single, comprehensive AGENTS.md file. This allows teams to manage different sets of instructions (e.g., for frontend, backend, testing) in separate files and automatically compile them into a format that is universally understood by various AI tools.
This diagram shows how Ruler composes multiple source files into a single AGENTS.md, which is then consumed by various AI IDEs.
Sources: packages/webapp/src/app/blog/openskills-cross-ide-compatibility/page.tsx
Best Practices
To get the most out of agents.md, follow these best practices:
- Be Specific and Actionable: Instead of vague rules like "write good tests," provide concrete instructions like "Write unit tests for all utility functions. Maintain > 80% coverage. Use Vitest."
- Complement README.md, Don't Duplicate:
README.mdis for humans (project setup, features).AGENTS.mdis for AI agents (coding patterns, technical constraints). - Update Regularly: Keep
AGENTS.mdsynchronized with your codebase as conventions evolve. - Organize by Concern: Group related guidelines under clear headings (e.g., Code Style, Testing, Security) to help AI agents find relevant information quickly.
Sources: packages/webapp/src/app/blog/agents-md-deep-dive/page.tsx
Real-World Example
The prpm repository itself uses an AGENTS.md file at its root. This file is automatically generated by the Ruler tool from several source markdown files located in the .ruler/ directory. This is a practical demonstration of the tool composition pattern.
<!-- Generated by Ruler -->
<!-- Source: .ruler/openskills.md -->
<skills_system priority="1">
## Available Skills
<!-- ... content from openskills.md ... -->
</skills_system>
<!-- Source: .ruler/prpm-development.md -->
<!-- Package: prpm-development -->
# Individual package
Use when developing PRPM (Prompt Package Manager) - comprehensive knowledge base...
## Mission
Build the npm/cargo/pip equivalent for AI development artifacts.
<!-- ... content from prpm-development.md ... -->
<!-- Source: .ruler/thoroughness.md -->
<!-- Package: thoroughness -->
# Thoroughness
Use when implementing complex multi-step tasks...
<!-- ... content from thoroughness.md ... -->
<!-- Source: .ruler/typescript-type-safety.md -->
<!-- Package: typescript-type-safety -->
# TypeScript Type Safety
Use when encountering TypeScript any types...
<!-- ... content from typescript-type-safety.md ... -->
This structure shows how different concerns—OpenSkills integration, PRPM-specific development guidelines, and general best practices—are managed in separate files and composed into a single, universally compatible AGENTS.md.
Sources: AGENTS.md
Conclusion
In a rapidly evolving and fragmented AI tooling landscape, agents.md provides a crucial foundation for interoperability. Its simplicity, flexibility, and tool-agnostic design make it a powerful standard for communicating project context to AI agents. By promoting portability and enabling tool composition, agents.md helps developers avoid vendor lock-in and build more robust, maintainable, and future-proof AI-assisted workflows.
Sources: packages/webapp/src/app/blog/agents-md-deep-dive/page.tsx