/output-dev-prompt-file

name: output-dev-prompt-file
description: Create .prompt files for LLM operations in Output SDK workflows. Use when designing prompts, configuring LLM providers, or using Liquid.js templating.
allowed-tools: [Read, Write, Edit]

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

> 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
maxOutputTokens: 4096
---

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

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

The body uses exactly one mode:

• **Message mode** starts with a role tag and produces `messages`. Use it with `generateText`, `generateTextWithStreaming`, `streamText`, and `Agent`.
• **Instruction mode** starts with plain text and produces `instructions`. Use it with `generateImage` or when consuming `loadPrompt()` results directly:

---
provider: openai
model: gpt-image-1
---

Create a cinematic image of {{ subject }}.

Leading whitespace and HTML comments do not affect mode selection. Once plain text selects instruction mode, later tag-shaped text remains part of the instructions.

YAML Frontmatter Options

Required Fields

---
provider: anthropic    # LLM provider: anthropic, openai, google-vertex, amazon-bedrock, azure, perplexity
# 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

---
provider: anthropic
# current as of 2026-05-04 - run output-dev-model-selection for the latest
model: claude-sonnet-4-6
temperature: 0.7       # Supported range and default vary by provider
maxOutputTokens: 4096  # Maximum output tokens
maxSteps: 5            # Tool-loop ceiling when tools or skills are present (default 10)
skills:                # Skill file or directory paths, relative to this prompt
  - ./skills
providerOptions:       # Provider-specific options
  thinking:
    type: enabled
    budgetTokens: 2000
---

Frontmatter is a **strict camelCase allowlist**. Unknown top-level keys throw `Invalid prompt file`. A snake_case alias of a known field fails with a suggestion (`max_output_tokens` -> use `maxOutputTokens`). Put provider-specific keys (`effort`, `reasoningEffort`) under `providerOptions`, which stays open. Nested `thinking` stays open too (`budgetTokens` is the documented key; extra nested keys are not rejected as unknown top-level config).

Allowed top-level keys: `provider`, `model`, `temperature`, `maxOutputTokens`, deprecated `maxTokens`, `topP`, `topK`, `presencePenalty`, `frequencyPenalty`, `stopSequences`, `seed`, `maxSteps`, `skills`, `tools`, `providerOptions`, `messageOptions`, `n`, `maxImagesPerCall`, `size`, `aspectRatio`.

Use `maxOutputTokens` for new prompts. Deprecated `maxTokens` remains on the loaded config and populates `maxOutputTokens` when the canonical key is absent; when both are set, `maxOutputTokens` takes precedence.

Call arguments: `prompt`, `promptDir`, `variables`, `tools`, `output`, `toolChoice`, `stopWhen`, `abortSignal` on `generateText` (plus `onChunk` on `generateTextWithStreaming`; plus `onChunk` / `onEnd` / `onError` on `streamText`). `generateImage`: `prompt`, `promptDir`, `variables`, `images`, `mask`, `abortSignal`.

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)

---
provider: anthropic
model: claude-sonnet-4-6
temperature: 0.7
maxOutputTokens: 8192
---

Anthropic with Extended Thinking

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

OpenAI

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

Google Vertex (Gemini)

---
provider: google-vertex
# current as o