Creating agents.md Files

Overview

The agents.md format provides project-specific context for AI coding assistants. It's the simplest format: plain markdown only with NO YAML frontmatter, NO special syntax.

CRITICAL:

• No frontmatter - Pure markdown only (no YAML)

• Free-form content - No required structure

• Single file - Typically agents.md in project root

Quick Reference

Aspect Requirement

Format Plain markdown

Frontmatter None (forbidden)

Structure Free-form

File location agents.md in project root

Creating agents.md Files

Plain markdown with no frontmatter:

TaskMaster Development Guide

Project Overview

TaskMaster is a task management application for remote teams, built with real-time collaboration features and offline-first architecture.

Architecture

Frontend

• React 18 with TypeScript
• Vite for build tooling
• Zustand for state management
• React Query for server state
• Tailwind CSS for styling

Backend

• Node.js with Express
• PostgreSQL with Prisma ORM
• WebSocket for real-time features
• Redis for caching and pub/sub
• JWT for authentication

Coding Conventions

• Use TypeScript strict mode
• Functional components with hooks (no class components)
• Server components by default in Next.js
• Colocate tests with source files (*.test.tsx)
• Use Zod for runtime validation

File Structure

``` src/ components/ # Reusable UI components features/ # Feature-based modules hooks/ # Custom React hooks lib/ # Utility functions pages/ # Route pages types/ # TypeScript types ```

Development Workflow

1. Create feature branch from main
2. Write tests first (TDD)
3. Implement feature
4. Run pnpm test and pnpm lint
5. Create PR with description
6. Merge after approval

Testing

• Use Vitest for unit tests
• Use Playwright for E2E tests
• Aim for 80% coverage on new code
• Mock external dependencies

What to Include

Focus on project-specific information AI doesn't already know:

High Priority:

• Project overview and purpose

• Architecture decisions and patterns

• Tech stack and dependencies

• File structure and organization

• Coding conventions

• Development workflow

• Testing approach

• Domain knowledge and business logic

Skip:

• General programming best practices

• Language syntax explanations

• Framework basics

• Obvious code quality rules

Example: Backend API Project

Payment Gateway API

Overview

RESTful API for payment processing with support for multiple payment providers.

Tech Stack

• Node.js 20.x
• Express
• PostgreSQL 15
• Redis for rate limiting
• Stripe and PayPal integrations

API Design

Endpoints

All endpoints follow REST conventions:

• GET /api/payments - List payments
• GET /api/payments/:id - Get payment details
• POST /api/payments - Create payment
• PUT /api/payments/:id - Update payment
• DELETE /api/payments/:id - Cancel payment

Error Handling

Return consistent error format:

```json { "error": { "code": "PAYMENT_FAILED", "message": "Payment could not be processed", "details": {...} } } ```

Security

• All endpoints require JWT authentication
• Rate limiting: 100 requests/minute per IP
• Input validation with Zod schemas
• SQL injection prevention via Prisma
• PCI DSS compliance for payment data

Database

Conventions

• Use snake_case for table/column names
• Add timestamps (created_at, updated_at) to all tables
• Use UUIDs for primary keys
• Foreign keys follow {table}_id pattern

Example: Frontend Component Library

Design System Components

A React component library following Atomic Design principles.

Component Structure

All components follow this structure:

``` ComponentName/ ComponentName.tsx # Main component ComponentName.test.tsx # Tests ComponentName.stories.tsx # Storybook stories index.ts # Exports ```

Styling

• Use Tailwind CSS utility classes
• Create custom classes in styles/components/ for complex components
• Follow BEM naming for custom classes
• Responsive by default (mobile-first)

TypeScript

```typescript // Good: Explicit prop types interface ButtonProps { variant: 'primary' | 'secondary' | 'ghost'; size?: 'sm' | 'md' | 'lg'; disabled?: boolean; onClick?: () => void; children: React.ReactNode; }

export function Button({ variant, size = 'md', ...props }: ButtonProps) { return <button className={cn(variants[variant], sizes[size])} {...props} />; } ```

Accessibility

• All interactive elements must be keyboard accessible
• Use semantic HTML (button, nav, main, etc.)
• Include ARIA labels for icon-only buttons
• Test with screen readers
• Maintain minimum 4.5:1 contrast ratio

Content Format

Free-form markdown including:

• Project overview: Purpose and goals

• Architecture notes: Technical decisions and patterns

• Conventions: Coding standards and practices

• Context: Domain knowledge and business logic

• Workflows: Development processes

• File structure: Directory organization

• Dependencies: Key libraries and tools

Common Mistakes

Mistake Fix

Adding YAML frontmatter No frontmatter allowed - plain markdown only

Generic best practices Focus on project-specific patterns

Verbose explanations Be concise, AI already knows general concepts

Language tutorials Skip basics, focus on project conventions

Missing context Include domain knowledge and business logic

Writing Style

Concise (Good):

Testing

• Vitest for unit tests
• Playwright for E2E
• 80% coverage target
• Mock external dependencies

Verbose (Bad):

Testing

When you are writing tests, it's important to understand that we use Vitest for our unit tests because it's fast and modern. For end-to-end testing, we have chosen to use Playwright because it provides excellent cross-browser support and has a great developer experience...

File Placement

Typically in project root:

project-root/ agents.md # Main file src/ tests/ package.json

Can also be in subdirectories for monorepos:

monorepo/ packages/ frontend/ agents.md # Frontend-specific context backend/ agents.md # Backend-specific context

Validation

Documentation: /Users/khaliqgant/Projects/prpm/app/packages/converters/docs/agents-md.md

Schema location: /Users/khaliqgant/Projects/prpm/app/packages/converters/schemas/agents-md.schema.json

Best Practices

• Be concise: Focus on project-specific info (AI knows general practices)

• Keep updated: Review and update as project evolves

• Real examples: Show actual code patterns from your project

• Plain markdown: No YAML frontmatter or special syntax

• Human-readable: Write for both AI and human developers

• Project-specific: Avoid generic advice that AI already knows

• Natural structure: Organize however makes sense for your project

Migration from Other Formats

When converting to agents.md:

• Strip all frontmatter - Remove YAML headers completely

• Focus on content - Keep only markdown content

• Combine files - Merge multiple rule files into one cohesive document

• Simplify - Remove format-specific features (globs, regex, etc.)

• Plain markdown only - Use standard markdown syntax

Official Specification

For the authoritative specification, see: https://github.com/openai/agents.md

Remember: agents.md uses plain markdown with NO frontmatter. Free-form structure. Focus on project-specific context AI doesn't already know.