Creating .prompt Files

Overview

This skill documents how to create .prompt files for LLM operations in Output SDK workflows. Prompt files use YAML frontmatter for configuration and Liquid.js templating for dynamic content.

When to Use This Skill

Creating prompts for LLM-powered workflow steps
Configuring LLM provider settings (model, temperature, etc.)
Using template variables in prompts
Troubleshooting prompt formatting issues

Location Convention

Prompt files are stored INSIDE the workflow folder:

src/workflows/{workflow-name}/
├── workflow.ts
├── steps.ts
├── types.ts
└── prompts/
    ├── analyzeContent@v1.prompt
    ├── generateSummary@v1.prompt
    └── extractData@v2.prompt

Important: Prompts are workflow-specific and live inside the workflow folder, NOT in a shared location.

File Naming Convention

{promptName}@v{version}.prompt

Examples:

generateImageIdeas@v1.prompt
analyzeContent@v1.prompt
summarizeText@v2.prompt

The version suffix (@v1, @v2) allows for prompt versioning without breaking existing code.

Basic Structure

---
provider: anthropic
model: claude-sonnet-4-20250514
temperature: 0.7
maxTokens: 4096
---

<system>
System instructions go here.
</system>

<user>
User message with {{ variable }} placeholders.
</user>

YAML Frontmatter Options

Required Fields

yaml

---
provider: anthropic    # LLM provider: anthropic, openai, google
model: claude-sonnet-4-20250514  # Model identifier
---

Optional Fields

yaml

---
provider: anthropic
model: claude-sonnet-4-20250514
temperature: 0.7       # 0.0 to 1.0, default varies by provider
maxTokens: 4096        # Maximum output tokens
providerOptions:       # Provider-specific options
  thinking:
    type: enabled
    budgetTokens: 2000
---

Common Provider Configurations

Anthropic (Claude)

yaml

---
provider: anthropic
model: claude-sonnet-4-20250514
temperature: 0.7
maxTokens: 8192
---

Anthropic with Extended Thinking

yaml

---
provider: anthropic
model: claude-sonnet-4-20250514
temperature: 0.7
maxTokens: 32000
providerOptions:
  thinking:
    type: enabled
    budgetTokens: 2000
---

OpenAI

yaml

---
provider: openai
model: gpt-4o
temperature: 0.7
maxTokens: 4096
---

Google (Gemini)

yaml

---
provider: google
model: gemini-1.5-pro
temperature: 0.7
maxTokens: 8192
---

Message Blocks

Use XML-style tags to define message roles:

System Message

<system>
You are an expert at analyzing technical content.
Your responses should be clear and structured.
</system>

User Message

<user>
Please analyze the following content:

{{ content }}
</user>

Assistant Message (for few-shot examples)

<assistant>
I'll analyze this content step by step...
</assistant>

Liquid.js Templating

Variable Substitution

<user>
Analyze this content about {{ topic }}:

{{ content }}

Generate {{ numberOfIdeas }} ideas.
</user>

Conditional Content

<system>
You are an expert content analyzer.

{% if colorPalette %}
**Color Palette Constraints:** {{ colorPalette }}
{% endif %}

{% if artDirection %}
**Art Direction Constraints:** {{ artDirection }}
{% endif %}
</system>

Loops

<user>
Analyze each of these items:

{% for item in items %}
- {{ item.name }}: {{ item.description }}
{% endfor %}
</user>

Default Values

<user>
Generate {{ numberOfIdeas | default: 3 }} ideas for {{ topic }}.
</user>

Complete Example

Based on a real prompt file (generateImageIdeas@v1.prompt):

---
provider: anthropic
model: claude-sonnet-4-20250514
temperature: 0.7
maxTokens: 32000
providerOptions:
  thinking:
    type: enabled
    budgetTokens: 2000
---

<system>
You are an expert at creating structured, precise infographic prompts optimized for Gemini's image generation model.

Your task is to generate prompts for informational infographics that illustrate key concepts from the provided content.

CRITICAL RULES you MUST follow:
- Use Markdown dashed lists to specify constraints
- Use ALL CAPS for "MUST" requirements to ensure strict adherence
- Include specific compositional constraints (e.g., rule of thirds, lighting)
- Always include negative constraints to prevent unwanted elements
- Keep each infographic focused on ONE clear concept

{% if colorPalette %}
**Color Palette Constraints:** {{ colorPalette }}
{% endif %}

{% if artDirection %}
**Art Direction Constraints:** {{ artDirection }}
{% endif %}
</system>

<user>
Generate {{ numberOfIdeas }} structured infographic prompts based on key topics from this content.

<content>
{{ content }}
</content>

Each prompt MUST follow this structure:

Create an infographic about [specific topic]. The infographic MUST follow ALL of these constraints:
- The infographic MUST use the reference images as a visual style guide
- The composition MUST follow the rule of thirds for visual balance
- The infographic MUST use clean, minimal design with simple lines and shapes
{% if colorPalette %}- The color palette MUST strictly follow: {{ colorPalette }}{% endif %}
{% if artDirection %}- The art direction MUST strictly follow: {{ artDirection }}{% endif %}
- NEVER include any watermarks, logos, or decorative overlays
- NEVER use generic AI art buzzwords like "hyperrealistic"

Focus on the most important concepts that would benefit from visual explanation.
</user>

Using Prompts in Steps

With generateObject

typescript

import { generateObject } from '@output.ai/llm';
import { z } from '@output.ai/core';

const { result } = await generateObject({
  prompt: 'generateImageIdeas@v1',  // References prompts/generateImageIdeas@v1.prompt
  variables: {
    content: 'Solar panel technology explained...',
    numberOfIdeas: 3,
    colorPalette: 'blue and green tones',
    artDirection: 'minimalist style'
  },
  schema: z.object({
    ideas: z.array(z.string())
  })
});
// result contains { ideas: [...] }

With generateText

typescript

import { generateText } from '@output.ai/llm';

const { result } = await generateText({
  prompt: 'summarize@v1',
  variables: {
    content: 'Long article text...',
    maxLength: 200
  }
});
// result contains the generated text string

Best Practices

1. Be Explicit About Requirements

<system>
CRITICAL RULES you MUST follow:
- Rule 1
- Rule 2
- NEVER do X
- ALWAYS do Y
</system>

2. Use XML Tags for Structure in User Messages

<user>
Analyze the following:

<content>
{{ content }}
</content>

<requirements>
{{ requirements }}
</requirements>
</user>

3. Provide Examples (Few-Shot)

<system>
You analyze sentiment. Return: positive, negative, or neutral.
</system>

<user>
"I love this product!"
</user>

<assistant>
positive
</assistant>

<user>
"{{ text }}"
</user>

4. Version Your Prompts

When making significant changes, create a new version:

analyzeContent@v1.prompt - Original
analyzeContent@v2.prompt - Improved with better examples

Update the step to use the new version:

typescript

prompt: 'analyzeContent@v2'  // Changed from v1

5. Handle Optional Variables

{% if optionalField %}
Additional context: {{ optionalField }}
{% endif %}

Common Patterns

Classification Prompt

---
provider: anthropic
model: claude-sonnet-4-20250514
temperature: 0.3
---

<system>
You are a content classifier. Categorize content into exactly one category.
Available categories: {{ categories | join: ", " }}
</system>

<user>
Classify this content:

{{ content }}
</user>

Extraction Prompt

---
provider: anthropic
model: claude-sonnet-4-20250514
temperature: 0.2
---

<system>
You extract structured data from text. Be precise and only include information explicitly stated.
</system>

<user>
Extract the following fields from this text:
{% for field in fields %}
- {{ field }}
{% endfor %}

Text:
{{ text }}
</user>

Generation Prompt

---
provider: anthropic
model: claude-sonnet-4-20250514
temperature: 0.8
---

<system>
You are a creative writer. Generate engaging content based on the given parameters.
</system>

<user>
Generate {{ count }} {{ type }} about {{ topic }}.

Requirements:
{{ requirements }}
</user>

Verification Checklist

File located in prompts/ folder inside workflow directory
File named {promptName}@v{version}.prompt
YAML frontmatter includes provider and model
Message blocks use proper XML tags (<system>, <user>, <assistant>)
Variables use {{ variableName }} syntax
Conditionals use {% if %}...{% endif %} syntax
All required variables are documented or have defaults
Step code references correct prompt name

Related Skills

output-dev-step-function - Using prompts in step functions
output-dev-folder-structure - Understanding prompts folder location
output-dev-workflow-function - Orchestrating LLM-powered steps

Search AI Tools

Install this agent skill to your Project

SKILL.md

Creating .prompt Files

Overview

When to Use This Skill

Location Convention

File Naming Convention

Basic Structure

YAML Frontmatter Options

Required Fields

Optional Fields

Common Provider Configurations

Anthropic (Claude)

Anthropic with Extended Thinking

OpenAI

Google (Gemini)

Message Blocks

System Message

User Message

Assistant Message (for few-shot examples)

Liquid.js Templating

Variable Substitution

Conditional Content

Loops

Default Values

Complete Example

Using Prompts in Steps

With generateObject

With generateText

Best Practices

1. Be Explicit About Requirements

2. Use XML Tags for Structure in User Messages

3. Provide Examples (Few-Shot)

4. Version Your Prompts

5. Handle Optional Variables

Common Patterns

Classification Prompt

Extraction Prompt

Generation Prompt

Verification Checklist

Related Skills