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

1. Be concise: Focus on project-specific info (AI knows general practices)
2. Keep updated: Review and update as project evolves
3. Real examples: Show actual code patterns from your project
4. Plain markdown: No YAML frontmatter or special syntax
5. Human-readable: Write for both AI and human developers
6. Project-specific: Avoid generic advice that AI already knows
7. Natural structure: Organize however makes sense for your project

Migration from Other Formats

When converting to agents.md:

1. Strip all frontmatter - Remove YAML headers completely
2. Focus on content - Keep only markdown content
3. Combine files - Merge multiple rule files into one cohesive document
4. Simplify - Remove format-specific features (globs, regex, etc.)
5. 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.