Ask UI

Use Ask UI as a presentation and persistence adapter. Question generation and reasoning remain in the caller's workflow.

Determine Whether to Use the UI

Use the UI when the current round contains at least two independent questions that the user can answer immediately. Questions with dependencies should be left for subsequent rounds. Ask directly in the conversation when there's only one question.

For

grill-me

grill-with-docs

, brainstorming, or other confirmation and question collection workflows, always use the UI when a round has more than two questions.

Fallback to the caller workflow's regular text format if the local service or browser cannot start.

Ask Questions and Wait for Responses

Resolve the directory containing this
```
SKILL.md
```
as
```
ASK_UI_SKILL_DIR
```
.
Read references/schema.md before creating JSON.
Create a QuestionSet JSON file. Omit
```
sessionId
```
for new tasks; reuse the currently active
```
sessionId
```
and set
```
basedOnRound
```
for subsequent rounds. Include context fields so users can understand the questions without viewing the conversation: Session-level
```
projectName
```
/
```
sessionSummary
```
/
```
sessionBackground
```
, Round-level
```
purpose
```
, and write
```
background
```
for questions that require separate context. Multiple-choice questions do not have an "Other" option. Answers outside the preset options are carried by the supplementary notes for each question, so only list truly mutually exclusive options and don't add "Other" to fill in.
Run the foreground command and keep this tool call active until it exits:
text
```
node <ASK_UI_SKILL_DIR>/scripts/ask-ui.mjs ask --input <questions.json>
```
This command writes readiness information, the
```
ask-ui-session: <id>
```
marker, and a local URL to stderr, opens the form, and waits. Do not end the Agent round, and do not ask the user to reply "submitted".
After the user submits, parse the single JSON result output to stdout and immediately continue the original workflow.
If more independent questions are needed, call
```
ask
```
again with the same
```
sessionId
```
and set
```
basedOnRound
```
to the returned round number. End the Session when there are no more questions.

When the Command is Put in the Background or Interrupted

ask

blocks until the user submits, which can easily be moved to the background by the harness. After moving to the background, stdout and stderr are mixed in the same task output file, parsing that file directly will definitely fail.

Never ask the user to reply "submitted" to advance
ask
. After the user fills out the form, the page closes automatically, and the

ask

process exits immediately. The harness will push a background task completion notification to you—that's the signal the result is ready, no need for the user to repeat it. Asking the user to report what they just did is the only state that should never occur in this flow.

Follow this order of judgment after moving to the background:

Command is still running → End this round and wait for the harness's task completion notification. Do not
```
sleep
```
to poll, do not urge the user.
Received completion notification, or
```
ask-ui-submitted: <id> round <n>
```
appears in the output → Result is ready.

Retrieve the result using the

ask-ui-session: <id>

from stderr:

text

node <ASK_UI_SKILL_DIR>/scripts/ask-ui.mjs resume --session <sessionId>

When

resume

returns

status: "submitted"

, it contains the complete answer; when it returns

{"status":"waiting"}

, it means the process hasn't exited yet, go back to step 1 and continue waiting. Do not

tail

the task output, do not manually construct the file path under

.ask-ui/

The browser opens every round: the page closes automatically after submission, so the next round must reopen. All rounds of the same Session reuse the persistent service and stable URL.

Only use

--no-open

when browser opening is managed separately externally. Only use

--port <number>

when the localhost port must be fixed.

Manual Fallback and Recovery

This is a last resort, only to be used when

ask

is truly unavailable—it's the only path that requires the user to reply "submitted".

ask

being moved to the background does not count as unavailable; follow the previous section to wait for notifications in that case.

Follow the detached process when: the foreground tool call cannot stay active, the local browser cannot connect to the temporary service, or an interrupted direct connection round needs to be restored:

text

node <ASK_UI_SKILL_DIR>/scripts/ask-ui.mjs create --input <questions.json>

Parse the returned JSON. Provide both its URL and a visible marker in the conversation:

text

ask-ui-session: <sessionId>

Tell the user to only reply "submitted" after submitting the form. The

create

command starts or reuses a detached localhost service and returns immediately.

When the user says "submitted", "done submitting", or "finished answering":

Retrieve the
```
sessionId
```
from the most recent
```
ask-ui-session
```
marker in the conversation.

Run:

text

node <ASK_UI_SKILL_DIR>/scripts/ask-ui.mjs resume --session <sessionId>

If the result is
```
submitted
```
, use the questions and answers in it to continue the original workflow.
If more independent questions are needed, prioritize returning to the foreground
```
ask
```
command, using the same
```
sessionId
```
and setting
```
basedOnRound
```
to the round just processed. Only use
```
create
```
again if direct connection waiting is still impossible.

If there are no more questions, run:

text

node <ASK_UI_SKILL_DIR>/scripts/ask-ui.mjs complete --session <sessionId>

If the marker cannot be obtained from the conversation, run

resume

without

--session

. When multiple candidates are returned, infer the most matching one based on the current topic, workspace, title, and submission time. Only ask the user if the match is truly undetermined.

Duplicate "submitted" messages must not create duplicate rounds. Only create a new round after successfully reading a

submitted

round.

Maintain Session Continuity

One task corresponds to one Session.
Each batch of questions corresponds to one Round.
All rounds of the same task reuse the same
```
sessionId
```
.
Never overwrite submitted questions or answers.
Corrections and supplementary confirmations are placed in new Rounds.
Only start a new Session for a new task, when the task is completed, or when the user explicitly requests a restart.

Optional Active Wake-Up

Ask UI supports optional wake-up metadata for Claude Code and Codex App Server. Treat this as an enhancement, not a requirement.

Only enable automatic wake-up after user consent.
Claude Code requires a recorded session id.
Codex requires a host-provided thread id. Never guess the Codex thread id.
When the adapter fails, preserve the answer and return to the manual "submitted" process.
Direct connection
```
ask
```
mode never triggers the wake-up adapter, as the waiting process itself is the return channel.

Common Commands

text

node <ASK_UI_SKILL_DIR>/scripts/ask-ui.mjs ask --input <questions.json>
node <ASK_UI_SKILL_DIR>/scripts/ask-ui.mjs create --input <questions.json>
node <ASK_UI_SKILL_DIR>/scripts/ask-ui.mjs status --session <sessionId>
node <ASK_UI_SKILL_DIR>/scripts/ask-ui.mjs serve
node <ASK_UI_SKILL_DIR>/scripts/ask-ui.mjs complete --session <sessionId>
node <ASK_UI_SKILL_DIR>/scripts/self-test.mjs

ask-ui

NPX Install

Tags

SKILL.md Content (Chinese)

Ask UI

Determine Whether to Use the UI

Ask Questions and Wait for Responses

When the Command is Put in the Background or Interrupted

Manual Fallback and Recovery

Maintain Session Continuity

Optional Active Wake-Up

Common Commands