GPT-5.5 prompting guide

2026-04-25 · Source: Simon Willison's Weblog · Field: Technology & Digital — Artificial Intelligence & Machine Learning, Software Development & Engineering · Depth: Intermediate, quick

Summary

OpenAI has released a prompting guide for its new GPT-5.5 model, now available via API. The guide includes a "neat trick" for multi-step tasks, recommending a short, user-visible update before tool calls to acknowledge the request and state the first step, improving user experience during longer processes. Additionally, OpenAI suggests using a Codex command, "$openai-docs migrate this project to gpt-5.5", to upgrade existing code, leveraging an embedded skill that includes prompt rewriting instructions. A separate "Using GPT-5.5 guide" advises treating GPT-5.5 as a new model family, recommending a fresh baseline for migration rather than porting old prompt stacks. It suggests starting with minimal prompts and then tuning reasoning, verbosity, tool descriptions, and output format.

Key takeaway

For AI Engineers migrating to GPT-5.5, you should avoid directly porting existing prompt stacks from older models. Instead, start with a minimal prompt that meets your product contract and iteratively tune its parameters. This approach will help you optimize GPT-5.5's performance and prevent issues arising from incompatible prompt designs, ensuring a smoother transition and better model utilization.

Key insights

GPT-5.5 requires fresh prompt engineering, not just porting old prompts.

Principles

• Acknowledge multi-step tasks early.
• Start GPT-5.5 migration with a fresh baseline.

Method

For GPT-5.5 migration, begin with the smallest prompt preserving product contract, then tune reasoning effort, verbosity, tool descriptions, and output format against representative examples.

In practice

• Use "$openai-docs migrate this project to gpt-5.5" in Codex.
• Send a short user-visible update for multi-step tasks.

Topics

• GPT-5.5
• Prompt Engineering
• OpenAI API
• Codex
• Model Migration

Code references

• openai/skills

Best for: Prompt Engineer, AI Engineer, Machine Learning Engineer

Related on AIssential

• OpenAI says old prompts are holding GPT-5.5 back and developers need a fresh baseline — GPT-5.5 performs best with minimal, outcome-focused prompts, requiring a fresh approach to prompt engineering.
• Migrating to GPT-5.x Without Breaking GPT-4: A Practical, Backward-Compatible Playbook — GPT-5.x's subtractive parameter changes necessitate a compatibility layer for seamless GPT-4 coexistence.
• OpenAI Quietly Told You to Throw Away Your Prompt Stack — Modern LLMs perform best when given clear outcomes, not prescriptive step-by-step instructions.
• You Might Want to Re-Learn Prompting... — ChatGPT 3.5 models perform better with outcome-first, shorter prompts that define the desired result.
• Introducing GPT-5.4 — GPT-5.4 enhances professional AI capabilities through integrated reasoning, coding, and agentic workflows with improved efficiency and safety.
• The Most Important GPT-5.5 Upgrade — GPT 5.5 excels at inferring user intent and personalizing responses by leveraging past conversational context.

Open in AIssential →

Editorial summary, takeaway, and curation by AIssential. Original article published by Simon Willison's Weblog.