File Format Specification

Overview

Prompd files (.prmd) are structured prompt definitions that combine YAML frontmatter with Markdown content. They enable parameterized, versionable, and reusable AI prompts with inheritance and composition capabilities.

Key Features

• YAML Frontmatter: Structured metadata and parameters
• Markdown Content: Human-readable prompt template
• Parameter Substitution: Jinja2 templating with single braces ({parameter})
• Inheritance: Extend other templates via inherits field
• Package References: Import from registry packages
• Context Files: Include external data sources
• Validation: Built-in parameter type checking and constraints

File Structure

Every .prmd file follows this structure:

---
# YAML Frontmatter (required)
id: unique-prompt-identifier
name: "Human Readable Name"
version: 1.0.0
description: "Brief description of what this prompt does"
parameters:
  - name: parameter_name
    type: string
    required: true
# ... other metadata fields
---

# Markdown Content (optional if all content is in YAML fields)
Your prompt content with {parameter_name} substitution...

YAML Frontmatter

Required Fields

id (string, required)

Unique identifier for the prompt. Used for referencing and inheritance.

id: security-audit
id: code-review-comprehensive
id: data-analysis-pipeline

Rules:

• Must be unique within its scope
• Use kebab-case or snake_case
• No spaces or special characters except hyphens and underscores
• Maximum 64 characters

name (string, required)

Human-readable name for the prompt.

name: "Security Audit Template"
name: "Comprehensive Code Review"
name: "Data Analysis Pipeline"

Core Optional Fields

version (string)

Semantic version number (major.minor.patch).

version: "1.0.0"
version: "2.1.3"

description (string)

Brief description of the prompt’s purpose.

description: "Performs comprehensive security audit using OWASP standards"

author (string)

Author or organization name.

author: "@prompd.io"
author: "Security Team"

Parameters

The parameters array defines input variables for the prompt:

parameters:
  - name: application_name
    type: string
    required: true
    description: "Name of the application being analyzed"

  - name: audit_scope
    type: string
    enum: [basic, comprehensive, compliance]
    default: comprehensive
    description: "Scope of the audit to perform"

  - name: compliance_requirements
    type: array
    items:
      enum: [SOC2, PCI-DSS, HIPAA, GDPR, SOX]
    required: false
    description: "Specific compliance frameworks to evaluate"

  - name: confidence_threshold
    type: number
    minimum: 0.0
    maximum: 1.0
    default: 0.8
    description: "Minimum confidence level for findings"

Parameter Types

Type	Description
string	Plain text
number	Integer or float (generic numeric)
integer	Whole number only
float	Decimal number
boolean	true / false
array	JSON array with untyped elements
object	Plain key-value object (non-array)
json	Any JSON value — arrays of objects, nested structures, etc.
file	File path; caller supplies the file content as a string
base64	Base64-encoded binary (images, PDFs, blobs for multimodal LLMs)

String Parameters:

- name: input_text
  type: string
  required: true
  minLength: 10
  maxLength: 1000
  pattern: "^[a-zA-Z0-9\\s]+$"  # Regex validation

Number Parameters:

- name: temperature
  type: number
  minimum: 0.0
  maximum: 2.0
  default: 0.7

- name: max_tokens
  type: integer
  minimum: 1
  maximum: 4096
  default: 2000

Boolean Parameters:

- name: include_examples
  type: boolean
  default: true

Array Parameters:

- name: target_languages
  type: array
  items:
    type: string
    enum: [javascript, python, java, go, rust]
  minItems: 1
  maxItems: 5
  default: [javascript]

Object Parameters:

- name: model_config
  type: object
  properties:
    provider:
      type: string
      enum: [openai, anthropic, ollama]
    model:
      type: string
    temperature:
      type: number
  required: [provider, model]
  default:
    provider: openai
    model: gpt-4o
    temperature: 0.7

Float Parameters:

- name: price
  type: float
  minimum: 0.0
  default: 9.99
  description: "Price value requiring decimal precision"

JSON Parameters:

Use json when the parameter is structured data that doesn’t fit neatly into array (untyped list) or object (flat key-value map) — for example, arrays of objects, nested configurations, or evaluation criteria.

- name: evaluation_criteria
  type: json
  required: true
  description: "Array of evaluation objects, e.g. [{name, weight, description}]"

Apply the fromjson filter in the template when the value may arrive as a JSON string (e.g. from a --param flag). If the value is already a parsed object or array (e.g. loaded from a --param-file), the filter passes it through unchanged — so it is always safe to pipe through fromjson:

{% for criterion in evaluation_criteria | fromjson %}
- {criterion.name}: {criterion.weight}
{% endfor %}

File Parameters:

- name: source_file
  type: file
  required: true
  description: "Path to the source file. The caller resolves the path and supplies its content as a string. The CLI does not auto-read files."

Base64 Parameters:

- name: chart_image
  type: base64
  required: false
  description: "Base64-encoded image for multimodal analysis (PNG, PDF, etc.)"

Enum Parameters:

- name: output_format
  type: string
  enum: [markdown, json, xml, yaml]
  default: markdown

Inheritance

inherits (string)

Path to parent template to inherit from.

# Local file inheritance
inherits: "./base-security-audit.prmd"
inherits: "../templates/analysis-base.prmd"

# Package inheritance (must be quoted)
inherits: "@prompd.io/security-toolkit@1.0.0/prompts/base-audit.prmd"

See the full Inheritance System documentation for details.

override (object)

Section-based content overrides for inherited templates.

override:
  system-prompt: "./custom-system-prompt.md"
  examples: "./domain-specific-examples.md"
  legacy-section: null  # Remove section completely

Context and References

context (array)

External files to include as context.

context:
  - "./threat-model.md"
  - "../data/owasp-top-10.json"
  - "@prompd.io/security@1.0.0/contexts/security-checklist.md"

system (string)

System message or persona definition.

system: "You are a senior security engineer with 15+ years of experience"
system: "./personas/security-expert.md"

assistant (string)

Assistant personality or role definition.

assistant: "You are a helpful assistant specializing in code analysis"
assistant: "./roles/code-reviewer.md"

Advanced Fields

using (array)

Package dependencies with optional aliases.

using:
  - name: "@prompd.io/api-toolkit@1.2.1"
    prefix: "@api"
  - name: "@prompd.io/security-patterns@2.0.0"
    prefix: "@security"

tags (array)

Searchable tags for categorization.

tags: [security, audit, owasp, compliance]

Template Syntax

Prompd uses Jinja2 templating with single braces for variables:

Variable Substitution

{parameter_name}            # Simple substitution
{user.name}                 # Object property access
{items[0]}                  # Array access
{name|upper}                # Filter: converts to uppercase
{name|default('Anonymous')} # Default value if undefined

Conditionals

{% if condition %}
  Content when condition is true
{% elif other_condition %}
  Alternative content
{% else %}
  Default content
{% endif %}

Loops

{% for item in items %}
- {item}
{% endfor %}

{% for key, value in object.items() %}
- {key}: {value}
{% endfor %}

Filters

{name|upper}                # Convert to uppercase
{name|lower}                # Convert to lowercase
{name|title}                # Title Case
{description|truncate(100)} # Truncate to 100 characters
{price|round(2)}            # Round to 2 decimal places
{items|length}              # Get length of array/string
{text|escape}               # HTML escape
{data|fromjson}             # Parse a JSON string to a value; passes through unchanged if already parsed

fromjson pass-through behavior

fromjson converts a JSON string to a parsed value. If the parameter is already a parsed object or array (for example, when loaded via --param-file), the filter passes it through unchanged. It is always safe to pipe json-typed parameters through fromjson regardless of how the parameter was provided.

Validation Rules

File Validation

• File must have .prmd extension
• File must contain YAML frontmatter (between --- markers)
• YAML must be valid syntax
• Required fields must be present

Parameter Validation

• Parameter names must be valid identifiers
• Types must be one of the ten supported values: string, number, integer, float, boolean, array, object, json, file, base64
• integer validates that the value is a whole number (rejects floats); use number or float when decimals are acceptable
• Enum values must be arrays of strings
• Default values must match parameter type
• Required parameters cannot have null defaults

Common Validation Errors

# WRONG - Missing required quotes
inherits: @prompd.io/package@1.0.0

# CORRECT - Properly quoted
inherits: "@prompd.io/package@1.0.0/prompts/base.prmd"

# WRONG - Parameter type mismatch
parameters:
  - name: count
    type: number
    default: "not-a-number"

# CORRECT - Matching type
parameters:
  - name: count
    type: number
    default: 42

Best Practices

File Organization

project/
├── prompts/
│   ├── security/
│   │   ├── base-audit.prmd
│   │   └── api-security.prmd
│   └── generation/
│       └── documentation.prmd
├── contexts/
│   └── security-checklist.md
└── systems/
    └── security-expert.md

Naming Conventions

• Files: kebab-case.prmd (e.g., security-audit-comprehensive.prmd)
• IDs: kebab-case or snake_case (e.g., security_audit_v2)
• Parameters: snake_case (e.g., application_name, max_tokens)
• Template variables: {snake_case} (e.g., {application_name})

Parameter Design

• Use descriptive names and descriptions
• Provide sensible defaults where possible
• Use enums for limited choice parameters
• Validate input ranges and formats

Version Management

• Use semantic versioning (major.minor.patch)
• Increment major for breaking changes
• Increment minor for new features
• Increment patch for bug fixes