Instruction Blocks

Set up interactive instruction blocks with quick replies and skills so your AI agent knows when to act and what to offer customers.

Instruction blocks are the interactive parts of your AI agent's instructions. Each block bundles three things together:

When the block should apply — based on what the customer is asking or doing
What the agent should do — written guidance inside the block
What to offer next — quick reply buttons and/or skills the agent can run

Use them when a conversation needs more than a plain text answer — for example, offering "Track my order" and "Talk to someone" buttons when a customer asks about shipping, or running a booking skill when they ask to schedule a call.

Instruction blocks live on the Instructions tab when you edit an AI Persona (Intelligence → Agent). Save your changes, test in the playground, then deploy when you're happy.

Instruction blocks vs. plain instructions

Your agent's instructions can include regular text and instruction blocks. Both are valid — use the right tool for the job.

Use plain instructions for…	Use an instruction block for…
General tone and policies	A specific situation with a clear trigger
Rules that always apply	Clickable quick replies customers can tap
Background guidance	Running a particular skill when the moment is right

Plain text outside a block still shapes how your agent behaves. Instruction blocks add matching (so the right scenario fires) and interactivity (buttons and skills).

Add an instruction block

Open Intelligence → Agent and select your AI Persona.
Go to the Instructions tab.
Add a block in either of these ways:
- Click Add instruction block in the toolbar.
- Type / in the editor and choose Instruction Block.

The block is inserted at your cursor (or at the end of the document if you used the slash menu). You cannot nest one instruction block inside another — keep each scenario in its own top-level block.

Use the document outline panel on the right to jump between blocks, headings, and quick replies as your instructions grow.

Parts of an instruction block

Every instruction block has four areas to configure.

1. When to run this block (description)

At the top of each block is the When to run this block line. This is the most important field — it tells your agent which customer situations should activate this block.

Click the line to edit it, then write a full sentence describing the situation in plain language:

Customer asks where their order is, when it will arrive, or for a tracking link.

The description is required. If you leave it blank, the block cannot be saved properly and matching will be unreliable.

For detailed guidance on writing descriptions — including how to avoid overlaps between blocks — see Writing Block Descriptions.

2. Example messages (optional)

Below the description you'll see two optional lists:

Positive examples (+ icon) — real customer messages that should trigger this block
Negative examples (ban icon) — messages that look similar but should not trigger this block

These sharpen matching when descriptions alone aren't enough. Add a few natural phrases from real conversations — the way customers actually write.

Limits: up to 20 positive and 20 negative examples per block. Keep each example short — one or two sentences at most.

3. Instructions

Inside the dashed Instructions box, write what you want the agent to do when this block matches. This is the same kind of guidance you'd give a teammate:

How to respond
What to ask next
What to avoid promising
When to hand off to a human

You can use headings, bullet lists, and numbered lists inside the box. Keep the guidance focused on this one scenario.

4. Quick replies and skills

This is what makes the block interactive.

Quick replies

Quick replies are tappable buttons your customers see beneath the agent's message — for example, "Track order", "Change address", or "Speak to a team member".

Add a quick reply:

Click inside the Instructions box.
Open the block's ⋯ menu and choose Insert Quick Reply, or
Type / and choose Button.

Each quick reply has two fields:

Field	What it is	Tips
Label	The text on the button — what the customer sees	Keep it short and action-oriented. Max 20 characters.
Payload	The value sent when the customer taps the button	Optional. Use it when the label alone isn't enough for the agent to understand the choice — for example, `track_order` vs. `cancel_order` when both labels are short. Max 100 characters.

When a customer taps a button, your agent receives the payload as context so it knows which option they picked — even if two buttons have similar labels.

Limits: up to 10 quick replies per instruction block.

A block needs at least one quick reply or one skill reference before it can offer interactive buttons to customers. Blocks with only a description and instructions still guide your agent's behavior, but they won't surface quick replies on their own.

Skill references

You can tie a block to one or more skills so the agent knows which action to run in that scenario — for example, checking order status or booking an appointment.

Add a skill reference:

Click inside the Instructions box.
Type @ and pick a skill from the list, or
Type / and choose Skill.

Referenced skills appear as badges in the editor. Hover over a badge to see what the skill does. If a badge shows as not installed, install the skill from Intelligence → Skill Sets before deploying.

When a block matches and its skill hasn't already run in that turn, the agent can run it automatically in the background and follow up with the result.

Quick replies from blocks vs. from skills

Buttons can come from two places. They look the same to customers, but you configure them differently:

Source	Where you set it up	When customers see it
Instruction-block quick replies	The block's Instructions box (⋯ → Insert Quick Reply, or `/` → Button)	When this block matches the conversation
Skill output buttons	The skill's definition in Skill Sets (or in the skill's handler `response.buttons`)	After the skill runs and returns them

Priority: If a skill already returned buttons in the same turn, those are shown as-is — the agent won't swap them for a different block's quick replies. Instruction-block buttons are used when no skill has offered buttons yet.

Use block quick replies for fixed choices tied to a scenario ("Track order", "Talk to someone"). Use skill buttons for follow-up actions that depend on what the skill found ("View invoice", "Reschedule").

How matching works (what you need to know)

You don't need to configure matching manually — but understanding the basics helps you write blocks that fire reliably.

Your agent reads the conversation and drafts a reply.
It compares the moment against your block descriptions and example messages.
When a block matches confidently, the agent can attach that block's quick replies and run any linked skills.
If nothing matches clearly, the agent sends its reply without those buttons — it won't guess.

That's why clear descriptions, distinct boundaries between blocks, and well-chosen example messages matter. Overlapping blocks or vague descriptions are the most common reason quick replies don't appear when you expect them.

Example: order tracking block

Here's a complete block for a common support scenario.

When to run this block:

Customer asks where their order is, when it will arrive, or for a tracking link.

Positive examples:

"Where is my package?"
"Has my order shipped yet?"
"Can I get a tracking number?"

Negative examples:

"I want a refund" (refunds, not tracking)
"How much does shipping cost?" (pricing, not tracking)

Instructions:

Ask for their order number if you don't have it. Once you have it, use the order lookup skill. Give a clear ETA. If the order hasn't shipped yet, explain when it will and offer to notify them.

Quick replies:

Label	Payload
Track my order	`track_order`
Change delivery address	`change_address`
Talk to someone	`handover`

Skill reference: @shopify/get-order (or whatever order lookup skill you've installed)

Test this in the playground with messages like "where's my order?" and confirm the right buttons appear.

Tips for well-configured blocks

One scenario per block. Don't combine "cancel subscription" and "upgrade plan" in the same block — split them.
Write descriptions as situations, not labels. "Refunds" is too vague; "Customer asks for a refund or says they were charged incorrectly" is actionable.
Make quick reply labels customer-friendly. Write what they'd tap, not internal codes.
Use payloads for clarity. When two buttons could mean different things to the agent, give each a distinct payload.
Install skills before you reference them. A red badge in the editor means the skill isn't available yet.
Check for overlap. If two blocks keep firing on the wrong messages, tighten their descriptions or add negative examples.
Test before you deploy. The playground shows which block matched and whether quick replies were offered — use it after every significant change.

Troubleshooting

Quick replies never appear

Check these in order:

Does the block have at least one quick reply or skill? Blocks with instructions only won't offer buttons.
Is the description specific enough? Vague descriptions rarely match confidently.
Do two blocks overlap? The agent may skip both rather than pick the wrong one.
Did you deploy? Playground testing is safe, but customers only see deployed versions.

The wrong block keeps matching

Two descriptions are probably too similar. Open both blocks side by side, find a message that's matching the wrong one, and narrow the other block's description so it no longer applies. Add negative examples on the block that shouldn't fire.

A block never matches when it should

Rewrite the description as a full situational sentence.
Add positive examples using the exact phrases your customers send.
Compare against your other blocks — another block may be winning the match.

Writing Block Descriptions — Write descriptions and example messages that match reliably
AI Agent setup — Configure your AI Persona end to end
Skill Sets — Install and manage the skills your blocks can reference