steps: list inside a :::ordered_block id=<id> fence in
skill.md. The block has no description. Routing lists the skill id and the
skill description. This page lists every step kind. When to use a block, and
the one-entry rule for a fully guided skill, are in
Ordered Blocks.
Step kinds
The kind is inferred from which key the step carries.Step fields
A
collect: step names its question with utterance:; an utter: step
names the response to deliver with utter:. Don’t confuse this with the
skill frontmatter utter: list, which fires verbatim responses on skill
activation or when a memory condition first becomes true, with no ordered
block. See skill.md → utter.Once a
collect: utterance has been delivered in the current run, the engine
asks that response again, including its buttons (if configured), when a turn
would otherwise leave the collect open after a message that was not its
answer: after the model answers a side question in its own words, and after a
return from another skill. A return counts once the model has handled the
message that left the collect, or when the user taps a button on the resume
question. rephrase: true can still change the wording; the buttons belong to
this new ask. A tap on buttons from the earlier ask does not write the field.The question is not repeated when the user’s message arrives before the ask
was delivered, when that same turn writes the field, or when a typed return
from another skill happens before the model has handled the message that left
the collect. A skill already queued under this collect is the exception: the
engine still asks, including before the first delivery. A collect with no
utterance leaves the question to the model.Two collect steps may fill the same field. The later step wins. A blank or
whitespace description on that later step drops an earlier collect-step
description, and the memory-field description is what the model sees. When the
winning collect description has text, that text is what the model sees, and
training warns if the memory field also has one. See
Memory.
Implicit next
A step with no next falls through to the step below it, and the last step
falls through to END. Add next: where you are branching or jumping
backwards.
Conditional branching
Anext: branch list routes on conditions, with else: as the fallback:
else: last.
Conditions use the standard expression grammar. See
Conditions.
How a block is entered
Routing lists skills, not blocks. How a block is reached follows from the shape of the skill:DTMF
Adddtmf: to a collect: step to let a caller answer by pressing phone keys.
Keypresses count only while that step is active.
This block offers a keypad menu. utter_ask_account_type says “Press 1 for
checking, or 2 for savings”, and one keypress picks the branch:
categorical with the keys as enum_values, so a key
outside the menu is rejected:
skills/account_balance/memory.yml
Set exactly one of
length or finish_on_key. Tell the caller in the
utterance which key ends the input, or that they must use the keypad.
The digits are converted to the field’s memory type,
then written before the LLM runs, through the field’s
memory validation tool if it has
one. If the value is rejected, nothing is written and the turn
continues as a normal user message.
Declare identifiers that can start with zero, such as account numbers, as text
so leading zeros are kept.
Keypad input arrives on the twilio_media_streams, jambonz_stream,
audiocodes_stream, and genesys channels. The Inspector does not send keypad
input, so test keypad steps on a real line. On other channels, and on text, the
step collects the value as usual.
Repeating a collect
Use this when the collect utterance is a page of dynamic buttons (buttons: {source: ...}). Handle the tap, clear the collected field, and
route back to the same collect: step. You do not need a second collect or an
execute_tool: listen between pages. The engine asks again and the button source
runs for the new page.
This block asks for an appointment time. A Next button writes
slot_choice. The tool turns the page, clears that field, and the else:
branch returns to collect_slot.
slot_choice. The tool then stores
selected_time instead of clearing the field, so route_choice takes
selected rather than looping.
Recording a human handoff
record_handoff is a bundled tool with no arguments. An ordered block runs it
with execute_tool. It does not speak, write memory, or transfer the user.
Studio analytics use this call to count the conversation as handed to a human,
including when the transfer that follows fails. Put the step at the moment the
handoff is decided. The steps after it perform the transfer.
It is not a framework tool. The model is never offered it. A tools: gate or
@tool.record_handoff in prose does not resolve. A project function, shared
tool, or MCP import with this name fails training. A parameters: map on the
step fails training too, including a session.* value, because the tool
accepts no arguments.
See also
- Ordered Blocks: when to use one
skill.mdreference: the fence and frontmatter- Conditions: the expression grammar
- Dynamic buttons: button source tools