Prompt Template Guide

Prompt templates define the instructions sent to Gemini 2.5 Flash. Each template sits alongside agent manifests and can be versioned independently.

File Locations

• config/kiket/prompts/*.yml or .yml.erb – bundled templates.
• definitions/<template>/.kiket/prompts/*.yml – starter kits.
• storage/workflow_sources/<org>/<repo>/.kiket/prompts/*.yml – synced customer repositories.

Templates are resolved in that order. Duplicate id values raise an error.

Schema Overview

Key	Type	Notes
model_version	String	Use 1.0.
id	String	Matches the prompt value referenced by an agent manifest.
version	String	Semantic version for prompt rollout.
name / description	String (optional)	Human-friendly metadata.
model	String (optional)	Defaults to the platform standard (gemini-2.5-flash).
variables	Array\<String>	Snake_case variable names allowed in the body.
body	String	ERB template rendered before calling the model.
output_schema	Hash (optional)	Inline JSON schema describing response format.
output_schema_path	String (optional)	Relative or absolute path to a .json schema file.
metadata	Hash (optional)	Free-form settings (e.g. max_output_tokens).

If both output_schema and output_schema_path are set, the inline hash wins. Files ending in .yml.erb are processed through ERB prior to YAML parsing.

Rendering & Validation

The runtime enforces that every declared variable is supplied:

template = Prompts::PromptTemplate.load_file("config/kiket/prompts/triage.yml")
template.render(issue_title: "API 500", incident_summary: "...") # => String

Missing variables raise Prompts::PromptTemplate::MissingVariableError.

Schema validation happens after model execution, ensuring responses match the shape your workflows expect.

Linting

Run the shared AI lint command (via kiket ai lint or the admin automation runner) to validate manifests and prompts together. It verifies variable naming, schema integrity, and catches malformed ERB before you roll out changes.

Example Template

model_version: "1.0"
id: ai.prompts.triage
version: 1.0.0
name: Incident Triage Prompt
variables:
  - issue_title
  - incident_summary
  - recent_events
body: |-
  You are the on-call incident commander.
  Title: <%= issue_title %>
  Summary: <%= incident_summary %>

  Recent events:
  <%= recent_events %>

  Respond with JSON that matches the schema.
output_schema:
  type: object
  required: [severity, recommended_responder, escalation_needed]
  properties:
    severity:
      type: string
      enum: [critical, high, moderate, low]
    recommended_responder:
      type: string
    escalation_needed:
      type: boolean
metadata:
  max_output_tokens: 1024

Authoring Tips

• Keep prompts under 200 lines—if you need more, compose them with ERB partials or build tooling.
• Store reusable JSON schema files in config/kiket/prompts/schemas/.
• Bump version whenever you tweak instructions to help identify which prompt produced a response.