Database Schema

Relevant source files

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

• packages/converters/schemas/README.md
• packages/converters/schemas/zed.schema.json
• packages/webapp/src/app/blog/agents-md-deep-dive/page.tsx
• packages/webapp/src/app/blog/json-schemas-for-ai-prompts/page.tsx
• packages/webapp/src/app/blog/format-specifications-guide/page.tsx
• packages/converters/src/tests/from-agents-md.test.ts
• packages/converters/src/tests/to-zed.test.ts
• packages/webapp/src/app/blog/copilot-deep-dive/page.tsx
• packages/webapp/src/app/blog/windsurf-deep-dive/page.tsx
• packages/webapp/src/app/blog/openskills-cross-ide-compatibility/page.tsx
• packages/webapp/src/app/blog/distributable-intelligence/page.tsx
• public-documentation/mint.json

# AI Prompt Formats

The PRPM ecosystem is built around the concept of "distributable intelligence," where rules, skills, and agents for AI coding assistants are packaged and shared. A core challenge in this ecosystem is the fragmentation of prompt formats across different AI tools. PRPM addresses this by supporting and converting between numerous formats, with agents.md positioned as a key open standard.

This document provides an overview of the various AI prompt formats supported by PRPM, their key characteristics, and how they are handled within the system. The primary mechanism for managing this complexity is through a system of format converters and JSON schemas, which provide validation, documentation, and a basis for reliable conversion.

Sources: packages/webapp/src/app/blog/distributable-intelligence/page.tsx, packages/webapp/src/app/blog/json-schemas-for-ai-prompts/page.tsx, packages/webapp/src/app/blog/format-specifications-guide/page.tsx

The agents.md Standard

agents.md is an open, tool-agnostic format for providing project-specific guidance to AI agents. It was created through a collaboration involving major players like OpenAI and Google to standardize how developers communicate context to AI coding tools.

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

Philosophy and Structure

The design philosophy of agents.md is "radical simplicity." It is a single, plain markdown file with no required directory structure, special syntax, or custom extensions. Frontmatter is entirely optional. This makes it human-first and universally compatible.

While there are no required fields, the specification recommends several sections to help AI agents understand a project:

• Project Overview
• Development Environment
• Build & Test Commands
• Code Style Guidelines
• Testing Instructions
• Contribution Guidelines
• Security Considerations

Sources: packages/webapp/src/app/blog/agents-md-deep-dive/page.tsx:34-36, 110-134

Tool Compatibility

agents.md is designed for cross-tool compatibility and is supported by:

• OpenAI Codex
• GitHub Copilot (in addition to its native format)
• Google Gemini Code Assist
• Any future tool that adopts the open standard.

This makes it the recommended format for teams using multiple AI tools or seeking to avoid vendor lock-in.

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

Hierarchical Extensions (OpenAI Codex)

OpenAI Codex extends the standard with a hierarchical file system, allowing for global, project-level, and override instructions.

1. ~/.codex/AGENTS.md: Global guidance for all projects.
2. AGENTS.md: Standard project-level guidance, which merges with parent directories.
3. AGENTS.override.md: A Codex-specific extension that replaces all parent instructions, useful for monorepos.

Sources: packages/webapp/src/app/blog/agents-md-deep-dive/page.tsx:78-100, 360-381

The following diagram illustrates the hierarchical loading mechanism in OpenAI Codex.

Format Fragmentation and PRPM's Role

The AI coding tool landscape is fragmented, with each tool often using its own proprietary format. This creates friction for developers and hinders interoperability.

Format	File Location	Structure	Cross-Tool Support
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
Zed	.rules	Plain markdown	⚠️ Partial (reads many formats)

Sources: packages/webapp/src/app/blog/agents-md-deep-dive/page.tsx:260-297, packages/converters/schemas/zed.schema.json:11-12, packages/webapp/src/app/blog/format-specifications-guide/page.tsx:112-167

PRPM acts as a universal translator, enabling developers to write instructions once and use them across different tools. This is achieved through a robust conversion system powered by JSON schemas.

Sources: packages/webapp/src/app/blog/distributable-intelligence/page.tsx:55-59, packages/webapp/src/app/blog/json-schemas-for-ai-prompts/page.tsx:90-98

JSON Schemas for Validation and Conversion

To manage the complexity of different formats, PRPM maintains comprehensive JSON schemas for over 15 formats and 29 subtypes. These schemas serve several critical functions:

• Validation: prpm publish and prpm convert use schemas to validate packages, catching errors before they are published or written to the filesystem.
• IDE IntelliSense: Developers can configure their IDEs (like VS Code) to use these schemas for autocomplete, inline documentation, and real-time validation of prompt files.
• Reliable Conversion: The schemas provide a precise, machine-readable definition of each format, which is essential for accurately converting between them.
• Living Documentation: Each schema contains descriptions, examples, and links to official documentation, serving as a source of truth for format specifications.

Sources: packages/webapp/src/app/blog/json-schemas-for-ai-prompts/page.tsx:40-54, 100-141, packages/converters/schemas/README.md:5-13

The following sequence diagram shows how schemas are used during the prpm publish process.

Overview of Other Key Formats

While agents.md is the open standard, PRPM provides first-class support for many tool-specific formats.

Windsurf

• Location: .windsurf/rules (single file)
• Structure: Plain markdown with no frontmatter.
• Key Constraint: Hard limit of 12,000 characters.
• Philosophy: Radical simplicity, zero configuration.

Sources: packages/webapp/src/app/blog/windsurf-deep-dive/page.tsx:28-32, 100-103

GitHub Copilot

• Location:
  • Repository-wide: .github/copilot-instructions.md
  • Path-specific: .github/instructions/*.instructions.md
• Structure: A two-tier system. The repository-wide file is plain markdown. Path-specific files use optional YAML frontmatter with an applyTo field for glob patterns.
• Key Feature: Also reads agents.md, CLAUDE.md, and GEMINI.md as alternative instruction sources.

Sources: packages/webapp/src/app/blog/copilot-deep-dive/page.tsx:64-70, 89-95, 126-133

Zed

• Location: .rules file.
• Structure: Plain markdown, no frontmatter required.
• Key Feature: Zed is designed for high compatibility and can read instructions from a prioritized list of files, including .cursorrules, .windsurfrules, .github/copilot-instructions.md, and AGENTS.md.

Sources: packages/converters/schemas/zed.schema.json:9-12, packages/converters/src/tests/to-zed.test.ts:208-211

The Compositional Approach

PRPM's strategy for handling the ever-growing number of formats is not just to add native support for everything, but to encourage composition of specialized tools. For example, instead of natively supporting the OpenSkills format, PRPM leverages a tool called Ruler.

1. OpenSkills generates content.
2. This content is placed in a .ruler/ directory.
3. Ruler automatically splices all markdown files from .ruler/ into a single, universal AGENTS.md file.
4. This AGENTS.md file is then compatible with any tool that supports the open standard.

This approach favors interoperability and loose coupling over monolithic, native integrations, making the ecosystem more resilient and scalable.

Sources: packages/webapp/src/app/blog/openskills-cross-ide-compatibility/page.tsx:40-52, 60-63

Summary

PRPM navigates the fragmented landscape of AI prompt formats by embracing the open agents.md standard while providing robust conversion and validation capabilities for numerous proprietary formats. This is powered by a comprehensive set of JSON schemas that ensure reliability and a good developer experience. By promoting both a universal standard and a compositional approach to tooling, PRPM aims to create a more unified and powerful ecosystem for AI-assisted development.

Sources: packages/webapp/src/app/blog/distributable-intelligence/page.tsx, packages/webapp/src/app/blog/json-schemas-for-ai-prompts/page.tsx