# ask-user-question: Use the Structured Question Tool for User Decisions
English | [简体中文](README_CN.md)
When an agent needs the user to decide, it calls its built-in structured question tool so the user can pick an answer.
When that tool is unavailable, though, agents often bury the options in prose. The user has to read the whole paragraph to answer, and the answer may not map cleanly to an option.
This skill gives every question clear options, a recommendation, and consequences.
> 💡 This skill only governs how the agent asks the user questions. It does not affect project code, comments, commit messages, or generated files.
---
## Why ask-user-question?
**Typical AI question (options buried in prose):**
> "The change is done. The log cleanup was outside the original scope. Should I revert it or keep it? If we keep it, it could also go in a separate commit, or I could look for another approach."
**With a structured question tool (the user picks):**
| Option | Description |
| ------------------------- | ------------------------------------------------ |
| `1. Revert (Recommended)` | This commit contains only the login fix. |
| `2. Keep` | The log cleanup is committed with the login fix. |
**Without the tool (numbered text, the user replies `1`):**
```
Keep the log cleanup change?
1. Revert (Recommended) — This commit contains only the login fix.
2. Keep — The log cleanup is committed with the login fix.
```
---
## Features
- **Tool first**: when the user can pick on the spot, the agent always calls the structured question tool and does not list text options in the reply.
- **Decision-ready options**: labels are numbered, the recommended option comes first, and consequences go in the description field. When a rule fixes the options, their meaning, numbering, and order stay unchanged.
- **One question at a time**: by default each reply asks one question; when a rule limits the number of questions, that rule applies.
- **Explicit exceptions**: the agent falls back to a text list, and says why, only when the tool limit is exceeded and the question cannot be split, when there is no tool or the call fails, or when the user cannot pick on the spot.
- **Unique numbers**: every answer in a text list has a unique number within the reply, so the user can reply with just `1a, 2b`.
---
## Installation
### Recommended: install with the `skills` CLI
[`skills`](https://github.com/vercel-labs/skills) is an Agent Skill manager from Vercel Labs that supports Claude Code, Cursor, Codex, and other popular environments.
Install globally (for all projects):
```bash
npx skills add dualface/ask-user-question -g
```
Install into the current project:
```bash
npx skills add dualface/ask-user-question
```
Install for a specific agent only (for example, Claude Code):
```bash
npx skills add dualface/ask-user-question -g -a claude-code
```
Update and remove:
```bash
npx skills update ask-user-question -g
npx skills remove --global ask-user-question
```
### Manual installation
Clone this repository into the agent's skills directory, naming the target directory `ask-user-question`:
**Claude Code (global):**
```bash
git clone https://github.com/dualface/ask-user-question.git ~/.claude/skills/ask-user-question
```
For other agents that support the `SKILL.md` convention, see their documentation for the skills path.
---
## Usage
No activation is needed after installation. The agent loads this skill automatically, based on its description, when it is about to ask the user to decide, confirm, or choose. You can also type `/ask-user-question` manually.
### Notes
- **How it works**: this skill takes effect through the agent following the instructions in its context. Nothing enforces it programmatically.
- **When it loads**: skills load on demand, so the agent may ask a question before loading this one.
- **Always on**: to apply it to every question, add "read the ask-user-question skill at the start of every session and follow it" to the agent's global rules (for example, Claude Code's `~/.claude/CLAUDE.md` or a file in `~/.claude/rules/`).
---
## Core files
| Path | Description |
| ---------- | ------------------------------------------------------------------------------ |
| `SKILL.md` | Skill entry point: question rules, conditions for text lists, numbering format |
---
## License
Open source under the MIT License. See [LICENSE](LICENSE).
---
## Other projects by the author
Try other projects by [dualface](https://dualface.dev/):
- [Kander](https://github.com/dualface/kander): rule-driven multi-agent kanban orchestration with built-in independent review and delivery gates.
- [Ullage](https://github.com/dualface/ullage-cli): a local daemon and CLI for checking usage of Claude, ChatGPT, Grok, Cursor, and other subscriptions.
- [QuickTUI](https://quicktui.ai/): a full terminal on your phone for any coding agent. Self-hosted and direct-connected, free for a single host.