When to use an ordered block vs. another lever
The fence
id=pick_card. The body between
the fences is YAML: the steps: list.
The prose around the block is what tells the LLM when to enter it, so say so in
the same sentence that references @block.<block_id>. When the skill is already
running, the model moves into that block with
enter. When the block completes,
execution returns to the surrounding prose.
Hybrid: one ordered block inline
The Card Replace skill has a problem: the agent sometimes checks eligibility after the customer picks a card, or skips the check entirely. Order matters, and prose isn’t enforcing it. That section becomes a block; the rest stays prose.skills/card_replace/skill.md
select_card step is still a conversation: the LLM owns the wording and the
back-and-forth, and the step ends once selected_card_id is set. Everything
outside the block stays prose with if: scoping.
For the full step vocabulary, see
Ordered block steps.
Fully controlled
A fully guided skill is blocks only. It has one entry block: the only ordered block that no other block in the skill starts withcall: or link:. The
block id has no reserved name: main is allowed, and so is any other id.
activate with the skill id starts it. Routing shows the skill id and the
skill description. An ordered block has no description.
Training will fail if:
- an ordered block sets a
description— routing uses the skill description - there is no entry block — every block is started by
call:orlink:from another block in the skill - there is more than one entry block — more than one block is not started that way
- a block cannot be reached from the entry — no
call:orlink:path leads from the entry to that block
skills/card_replace/skill.md
The tradeoff
Every step you put inside a block is a step the agent can no longer reorder. A block is a state machine, and it holds that order even when the conversation would naturally take another route: a customer who volunteers the answer to step four while you are on step one, or who asks a question mid-sequence, is moving against the grain of the block. The more of a skill you enclose, the more of that flexibility you trade away, and the more scripted the conversation feels. That trade is worth making where the order carries a regulatory or correctness requirement, and rarely worth making anywhere else. In practice that is two to five steps, not a whole skill, which is why the hybrid form covers most enterprise needs.Boundary rules
- Local order, not global lock-in. The user can trigger a different skill mid-block. The block pauses and, if the user comes back to it, continues at the same step.
- Prose and blocks coexist. Prose enters a block via
@block.<block_id>; when it completes, execution returns to the prose. tool_constraintsare always enforced. Whether the LLM or anexecute_tool:step attempts the call,requires:is checked.
ordered_block_* events. See
What the Inspector records
and the tracker event contract.