Prompt Format Conversion Engine
Relevant source files
The following files were used as context for generating this wiki page:
- packages/converters/src/index.ts
- packages/converters/src/format-registry.ts
- packages/converters/src/types/canonical.ts
- packages/converters/schemas/canonical.schema.json
- packages/converters/README.md
- packages/webapp/src/app/blog/format-specifications-guide/page.tsx
- packages/webapp/src/app/blog/write-once-distribute-everywhere/page.tsx
- packages/converters/schemas/README.md
The Prompt Format Conversion Engine is the core component of PRPM that enables interoperability between different AI IDE prompt formats. Its primary purpose is to translate prompts from their native format (e.g., Cursor, Claude Code, Continue) into a universal internal representation, and then from that representation into any other supported target format. This system is what powers PRPM's "write once, distribute everywhere" philosophy, allowing package publishers to maintain a single source while users can install packages in the format compatible with their specific editor.
The engine is located in the @pr-pm/converters package and consists of format-specific parsers, generators, a validation system based on JSON schemas, and a universal CanonicalPackage data structure that serves as the intermediary for all conversions.
Sources: packages/converters/README.md, packages/webapp/src/app/blog/write-once-distribute-everywhere/page.tsx:29-35
Architecture
The conversion engine uses a hub-and-spoke architecture, with the CanonicalPackage format acting as the central hub. Each supported AI IDE format has a dedicated "from" converter (parser) that translates its native structure into the canonical format, and a "to" converter (generator) that translates the canonical format back into the native structure. This design avoids the need for a direct converter between every pair of formats, simplifying maintenance and scalability.
This diagram illustrates the hub-and-spoke model for format conversion.
This architecture ensures that to add a new format, only two converters (fromNewFormat and toNewFormat) need to be created.
Sources: packages/converters/README.md:29-37, packages/converters/src/index.ts
The Canonical Format
The canonical format is the universal, intermediary data structure used for all conversions. It is designed to capture the core instructional content and common metadata from various prompt formats, while providing a structured representation that can be losslessly transformed between formats where features overlap.
Sources: packages/webapp/src/app/blog/format-specifications-guide/page.tsx:320-324, packages/converters/src/types/canonical.ts
Data Structure
The CanonicalPackage interface is the primary data structure. It is defined in TypeScript and has a corresponding JSON schema for validation.
This class diagram shows the structure of the CanonicalPackage and its related types.
Key Fields
The following table details the main properties of the canonical.schema.json.
| Field | Type | Description |
|---|---|---|
name | string | The unique name of the package. |
version | string | The semantic version of the package. |
description | string | A brief description of the package's purpose. |
format | string | The original source format of the package (e.g., 'cursor', 'claude'). |
subtype | string | The subtype within the format (e.g., 'skill', 'agent', 'rule'). |
tags | array | An array of strings for categorization and search. |
files | array | An array of file paths included in the package. |
content | object | An object containing the structured prompt content, broken into sections. |
metadata | object | A key-value store for format-specific metadata that doesn't fit into the canonical structure (e.g., Claude's allowed-tools). |
Sources: packages/converters/schemas/canonical.schema.json:10-74
Conversion Process
The conversion process is a two-step flow: parsing from the source format to the canonical format, and then generating the target format from the canonical representation.
This sequence diagram shows the steps involved when a user installs a Cursor package for use in a Claude-compatible IDE.
This flow ensures that all transformations are validated against the canonical model, providing a consistent and reliable conversion pipeline.
Sources: packages/converters/README.md:12-27, packages/webapp/src/app/blog/write-once-distribute-everywhere/page.tsx:61-80
Supported Formats & Converters
The engine supports a wide range of AI IDE formats. For each format, there is a pair of converter functions.
| Format | "From" Converter | "To" Converter | Description |
|---|---|---|---|
cursor | fromCursor | toCursor | Cursor rules and commands. |
claude | fromClaude | toClaude | Claude Code agents, skills, and commands. |
continue | fromContinue | toContinue | Continue Dev rules and prompts. |
windsurf | fromWindsurf | toWindsurf | Windsurf rules (plain markdown). |
copilot | fromCopilot | toCopilot | GitHub Copilot repository and path-specific instructions. |
kiro | fromKiro | toKiro | Kiro steering files and hooks. |
agents-md | fromAgentsMd | toAgentsMd | The open agents.md standard. |
Sources: packages/converters/README.md:39-61, packages/converters/src/index.ts
Validation System
A critical part of the conversion engine is its validation system, which uses JSON Schemas to ensure format compliance. Validation occurs at multiple stages:
- Publish Time: When a package is published, its files are validated against the schema of its declared format.
- During Conversion: The output of a "to" converter is validated against the target format's schema to ensure the conversion was successful.
The schemas define required fields, data types, and other constraints for each format. This prevents malformed packages from entering the registry and ensures users receive valid files for their tools. The core validation functions are validateMarkdown and validateFormat.
Sources: packages/converters/README.md:63-91, packages/converters/schemas/README.md:5-11, packages/webapp/src/app/blog/json-schemas-for-ai-prompts/page.tsx:102-111
Quality Scoring & Lossy Conversions
Not all formats have the same features. For example, Claude Code supports allowed-tools restrictions, while Windsurf does not. The conversion engine accounts for these differences through a quality scoring mechanism.
The ConversionResult object returned by "to" converters includes:
qualityScore: A number from 0-100 indicating the fidelity of the conversion.lossyConversion: A boolean that istrueif format-specific information was lost.warnings: An array of strings detailing what information could not be translated.
This system provides transparency about the conversion process, informing users when a package's features may not be fully supported in the target format.
Sources: packages/converters/README.md:120-127, packages/webapp/src/app/blog/write-once-distribute-everywhere/page.tsx:107-120
Summary
The Prompt Format Conversion Engine is the technological foundation of PRPM's cross-platform compatibility. By using a hub-and-spoke architecture centered on a well-defined canonical format, it allows developers to create and share AI prompts without being locked into a single IDE's ecosystem. The integrated validation and quality scoring systems ensure that conversions are both reliable and transparent, fostering a more open and interconnected community for AI-assisted development.