Instructions overview

Instructions are the foundational context, rules, and behavioral guidelines that shape how Opal creates output and tailors it to your unique needs. A simple form of instructions could have your company's brand guidelines, ensuring Opal generates on-brand content. Other common instructions include details about your company's products and services, target personas, user journey funnel, term-bases, and so on.

A key differentiator for Opal is its ability to dynamically pull and apply these instructions based on their When to use criteria. This ensures Opal always applies the most relevant and intelligently tailored guidelines, so Opal adapts its responses and actions precisely to the current context and your specific requirements.

For a visual walkthrough of instructions, watch the video overview. 

Components of an instruction

Each instruction contains the following components:

1. Name – Acts as a short, descriptive identifier for the instruction, aiding in easy recognition.
2. Active – Indicates whether the instruction is active in Opal and operational.
3. Core Instructions – Defines the instruction's behavior, including objectives, response formats, and any constraints. See Core instruction for information.
4. Where to use – Defines the Optimizely product and instance contexts where the instruction applies. If you do not set a Product and Instance, the instruction applies to all products. 
5. When to use – Defines the conditions that activate the instruction
   . See When to use for information.

Core instruction

Write the Core Instruction as you would write guidance for a new team member. Use the smart text editor with clear structure and complete details so Opal can execute tasks effectively. Detailed instructions reduce ambiguity and keep outputs consistent. To create a well-structured Core Instruction section, include the following:

• Objective or goal – Clearly state what the instruction achieves.
• Execution steps or process – Outline the step-by-step instructions Opal follows, including any prompts or questions for the user.
• Response format guidelines – Define how Opal formats its responses (for instance, tables or lists).
• Constraints or safety measures – Highlight any limitations or considerations Opal should observe.

When to use

Use the When to use section to specify the exact conditions that activate your instructions. You can base these on your intent, keywords, or phrases.

Apply the following techniques to write When to use conditions that activate accurately and consistently.

• Anchor your condition to a specific action or workflow – Vague intent-based descriptions give Opal too much room for interpretation and lead to false matches. Reference a specific workflow, tool, or product feature instead.
  • Before – When asked to help with marketing.
  • After – When asked to configure a marketing promotion campaign in the promotions manager.
  • Why it matters – Without a specific anchor, the instruction activates for unrelated prompts. Naming the tool or workflow sets a clear boundary.
• State keywords explicitly – If your instruction should only activate for a specific concept, name the keyword directly. This turns semantic matching into keyword matching, which is more precise for narrow use cases.
  • Before – When asked to help with creating, planning, or designing a marketing promotion.
  • After – ONLY use for the keyword "marketing promotion." Do NOT use for other keywords like sale, offer, or discount.
  • Why it matters – Semantic matching can link related concepts unexpectedly. A prompt such as Email subject for strawberries on sale can trigger a "marketing promotion" instruction because the relevancy model connects "sale" to "promotion." Explicit keywords prevent this.
• Add negative conditions to block false matches – Use Do NOT use for... to block related-but-wrong prompts. The relevancy model respects explicit exclusions.
  • Before – When asked about customer data.
  • After – When asked to export, segment, or analyze customer data in the CDP. Do NOT use for questions about individual customer support tickets or account settings.
  • Why it matters – Without exclusions, instructions activate for prompts that are topically related but contextually wrong. Exclusions give Opal a clear signal to stand down.
• List synonyms for narrow concepts – If users might phrase the same request in different ways, include alternative terms. This prevents the instruction from failing to activate because the user chose a different word.
  • Example – When asked about content scoring, content grades, or content quality scores.
  • Why it matters – An instruction scoped too narrowly — or written in jargon — fails to activate when it should. Listing synonyms and natural-language variants keeps coverage complete without broadening the scope.
• Draw clear boundaries between similar instructions – If you have multiple instructions covering related topics, make sure their When to use sections are distinct. Overlapping conditions cause both instructions to trigger at the same time and produce inconsistent or conflicting responses.
  • Before – Two instructions both use When the user asks about marketing, causing them to activate for the same prompts.
  • After – Separate the conditions so each instruction has a distinct scope:
    • Instruction A – Content creation: When the user asks to write, draft, or brainstorm marketing content such as email copy, social media posts, or ad text.
    • Instruction B – Campaign setup: When the user asks to create, schedule, or configure a marketing campaign or automation workflow. Do NOT use for writing content or copy.
  • Why it matters – Overlapping When to use conditions mean both instructions trigger on the same prompt. Explicit boundaries and mutual exclusions keep each instruction focused.

The following table outlines common scoping goals, the corresponding technique to apply in the When to use, and a practical example of each.

Instructions

Instructions tell Opal how to behave, shaping its tone, output format, and overall approach. There are the following two types of instructions:

• Instance instructions – Administrators set to enforce organization-wide standards.
• Personal instructions – Individual users set to match their own preferences and working style. 

Instance (organization-wide) instructions

Opal administrators can create, update, and delete instance instructions. These instructions enforce organization-wide policies, guidelines, brand standards, or platform behaviors. Examples include brand voice guidelines, approved content templates, compliance rules, or default behaviors for all teams. See Create an organization-wide instruction for information.

Examples of organization-wide instructions include the following:

• Brand voice – Always write in Optimizely's tone of voice: professional, direct, and action-oriented.
• Writing style rules – Specific grammar, vocabulary, and formatting standards (like a company style guide).
• Canvas behavior – Always use a canvas when creating persistent artifacts like briefs, reports, or blog posts.
• Approved tools – Use Chart.js for all data visualizations or Use Tailwind CSS for all HTML output.
• Content templates – When creating a campaign brief, follow the standard template.
• Compliance rules – Never include pricing information in generated content without a disclaimer.
• Presentation standards – All presentations must use reveal.js with a 16:9 aspect ratio.
• Image and media guidelines – Always use Optimizely's file server URLs when embedding images.

For information on administrator functions, see Get started with Optimizely Opal for administrators. 

Personal instructions

Opal users can create, update, and delete personal instructions. Personal instructions apply to you (the individual user). You can capture your explicit preferences, working style, or custom behaviors you want Opal to follow in your interactions. Examples of personal instructions include the following:

• Response format – Always respond in bullet points or Keep responses under 200 words.
• Tone preferences – Use a casual, conversational tone with me or Be more concise and skip the pleasantries.
• Role context – I am a developer, so always include code snippets when relevant.
• Language – Always respond in French.
• Output defaults – When creating documents, always use a canvas or Default to tables over bullet lists.
• Shortcuts –When I say 'quick summary,' give me a 3-bullet TL;DR.
• Expertise level – Assume I have advanced knowledge of A/B testing, skip the basics.
• Reminders – Always remind me to add a meta description when writing blog posts.

For information on user functions, see Get started with Optimizely Opal for users.

Prebuilt instructions

Optimizely provides prebuilt instructions in your Opal instance. You can use them immediately or update them to meet your organization's requirements. These instructions serve as a foundation to accelerate your implementation. 

Prebuilt instructions are turned off by default. You can turn them on by toggling Active to on. See the Activate the INSTRUCTION_NAME section in the following documentation:

• Campaign brief – Guides the creation of a comprehensive marketing campaign brief, detailing its purpose, objectives, target audience, key messages, deliverables, channels, and measurement strategies.
• Industry marketer – Adapts existing content from a given URL to a specified industry, customizing it with relevant terminology and examples.
• Keyword-Research – Generates an expert-level keyword research report using the Idealab Opal tools, providing insights into search volume, Cost Per Click (CPC), related keywords, and common questions to inform your Search Engine Optimization (SEO) strategy.
• Marketing planning meeting – Helps organize and facilitate marketing planning meetings by generating agendas, summarizing key discussion points, and outlining action items.
• Marketing researcher – Conducts in-depth research on a topic you specify providing comprehensive reports and marketing strategy suggestions.
• Personalization advisor – Helps you uncover, design, and measure high-value personalization opportunities.
• Task brief – Generates a structured and actionable brief for a specific task or deliverable, ensuring it aligns with your overall campaign goals, audience, and requirements.
• Tone of voice (sample) – Provides a comprehensive guide to maintaining a consistent brand voice across all content, focusing on professionalism, positivity, insightfulness, and approachability.
• Video transcription – Transcribes audio from a video, offering plain text or .srt formats and removing filler words.

Instruction samples

Not sure how to start writing instructions? The following sample instructions provide ready-made examples you can copy, customize, and use to create your own instructions. See the following samples:

• Sample boilerplate press release
• Sample competitor instruction
• Sample persona instruction
• Sample products and services instruction
• Sample tracked keyword instruction

How Opal selects which instructions to use

When you send a message, Opal decides which instructions are relevant before it generates a response. The following is what happens behind the scenes:

1. Opal gathers all active instructions – Opal collects all instructions available to you and filters out any that are deactivated.
2. Opal matches tool-based instructions first – If an instruction's When to use field references specific tools (for example, Tools: [generate_image]), Opal automatically selects it whenever those tools are available. Opal requires no further evaluation.

3. Opal evaluates remaining instructions for relevance – An AI model evaluates all non-tool instructions by reading the following:

   • Your latest message.
   • The conversation history.
   • The When to use field of each instruction.

   The model then decides which instructions are relevant to your conversation. See the following How the relevancy model works section for information.

4. Opal injects matched instructions into context – Opal adds selected instructions to the system prompt so it can follow them when generating a response

Opal uses only the When to use section to decide whether an instruction is relevant. Opal does not consider the instruction's title and body content during selection and includes them only after selecting an instruction.

How the relevancy model works

The AI model that evaluates instruction relevancy is designed to be inclusive rather than exclusive. The model includes a potentially relevant instruction rather than risk missing one that matters. This means the following:

• Broad or generic When to use descriptions match frequently. If your purpose is vague, the
  model errs on the side of including it. See When to use for best practices and examples.
• The model makes semantic connections. The model understands that "email subject for a sale" is conceptually related to "marketing promotion," even if those exact words do not display in your prompt.
• There is no scoring or ranking. Opal either selects each instruction or does not. There is no "70% match" partial inclusion.

This inclusive behavior is intentional. Missing a relevant instruction is worse than including an extra
one. Write your When to use section carefully to avoid unwanted activations. See When to use for best practices and examples.