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.
A procedure — also called an instruction block — is one customer scenario handled end to end. Each one has two halves:
- When it applies — a description of the situation, plus optional example messages
- What happens then — one ordered list of instructions the agent works through
Use a procedure when a conversation needs more than a plain text answer — for example, asking for an order number, looking the order up with a skill, and then offering "Track my order" and "Talk to someone" buttons.
Because the instructions are one ordered list, a procedure can say when a skill runs and when buttons are offered, not just that they exist.
Procedures are created and edited on the Procedures tab when you edit an AI Persona (Intelligence → Agent). Save your changes, test in the playground, then deploy when you're happy.
Procedures vs. plain instructions
Your agent's instructions can include regular text and procedures. Both are valid — use the right tool for the job.
| Use plain instructions for… | Use a procedure 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 at a particular moment |
Plain text outside a procedure still shapes how your agent behaves. Procedures add matching (so the right scenario fires) and order (so things happen at the right point).
The two live on different tabs. The Instructions tab is for the general guidance; its editor shows only that. Underneath it, a line tells you how many procedures you have and links to the Procedures tab, which is where every procedure is written.
Add a procedure
- Open Intelligence → Agent and select your AI Persona.
- Go to the Procedures tab.
- Click Add procedure.
A new, empty procedure appears at the bottom of the list, opened on its first step. Fill it in top to bottom — that's the order your agent reads it.
To remove one, open its ⋯ menu and choose Delete procedure.
When the procedure applies
The description
The field at the top of the card is the most important one — it tells your agent which customer situations should activate this procedure.
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, matching will be unreliable.
For detailed guidance on writing descriptions — including how to avoid overlaps between procedures — see Writing Block Descriptions.
Example messages (optional)
Directly below the description are two optional lists. Each example you add becomes a chip:
- Positive examples (tick icon) — add a message that should trigger this
- Negative examples (ban icon) — add a message that should not trigger this
These sharpen matching when the description alone isn't enough. Add a few natural phrases from real conversations — the way customers actually write.
Limits: up to 20 examples per side. Keep each one short — one or two sentences at most.
The instructions
Below the examples, Instructions is one ordered list of everything the agent works through when this procedure runs. It goes through the list one position at a time instead of answering from general knowledge.
Add an entry with the Add button at the bottom, or press / in an empty step. Both open the same menu of five kinds:
| Kind | What it's for |
|---|---|
| Step | Something the AI does at this point |
| Decision | Take a different path per condition |
| Skill | Run one of your installed skills |
| Quick replies | Offer tappable options to the customer |
| Note | Guidance that applies throughout — not a step |
Ordering entries
Entries are numbered on a rail down the left. Only positions get a number — a Note doesn't, because it isn't a point in the flow.
Hover an entry, or tab into it, and its controls appear on the right:
- + — insert a new entry directly after this one
- Copy — duplicate it, in place
- ↑ and ↓ — move it up or down
- Bin — remove it
While you're typing a Step, pressing Enter commits it and opens the next one, so you can write a whole sequence without touching the mouse. Backspace in an entry that's already empty removes it and puts your cursor back in the one above.
Order is the point. A skill placed at 2 runs after the step at 1; quick replies placed at 4 are offered once the customer has an answer. Move them and the agent's behavior moves with them.
Step
A single instruction — Ask for the order number. It's the entry a new procedure starts on, and the one you'll use most.
Decision
A fork in the procedure. Each row reads If … then … — for example, If the order has shipped, then give the tracking link.
Click Add condition for another row, up to 5 in one decision. The Otherwise field at the bottom is optional; use it for what should happen when none of the conditions hold.
A decision counts as one position however many conditions it has — the agent makes one choice there.
Decisions are where references earn their keep: If the order has shipped is a description of a condition, while If Order status is shipped is one the agent can actually check.
Skill
Runs one of your organization's skills at this point in the procedure — checking an order, booking an appointment, looking something up.
Type @ and pick the skill from the list, then keep typing to say what to run it with or what to do with the result — it's all one sentence: @get-order using Order number, then confirm the address. Only skills your organization has installed are offered; if the list has none, install what you need from Intelligence → Skill Sets first.
An entry that names no skill is just a step, and saves as one.
You can also name a skill anywhere else — inside a decision arm, for instance (if it has shipped, then run @get-tracking). Wherever it appears, the agent gets that skill for the turn.
Quick replies
Tappable buttons your customers see beneath the agent's message — "Track order", "Change address", "Speak to a team member". They're offered at the point in the procedure where you put this entry.
Click + add reply and fill in two fields:
| Field | What it is | Tips |
|---|---|---|
| Label | The text on the button — what the customer sees | Keep it short and action-oriented. |
| Message | What comes back when the customer taps it | Starts out matching the label. Change it when the label alone isn't enough for the agent to tell the options apart — for example, track_order vs. cancel_order. |
Click Done and the reply collapses into a chip. Click a chip to edit it again, or the × on it to remove it. One entry holds up to 10 replies.
When a customer taps a button, your agent receives the message as context, so it knows which option they picked even if two labels look alike.
A procedure needs at least one Quick replies entry before it can offer buttons of its own. Procedures made only of steps, decisions, skills and notes still guide your agent — they just won't surface buttons.
Note
Guidance that holds for the whole procedure rather than at one point — never promise a delivery date you haven't checked, keep replies to two sentences. This is where the rules go, as opposed to the work.
Notes aren't numbered and don't count toward the step limit, so a procedure with a lot to say about how to behave doesn't get fewer things to do.
Referencing the conversation
Type @ anywhere in a step, a decision or a note to point at something the conversation itself holds. Pick from the list and it drops in as a chip:
| Group | What it refers to |
|---|---|
| Conversation fields | A custom field captured on this conversation — Order status, Budget |
| Contact fields | A custom field on the contact's record, carried between conversations — Company, Plan |
| Labels | Whether a label is on this conversation — VIP, At risk |
| Skills | One of your installed skills to run |
This is what turns a description of a condition into a condition your agent can actually check:
| Without a reference | With one |
|---|---|
| If the order has shipped, then give the tracking link | If Order status is shipped, then give the tracking link |
| If they're an important customer, then skip the queue | If VIP, then skip the queue |
When the procedure runs, your agent is told what this conversation currently holds — Order status (currently: shipped), VIP (applied) — and decides on that. Where a field has no value yet it's told so, and to ask rather than assume.
References use the field or label's name. Rename one and existing procedures keep reading correctly — they just stop checking a value until you repoint them. A chip whose field or label no longer exists turns red so you can spot it.
Limits
| Limit | Value |
|---|---|
| Numbered positions per procedure (steps, decisions, skills, quick replies) | 15 |
| Notes per procedure | 10 |
| Conditions in one decision | 5 |
| Replies in one Quick replies entry | 10 |
| Characters in a single field | 400 |
| Example messages per side | 20 |
A procedure with no positions still matches and still supplies its notes — it just has no checklist to follow.
Procedures you wrote earlier
Nothing to migrate by hand. A procedure written when instructions, steps, quick replies and skills were separate areas opens as one list: its old prose appears as notes at the top, then its steps, then its skills and quick replies at the end — because those three never had a position of their own.
Nothing is lost. Move them to where they belong in the flow and save.
Quick replies from procedures 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 |
|---|---|---|
| Procedure quick replies | A Quick replies entry in the procedure's Instructions | When this procedure matches, at the point you put the entry |
| 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 procedure's quick replies. Procedure buttons are used when no skill has offered buttons yet.
Use procedure 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 procedures that fire reliably.
- Your agent reads the conversation and drafts a reply.
- It compares the moment against your procedure descriptions and example messages.
- When a procedure matches confidently, the agent works through its instructions in order — running the skills and offering the quick replies where you placed them.
- If nothing matches clearly, the agent replies without them — it won't guess.
That's why clear descriptions, distinct boundaries between procedures, and well-chosen example messages matter. Overlapping procedures or vague descriptions are the most common reason quick replies don't appear when you expect them.
Example: an order tracking procedure
Here's a complete procedure for a common support scenario.
Description:
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:
| # | Kind | What it says |
|---|---|---|
| — | Note | Never promise a delivery date you haven't checked. |
| 1 | Step | Ask for the order number if you don't already have it. |
| 2 | Skill | @shopify/get-order — look the order up with the number they gave |
| 3 | Decision | If Order status is shipped, then give the tracking link. If it hasn't shipped, then give the expected ship date. Otherwise, hand over to a human agent. |
| 4 | Quick replies | Track my order → track_order, Change delivery address → change_address, Talk to someone → handover |
The decision at 3 checks the Order status field the skill at 2 filled in, rather than describing a condition and hoping the agent works it out. The skill sits at 2 because the agent needs the order number first. The buttons sit at 4 because they only make sense once the customer has an answer. Move that entry to 1 and the customer gets the buttons before anything has been looked up — which is exactly what you don't want.
The note has no number: it applies for the whole procedure, not at one point in it.
Test this in the playground with messages like "where's my order?". When a procedure fires, the playground takes you to the Procedures tab and highlights the card that ran.
Tips for well-configured procedures
- One scenario per procedure. Don't combine "cancel subscription" and "upgrade plan" — 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.
- Put each entry where it belongs. Ask yourself what the agent knows at that point — a skill that needs the order number can't run before you've asked for it.
- Notes for rules, steps for work. If it applies throughout, it's a note. If it happens at a moment, it's a position.
- Make quick reply labels customer-friendly. Write what they'd tap, not internal codes.
- Use the message field for clarity. When two buttons could mean different things to the agent, give each a distinct message.
- Install skills before you reference them. Only installed skills appear in the @ list.
- Decide on data, not on descriptions. Where a fact lives in a custom field or a label, reference it with @ — the agent can check a reference; it can only guess at a description.
- Check for overlap. If two procedures keep firing on the wrong messages, tighten their descriptions or add negative examples.
- Test before you deploy. The playground shows which procedure matched and whether quick replies were offered — use it after every significant change.
Troubleshooting
Quick replies never appear
Check these in order:
- Does the procedure have a Quick replies entry? Skills, steps and notes alone won't offer buttons.
- Is the description specific enough? Vague descriptions rarely match confidently.
- Do two procedures 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 procedure keeps matching
Two descriptions are probably too similar. Open both procedures side by side, find a message that's matching the wrong one, and narrow the other description so it no longer applies. Add negative examples to the procedure that shouldn't fire.
A procedure 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 procedures — another one may be winning the match.
The skill I want isn't in the list
Go to Intelligence → Skill Sets, install the skill set that contains it and configure any required settings, then return to the Procedures tab. It will appear in the @ list once it's available.
I can't add another entry
A procedure holds up to 15 numbered positions and up to 10 notes. The two are counted separately, so running out of steps doesn't stop you adding a note.
If you're at the limit, remove what you no longer need, or split the scenario into two procedures.
I can't add another quick reply
One Quick replies entry holds up to 10 replies. Across a whole procedure, only the first 10 replies you wrote are offered to customers — several entries that add up to more than ten will lose the extras.
Remove replies you no longer need, or split the scenario into two procedures.
What's next?
- 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 procedures can run