/pr-pm/prpm

Wiki directory

Browse AI-generated documentation for any repository.

Background Jobs and Cron Scheduler

Relevant source files

The following files were used as context for generating this wiki page:

Introduction

agents.md is an open, tool-agnostic format for providing project-specific guidance to AI coding agents. Created through a collaboration involving OpenAI, Google, and other major players, it aims to standardize how developers communicate context to AI tools, moving away from a fragmented ecosystem of proprietary configuration files.

The core philosophy of agents.md is radical simplicity. It is a single, plain markdown file with no required directory structure, special syntax, or custom extensions. This human-first, tool-agnostic approach ensures that the guidance is easy to write, read, and maintain, while being portable across any compatible AI tool.

Sources: packages/webapp/src/app/blog/agents-md-deep-dive/page.tsx:29-40

Core Specification

The agents.md specification is intentionally minimal to ensure broad compatibility and ease of use.

Attribute	Specification
File Location	`agents.md` at the project root. Some tools like OpenAI Codex support hierarchical placement.
Format	Plain Markdown. No special syntax or extensions are part of the core spec.
Frontmatter	Not required. The format is designed to be free of mandatory metadata.
Structure	Free-form. There are no required sections, allowing authors to organize content as they see fit.

Sources: packages/webapp/src/app/blog/agents-md-deep-dive/page.tsx:32-34, packages/webapp/src/app/blog/format-specifications-guide/page.tsx:501-512

Recommended Sections

While no sections are required, the specification recommends several to help AI agents effectively understand a project.

Section	Description
Project Overview	High-level summary of the project's purpose and goals.
Development Environment	Instructions for setting up the development environment and dependencies.
Build & Test Commands	Specific commands for building, testing, and running the project.
Code Style Guidelines	Conventions the AI should follow, such as naming, formatting, and patterns.
Testing Instructions	Guidance on how to write and run tests for the project.
Contribution Guidelines	Instructions for how to contribute code.
Security Considerations	Important security practices and potential vulnerabilities to be aware of.

Sources: packages/webapp/src/app/blog/agents-md-deep-dive/page.tsx:210-239

Real-World Example

This example for a TypeScript web application demonstrates how the recommended sections can be structured in a practical agents.md file.

# 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
Write component tests for interactive UI
Maintain >80% code coverage
Run tests before committing: npm test


*Sources: [packages/webapp/src/app/blog/agents-md-deep-dive/page.tsx:244-301](https://github.com/pr-pm/prpm/blob/HEAD/packages/webapp/src/app/blog/agents-md-deep-dive/page.tsx#L244-L301)*

## Tool Compatibility and Precedence

`agents.md` is the only format designed for cross-tool compatibility. This diagram illustrates its role as a universal standard.

Generating architecture diagram...

Sources: packages/webapp/src/app/blog/agents-md-deep-dive/page.tsx:50-80

OpenAI Codex: Hierarchical System

OpenAI Codex extends the standard with a hierarchical file system, allowing for global, project-level, and directory-specific guidance. It searches from the current directory upwards, merging instructions.

This diagram shows the lookup and precedence logic for Codex.

Generating architecture diagram...

AGENTS.override.md: A Codex-specific extension that replaces all parent instructions.
AGENTS.md: Standard file. Instructions are merged with those from parent directories.
~/.codex/AGENTS.md: Global guidance loaded for all projects.

Sources: packages/webapp/src/app/blog/agents-md-deep-dive/page.tsx:82-114, packages/webapp/src/app/blog/agents-md-deep-dive/page.tsx:516-541

GitHub Copilot: Dual Support

GitHub Copilot supports agents.md in addition to its own proprietary format, .github/copilot-instructions.md. When both files are present, their contents are read and merged. If conflicts arise, the Copilot-specific instructions typically take precedence.

Sources: packages/webapp/src/app/blog/agents-md-deep-dive/page.tsx:62-65, packages/webapp/src/app/blog/copilot-deep-dive/page.tsx:50-68, packages/webapp/src/app/blog/agents-md-deep-dive/page.tsx:543-556

PRPM Integration

PRPM treats agents.md as a first-class format, enabling its discovery, installation, and management. The PRPM parser for agents.md is designed for flexibility and unstructured content.

This diagram shows the parsing flow within PRPM.

Generating architecture diagram...

Sources: packages/converters/src/tests/from-agents-md.test.ts

Key Design Decisions

Optional Frontmatter: The parser respects the format's simplicity by not requiring frontmatter, but will parse it if present.
Auto-Description Extraction: If a description is not provided, it is automatically extracted from the first paragraph of the markdown content.
Section Type Inference: Semantic types (rules, examples, context) are inferred from section titles and content structure.
Auto-Tag Inference: Technology tags (e.g., typescript, testing) are automatically detected from the file's content to improve discoverability.

Sources: packages/webapp/src/app/blog/agents-md-deep-dive/page.tsx:143-164, packages/converters/src/tests/from-agents-md.test.ts:18-30, 191-240

JSON Schema

PRPM provides a formal JSON schema for the agents.md format, which is used for validation during publishing and conversion. Although the format is free-form, the schema helps ensure basic structural integrity and powers IDE integrations.

Sources: packages/webapp/src/app/blog/json-schemas-for-ai-prompts/page.tsx:497-520, packages/webapp/src/app/blog/format-specifications-guide/page.tsx:501-512

Format Comparison

The primary advantage of agents.md is its cross-tool compatibility, which sets it apart from proprietary, vendor-specific 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
Windsurf	`.windsurf/rules`	Plain markdown	❌ Windsurf only

Sources: packages/webapp/src/app/blog/agents-md-deep-dive/page.tsx:413-461, packages/webapp/src/app/blog/format-specifications-guide/page.tsx:100-161

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.md: Use README.md to explain the project to humans and agents.md to instruct AI agents on how to write code for the project.
Update Regularly: Keep the file in sync with your codebase and evolving conventions to prevent the AI from generating outdated code.
Organize by Concern: Group related guidelines under clear headings (e.g., "Testing Strategy," "Security") to help the AI quickly find relevant context.

Sources: packages/webapp/src/app/blog/agents-md-deep-dive/page.tsx:321-353

Conclusion

agents.md provides a simple, open standard for guiding AI coding assistants. Its tool-agnostic design promotes interoperability, prevents vendor lock-in, and allows developers to write guidance once and have it work across a growing ecosystem of AI tools. By prioritizing simplicity and portability, agents.md is positioned as a foundational format for the future of AI-assisted development.

Sources: packages/webapp/src/app/blog/agents-md-deep-dive/page.tsx:558-572

Background Jobs and Cron Scheduler

Relevant source files

The following files were used as context for generating this wiki page:

Introduction

Sources: packages/webapp/src/app/blog/agents-md-deep-dive/page.tsx:29-40

Core Specification

The agents.md specification is intentionally minimal to ensure broad compatibility and ease of use.

Attribute	Specification
File Location	`agents.md` at the project root. Some tools like OpenAI Codex support hierarchical placement.
Format	Plain Markdown. No special syntax or extensions are part of the core spec.
Frontmatter	Not required. The format is designed to be free of mandatory metadata.
Structure	Free-form. There are no required sections, allowing authors to organize content as they see fit.

Sources: packages/webapp/src/app/blog/agents-md-deep-dive/page.tsx:32-34, packages/webapp/src/app/blog/format-specifications-guide/page.tsx:501-512

Recommended Sections

While no sections are required, the specification recommends several to help AI agents effectively understand a project.

Section	Description
Project Overview	High-level summary of the project's purpose and goals.
Development Environment	Instructions for setting up the development environment and dependencies.
Build & Test Commands	Specific commands for building, testing, and running the project.
Code Style Guidelines	Conventions the AI should follow, such as naming, formatting, and patterns.
Testing Instructions	Guidance on how to write and run tests for the project.
Contribution Guidelines	Instructions for how to contribute code.
Security Considerations	Important security practices and potential vulnerabilities to be aware of.

Sources: packages/webapp/src/app/blog/agents-md-deep-dive/page.tsx:210-239

Real-World Example

This example for a TypeScript web application demonstrates how the recommended sections can be structured in a practical agents.md file.

# 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
Write component tests for interactive UI
Maintain >80% code coverage
Run tests before committing: npm test


*Sources: [packages/webapp/src/app/blog/agents-md-deep-dive/page.tsx:244-301](https://github.com/pr-pm/prpm/blob/HEAD/packages/webapp/src/app/blog/agents-md-deep-dive/page.tsx#L244-L301)*

## Tool Compatibility and Precedence

`agents.md` is the only format designed for cross-tool compatibility. This diagram illustrates its role as a universal standard.

Generating architecture diagram...

Sources: packages/webapp/src/app/blog/agents-md-deep-dive/page.tsx:50-80

OpenAI Codex: Hierarchical System

This diagram shows the lookup and precedence logic for Codex.

Generating architecture diagram...

AGENTS.override.md: A Codex-specific extension that replaces all parent instructions.
AGENTS.md: Standard file. Instructions are merged with those from parent directories.
~/.codex/AGENTS.md: Global guidance loaded for all projects.

Sources: packages/webapp/src/app/blog/agents-md-deep-dive/page.tsx:82-114, packages/webapp/src/app/blog/agents-md-deep-dive/page.tsx:516-541

GitHub Copilot: Dual Support

PRPM Integration

PRPM treats agents.md as a first-class format, enabling its discovery, installation, and management. The PRPM parser for agents.md is designed for flexibility and unstructured content.

This diagram shows the parsing flow within PRPM.

Generating architecture diagram...

Sources: packages/converters/src/tests/from-agents-md.test.ts

Key Design Decisions

Optional Frontmatter: The parser respects the format's simplicity by not requiring frontmatter, but will parse it if present.
Auto-Description Extraction: If a description is not provided, it is automatically extracted from the first paragraph of the markdown content.
Section Type Inference: Semantic types (rules, examples, context) are inferred from section titles and content structure.
Auto-Tag Inference: Technology tags (e.g., typescript, testing) are automatically detected from the file's content to improve discoverability.

Sources: packages/webapp/src/app/blog/agents-md-deep-dive/page.tsx:143-164, packages/converters/src/tests/from-agents-md.test.ts:18-30, 191-240

JSON Schema

Sources: packages/webapp/src/app/blog/json-schemas-for-ai-prompts/page.tsx:497-520, packages/webapp/src/app/blog/format-specifications-guide/page.tsx:501-512

Format Comparison

The primary advantage of agents.md is its cross-tool compatibility, which sets it apart from proprietary, vendor-specific 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
Windsurf	`.windsurf/rules`	Plain markdown	❌ Windsurf only

Sources: packages/webapp/src/app/blog/agents-md-deep-dive/page.tsx:413-461, packages/webapp/src/app/blog/format-specifications-guide/page.tsx:100-161

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.md: Use README.md to explain the project to humans and agents.md to instruct AI agents on how to write code for the project.
Update Regularly: Keep the file in sync with your codebase and evolving conventions to prevent the AI from generating outdated code.
Organize by Concern: Group related guidelines under clear headings (e.g., "Testing Strategy," "Security") to help the AI quickly find relevant context.

Sources: packages/webapp/src/app/blog/agents-md-deep-dive/page.tsx:321-353

Conclusion

Sources: packages/webapp/src/app/blog/agents-md-deep-dive/page.tsx:558-572