output: Skill for Claude Code

Writing .prompt Files: ProviderOptions Guide

When creating .prompt files, understanding the providerOptions structure is critical.

Decision Tree: Where Does This Option Go?

Is the key on the prompt config allowlist (provider, model, temperature, maxOutputTokens, deprecated maxTokens, topP, topK, presencePenalty, frequencyPenalty, stopSequences, seed, maxSteps, skills, tools, providerOptions, messageOptions, n, maxImagesPerCall, size, aspectRatio)?
├─ YES -> Top-level config
└─ NO -> Nest under providerOptions (unknown top-level keys throw; snake_case aliases like max_output_tokens fail with a camelCase suggestion)

In providerOptions:
├─ Is it 'thinking' or 'order'? -> Top-level (special AI SDK features)
└─ Is it provider-specific? -> Nested under provider namespace

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.

Common Mistakes to Avoid

❌ Mistake 1: Putting provider options at top-level

provider: anthropic
effort: medium          # WRONG: 'effort' is not a standard option

✅ Correct:

provider: anthropic
providerOptions:
  anthropic:
    effort: medium

---

❌ Mistake 2: Nesting thinking under provider

providerOptions:
  anthropic:
    thinking:           # WRONG: thinking is top-level
      type: enabled

✅ Correct:

providerOptions:
  thinking:             # Correct: top-level special key
    type: enabled

---

❌ Mistake 3: Wrong namespace for Google Vertex Gemini

provider: google-vertex
model: gemini-2.0-flash
providerOptions:
  vertex:               # WRONG: Gemini uses 'google' namespace
    useSearchGrounding: true

✅ Correct:

provider: google-vertex
model: gemini-2.0-flash
providerOptions:
  google:               # Correct: Gemini is a Google model
    useSearchGrounding: true