Skip to main content
An ordered block is a 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

A next: branch list routes on conditions, with else: as the fallback:
Branches are evaluated in order and the first match wins, so put 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

Add dtmf: 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:
Declare the field as 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.
A time button still writes 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