Clarifying Questions

Overview

Skills normally run from start to finish without stopping. Sometimes, though, a skill needs a decision that only the user can make: which output format to produce, or which of two matching records to use. Clarifying questions let a skill ask the user a multiple-choice question and continue once they answer.

The question is shown as a card directly above the chat composer. When the user picks an answer, the run resumes from exactly where it paused and the assistant continues with the result. It is the same pause/resume pattern you may recognise from Claude itself.

There are two modes:

Use pre-run for inputs you always need (and could also be passed up front). Use mid-run for decisions that only become clear once the skill is working.

Mid-run questions

1. Enable it

Set one flag in the SKILL.md frontmatter:

---
slug: summarise-topic
name: Summarise a topic
allow_mid_run_clarification: true   # required; default is false
---

This flag is the master switch. When it is true, the model is automatically given the ask_clarifying_question tool. You do not need to add it to the space's enabled tools; enabling the flag exposes it for this skill only.

2. Tell the model when to ask

You do not write the question out as structured data. You instruct the model in plain language in the playbook (the markdown body below the frontmatter), and the model builds the structured question itself at runtime:

# Summarise a topic
 
You are given a `topic`.
 
1. If the desired output format is unknown, call the `ask_clarifying_question`
   tool with one question: which format the user wants, with options "short" and
   "detailed". Wait for the answer.
2. Write the summary in the chosen format.

That sentence is all you author. At runtime the model turns it into a structured question (a key, a header, the option list) and the platform pauses the run until the user answers.

3. What the user sees

1. The run pauses (state awaiting_input).
2. A question card appears above the chat composer with the options and a Continue button. Questions are presented in small batches rather than all at once (see the per-batch cap under Limits below).
3. The user picks an answer and submits — clicking Continue or simply pressing Enter once all required questions are answered. They can also click I don't know to decline (the skill continues and makes a sensible choice itself, receiving declined: true), or Cancel skill to abort the whole run.
4. The run resumes from its checkpoint with the answer, finishes, and the assistant continues with the result.

If the user never answers, the question expires after the clarification timeout (15 minutes by default) and the run fails with clarification_timeout.

Pre-run questions

For questions you always ask before the skill runs (typically to fill a required input), declare them in the frontmatter. Each question binds to an input via input_parameter and is skipped automatically when that input is already provided in the request.

---
slug: regional-report
name: Regional report
inputs:
  region:
    type: string
    required: true
clarifying_questions:
  - key: region
    header: Region
    text: Which region should the report cover?
    input_parameter: region
    options:
      - { value: eu, label: Europe }
      - { value: us, label: North America }
      - { value: apac, label: APAC }
---

When the skill is started without region, the run-start gate returns clarification_required and the question is shown before the skill executes. Once answered, the value is merged into the inputs and the run proceeds.

Question reference

Both modes use the same question shape. (For mid-run questions the model fills these in; for pre-run questions you write them in YAML.)

A question must offer at least one option or set allow_free_text: true.

Limits and configuration

The effective per-request bound is min(max_clarification_questions or SKILL_CLARIFICATION_MAX_PER_BATCH, SKILL_CLARIFICATION_MAX_PER_BATCH_CEILING).

Complete example

A minimal skill that asks one mid-run question and then produces its output:

---
slug: summarise-topic
name: Summarise a topic
version: 1.0.0
description: Summarise a topic, asking the user for the format first.
intent: Ask for a format choice, then summarise the given topic.
allow_mid_run_clarification: true
inputs:
  topic:
    type: string
    required: true
outputs:
  result:
    type: markdown
    required: true
---
 
# Summarise a topic
 
You are given a `topic`.
 
1. First, before anything else, call the `ask_clarifying_question` tool with one
   question: which format the user wants, with options "short" and "detailed".
   Wait for the answer.
2. Write a summary of the topic in the chosen format.
3. Return the result as markdown.

The only things you must provide for mid-run questions are the allow_mid_run_clarification: true flag and a sentence in the playbook telling the model when to ask. Everything else (the question structure, the pause, the resume) is handled for you.