output-dev-prompt-file

What this skill does

# 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/
    ├── [email protected]
    ├── [email protected]
    └── [email protected]
```

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

## File Naming Convention

```
{promptName}@v{version}.prompt
```

Examples:
- `[email protected]`
- `[email protected]`
- `[email protected]`

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

## Basic Structure

> Picking a model? See [`output-dev-model-selection`](../output-dev-model-selection/SKILL.md) for the current decision tree and AI Gateway lookup script. Examples below show concrete IDs as of 2026-05-04 — refresh them with that skill.

```
---
provider: anthropic
# current as of 2026-05-04 — run output-dev-model-selection for the latest
model: claude-sonnet-4-6
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, vertex
# current as of 2026-05-04 — run output-dev-model-selection for the latest
model: claude-sonnet-4-6
---
```

### Provider Consistency

All prompt files in a workflow should use the **same provider** unless the user explicitly requests otherwise. Mixing providers (e.g., some prompts using anthropic and others using openai) requires the user to have API keys for all providers, which causes runtime failures if they don't.

When no existing prompts dictate a provider, default to `anthropic`. For the model itself, see [`output-dev-model-selection`](../output-dev-model-selection/SKILL.md) — it walks priority (reasoning/balance/speed/cost), provider lookup, and produces a current model ID.

### Optional Fields

```yaml
---
provider: anthropic
# current as of 2026-05-04 — run output-dev-model-selection for the latest
model: claude-sonnet-4-6
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

> Each example below pins a model that was current as of 2026-05-04. Run [`output-dev-model-selection`](../output-dev-model-selection/SKILL.md) when picking or refreshing.

#### Anthropic (Claude)

```yaml
---
provider: anthropic
model: claude-sonnet-4-6
temperature: 0.7
maxTokens: 8192
---
```

#### Anthropic with Extended Thinking

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

#### OpenAI

```yaml
---
provider: openai
# current as of 2026-05-04 — run output-dev-model-selection for the latest
model: gpt-5-5
temperature: 0.7
maxTokens: 4096
---
```

#### Vertex (Gemini)

```yaml
---
provider: vertex
# current as of 2026-05-04 — run output-dev-model-selection for the latest
model: gemini-3-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 (`[email protected]`):

```
---
provider: anthropic
# current as of 2026-05-04 — run output-dev-model-selection for the latest
model: claude-sonnet-4-6
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>
```

## CRITICAL: Variable Type Constraint

The `variables` field in `generateText` and `Agent` only accepts **`string | number | boolean`** values. You cannot pass arrays or objects as variables -- TypeScript will reject them.

When your step has complex data (arrays, objects), pre-format it into a string before passing it as a variable:

```typescript
// WRONG - arrays/objects as variables cause TS2322
const { output } = await generateText( {
  prompt: 'rank@v1',
  variables: {
    stories: storyArray,       // Type error: not assignable to string | number | boolean
    interests: interestArray   // Type error: not assignable to string | number | boolean
  }
} );

// CORRECT - pre-format complex data into strings
const storiesText = stories.map( s =>
  `- ${s.title} (score: ${s.score}, by: ${s.author})`
).join( '\n' );
const interestsText = interests.join( ', ' );

const { output } = await generateText( {
  prompt: 'rank@v1',
  variables: {
    stories: storiesText,     // string - OK
    interests: interestsText  // string - OK
  }
} );
```

The prompt template then uses the pre-formatted string directly with `{{ stories }}` instead of Li