canned-prompts/CannedPromptFormat-v0.1.md

Canned Prompt Format v0.1

Status: Seed specification / experimental
Project: canned-prompts
Purpose: Portable packaging of reusable prompts and prompt templates.

1. Goals

The Canned Prompt Format (CPF) defines the smallest practical contract for a reusable prompt artifact.

A conforming package should be:

• human-readable;
• filesystem-portable;
• provider-neutral;
• inspectable before use;
• parameterizable where useful;
• versionable;
• extensible with examples, evals, dependencies, and provenance.

CPF v0.1 specifies the artifact format. It intentionally does not specify model execution, agent orchestration, dependency resolution, registry transport, or evaluation engines.

2. Package layout

The minimum valid package is:

my-prompt/
├── prompt.yaml
└── prompt.md

A richer package may contain:

my-prompt/
├── prompt.yaml
├── prompt.md
├── README.md
├── examples/
│   ├── basic.yaml
│   └── edge-case.yaml
├── evals/
│   └── quality.yaml
└── assets/
    └── rubric.md

Reserved paths

Path	Meaning
prompt.yaml	Required package manifest
prompt.md	Default prompt template unless overridden by template
README.md	Optional human documentation
examples/	Optional examples/fixtures
evals/	Optional evaluation specifications
assets/	Optional supporting text/data artifacts

Tools MUST ignore unknown non-reserved files unless a manifest field explicitly references them.

3. Manifest

The canonical manifest is UTF-8 YAML named prompt.yaml.

3.1 Minimal manifest

format: canned-prompt/v0.1
id: review/code-review
name: Code Review
version: 1.0.0
summary: Review a change for correctness and maintainability.
template: prompt.md

Required fields are:

• format
• id
• name
• version
• summary
• template

3.2 Package identity

format

MUST be exactly:

format: canned-prompt/v0.1

for this specification.

id

A stable, registry-independent logical identifier.

Recommended syntax:

<namespace>/<name>

Examples:

review/code-review
engineering/architecture-review
practice/pqrst-estimate

Rules for v0.1:

• lowercase ASCII is RECOMMENDED;
• /, -, _, and . MAY be used;
• whitespace MUST NOT be used;
• the ID MUST NOT contain .. path traversal segments;
• registry implementations MUST treat the ID as logical metadata rather than an unchecked filesystem path.

name

Human-readable display name.

version

A package version. Semantic Versioning (MAJOR.MINOR.PATCH) is RECOMMENDED and used by the reference implementation.

Behavior-changing edits SHOULD create a new version rather than overwrite a published package.

summary

A short description of the intended purpose. A consumer SHOULD be able to decide whether a package is potentially relevant from name + summary alone.

template

Relative path to the primary prompt template inside the package. The path MUST remain within the package directory.

4. Complete v0.1 manifest surface

format: canned-prompt/v0.1
id: review/code-review
name: Code Review
version: 1.2.0
summary: >
  Review a change for correctness, maintainability,
  security and test coverage.

type: template
template: prompt.md

inputs:
  - name: change
    type: content
    required: true
    description: The code, diff, or change to review.

  - name: repository_context
    type: content
    required: false
    description: Optional surrounding repository context.

parameters:
  depth:
    type: enum
    values: [quick, normal, thorough]
    default: normal
    description: Desired review depth.

  include_security:
    type: boolean
    default: true

output:
  format: markdown
  description: A structured review with findings and recommendations.

compatibility:
  capabilities:
    - code-analysis
  models: []
  providers: []

dependencies:
  prompts: []
  context: []
  capabilities: []

examples:
  - examples/basic.yaml

evals:
  - evals/review-quality.yaml

license: CC-BY-4.0

tags:
  - code-review
  - engineering

provenance:
  author: Example Author
  source: https://example.invalid/original
  derived_from: []

extensions: {}

All fields other than the required fields in section 3.1 are optional.

5. Prompt template syntax

CPF v0.1 uses deliberately small placeholder semantics:

{{ variable_name }}

A placeholder name MUST correspond to either:

• a declared input, or
• a declared parameter.

Whitespace immediately inside {{ and }} is insignificant.

Examples:

Review the following change at {{ depth }} depth.

{{ change }}

5.1 Rendering rules

1. Call-supplied values override defaults.
2. A declared parameter default is used when no call value is supplied.
3. A required input without a value is an error.
4. A placeholder with no resolved value is an error.
5. Values are substituted as text in v0.1.
6. Template evaluation MUST NOT execute arbitrary code.

CPF v0.1 does not define conditionals, loops, filters, or functions. Implementations MAY offer richer rendering modes only when explicitly declared by an extension; they MUST NOT silently reinterpret a v0.1 template as executable code.

6. Inputs

inputs is an optional ordered list.

inputs:
  - name: document
    type: content
    required: true
    description: Document to summarize.

Fields:

Field	Required	Meaning
name	yes	Placeholder/input identifier
type	no	Suggested semantic type; defaults to content
required	no	Whether a caller must supply it; defaults to false
description	no	Human-readable explanation

Recommended v0.1 input types are:

• content
• text
• url
• path
• json

These are descriptive hints in v0.1. A runtime MAY use them for validation or adapters.

7. Parameters

parameters is an optional mapping keyed by parameter name.

Supported descriptive parameter types:

• string
• integer
• number
• boolean
• enum

Example:

parameters:
  tone:
    type: enum
    values: [neutral, friendly, formal]
    default: neutral

  max_items:
    type: integer
    default: 10

A tool SHOULD validate enum values. Other type validation is RECOMMENDED but not mandatory for a minimal implementation.

8. Output contract

output describes the intended result, not an execution protocol.

output:
  format: markdown
  description: Concise structured findings.

Suggested format values include:

• text
• markdown
• json
• yaml
• xml
• code

Registries MAY index output format for discovery.

9. Compatibility

compatibility records known requirements or observations without binding the package to one runtime.

compatibility:
  capabilities:
    - code-analysis
    - long-context
  models:
    - example/model-family
  providers: []

Semantics:

• capabilities: abstract capabilities expected from the execution environment;
• models: model identifiers known to be compatible or evaluated;
• providers: provider identifiers when provider-specific behavior matters.

An empty list means "not constrained/unspecified", not "compatible with nothing".

10. Dependencies

Dependencies describe external artifacts or capabilities expected by the prompt.

dependencies:
  prompts:
    - id: context/repository-summary
      version: 1.0.0
      requirement: optional

  context:
    - id: policy/security
      requirement: required

  capabilities:
    - web-search

Recommended requirement values:

• required
• optional
• generate

generate means that a resolver MAY satisfy a missing dependency by invoking an appropriate generation process. CPF v0.1 does not define how generation or dependency resolution works.

This allows richer systems to integrate prompt resolution without forcing simple tools to implement an agent runtime.

11. Examples

examples is a list of relative paths.

An example file is not normative but SHOULD make intended usage obvious.

Suggested YAML shape:

name: basic review
values:
  change: |
    def add(a, b):
        return a + b
  depth: quick

Tools MAY render examples directly.

12. Evals

evals is a list of relative paths to evaluation specifications.

CPF v0.1 deliberately does not standardize a universal evaluation language. Eval files SHOULD therefore declare their own evaluator or schema.

Example:

schema: canned-prompts/eval-rubric/v0.1
name: code-review-quality
criteria:
  - identifies correctness risks
  - distinguishes blocking from advisory findings
  - avoids inventing repository facts

A registry may associate externally collected run/eval evidence with <id>@<version> without mutating the package.

13. Provenance and lineage

provenance:
  author: Ada Example
  source: https://example.invalid/source
  derived_from:
    - id: review/code-review
      version: 1.1.0

The field is descriptive in v0.1. Registries SHOULD preserve provenance when publishing or mirroring packages.

14. Licensing

A package MAY declare an SPDX license identifier or other clear license expression:

license: CC-BY-4.0

Absence of a license MUST NOT be interpreted as permission to redistribute or modify the package.

Tools SHOULD surface licensing metadata during publishing and installation.

15. Tags

tags:
  - architecture
  - review
  - agentic-coding

Tags are free-form discovery hints. Registries MAY normalize or enrich tags while preserving package metadata.

16. Extensions

extensions is the designated escape hatch for experimental or implementation-specific metadata.

extensions:
  org.example.canned-prompts:
    maturity: experimental

Extension keys SHOULD be namespaced to avoid collisions.

A consumer MUST ignore unknown extension entries unless it explicitly claims support for them.

17. Immutability and versioning

Published <id>@<version> pairs SHOULD be immutable.

A registry SHOULD reject publication of a package when the same ID/version already exists with different contents unless an explicit administrative override mechanism exists.

Suggested versioning guidance:

• PATCH: wording/metadata correction with intended behavior unchanged;
• MINOR: backward-compatible behavior or parameter additions;
• MAJOR: changed contract, renamed/removed inputs, or materially different intended behavior.

This guidance is intentionally advisory because prompt behavior is probabilistic and cannot be versioned as mechanically as an API.

18. Package validation

A v0.1 validator SHOULD verify at least:

1. prompt.yaml exists and parses as YAML;
2. required manifest fields exist;
3. format == canned-prompt/v0.1;
4. id is non-empty and contains no path traversal;
5. version is non-empty;
6. template resolves to a regular file inside the package;
7. referenced example/eval paths do not escape the package;
8. required inputs and parameter names are unique;
9. every template placeholder resolves to a declared input or parameter;
10. no required value is silently omitted during rendering.

19. Security requirements

Prompt packages are content, not trusted code.

Implementations MUST NOT:

• execute code merely because it appears in a package;
• treat template expressions as arbitrary code;
• interpolate environment variables or credentials implicitly;
• follow paths outside the package without explicit user action;
• embed or require secrets in published package metadata.

Implementations SHOULD:

• inspect all referenced paths for traversal;
• make package contents visible before execution;
• surface provenance and license metadata;
• treat remote content referenced by a package as untrusted input;
• separate package installation from model/tool authorization.

20. Registry model

CPF v0.1 does not mandate registry transport.

A valid registry may be:

• a filesystem directory;
• a Git repository;
• an object store;
• an HTTP service;
• a federated catalog.

Conceptually, a registry stores immutable package versions keyed by:

<id>@<version>

The reference implementation uses the filesystem layout:

registry/
└── <id path>/
    └── <version>/
        ├── prompt.yaml
        └── ...

For example:

registry/
└── practice/
    └── pqrst-estimate/
        └── 0.1.0/
            ├── prompt.yaml
            └── prompt.md

21. Reference CLI semantics

The v0.1 reference tool uses two stores:

• catalog — packages locally available for search/show/render;
• registry — packages available for publish/install.

Commands:

add PATH       validate and copy a package into the local catalog
search QUERY   search locally installed package metadata
show ID        display one installed package manifest
render ID      render an installed prompt with supplied values
publish PATH   validate and copy a package into a filesystem registry
install ID     copy a package version from the registry into the catalog

These semantics are illustrative, not mandatory for other implementations.

22. Worked example

prompt.yaml:

format: canned-prompt/v0.1
id: practice/pqrst-estimate
name: PQRST Estimate
version: 0.1.0
summary: Estimate how session effort was distributed across PQRST categories.
template: prompt.md

inputs:
  - name: session_summary
    type: content
    required: true

parameters:
  include_rationale:
    type: boolean
    default: true

output:
  format: markdown

tags: [retrospective, agentic-coding, pqrst]

prompt.md:

Review the following coding-session summary and estimate the distribution of
session effort across PQRST. Percentages must sum to 100%.

P = main problem
Q = quality and tests
R = research and context clarification
S = security and credentials
T = task organization

Session:

{{ session_summary }}

Include rationale: {{ include_rationale }}

23. Open questions for v0.2+

Experience should determine whether later revisions standardize:

• typed context/dependency contracts;
• content macros;
• prompt composition and inheritance;
• registry namespaces and ownership;
• cryptographic integrity/signing;
• canonical evaluation schemas;
• model capability vocabularies;
• run manifests and evidence formats;
• deterministic compilation manifests;
• trust/reputation signals;
• federated discovery;
• richer template syntax.

Until practical usage forces these decisions, v0.1 should remain intentionally small.