# Ask User Question

> Implement skills using AskUserQuestion tool for interactive user input and decisions. Use when authoring skills that need to gather options, handle free-text answers, process multi-select, or build multi-step workflows. Covers tool mechanics, constraints, wiring into skills, response handling, and dynamic question patterns.

- Skill: `full-stack-biz/ask-user-question` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add full-stack-biz/ask-user-question`
- Raw SKILL.md: https://api.skillmd.com/api/skills/full-stack-biz/ask-user-question/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: full-stack-biz (https://skillmd.com/u/full-stack-biz)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/full-stack-biz/ask-user-question

---


# Implementing Skills with AskUserQuestion

How to author skills that use the AskUserQuestion tool for interactive user input, decisions, and guided workflows.

## Official Tool Purpose

From Claude Code system prompt:

**Use AskUserQuestion to:**
1. **Gather user preferences or requirements** - Understand what user wants
2. **Clarify ambiguous instructions** - Ask when instructions are unclear
3. **Get decisions on implementation choices** - Multiple valid approaches exist
4. **Offer choices about what direction to take** - User picks path forward

**Key Capabilities:**
- Users always see "Other" option for custom text input
- `multiSelect: true` allows selecting multiple answers
- Put recommended option first, labeled with "(Recommended)"

**Important:** Don't use to ask "Is my plan ready?" or similar meta-questions. Use in-band questions only for actual decisions.

## How It Works in Skills

**Response Format:**
```json
{
  "questions": [...original questions...],
  "answers": {
    "Question text": "selected option OR custom text",
    "Another question": "answer"
  }
}
```

**Critical Rule:** Custom text appears in answers directly, not as "Other"
```
answers["Framework?"] = "angular"    ✅ (user typed)
answers["Framework?"] = "Other"      ❌ (never this)
```

## Hard Constraints

**Tool Limits (Claude Code enforced):**
- Max 1-4 questions per call
- Min 2, Max 4 options per question
- "Other" is automatic (never include in options list)
- Max header: 12 characters
- Max option label: varies but aim for 1-5 words
- Max description: 1-2 sentences recommended

**"Other" Behavior:**
- Always present automatically
- Users can type any custom text
- Custom text returned as answer value (not "Other")

Example:
```
answers["Framework?"] = "angular"     ✅ (user typed "angular")
answers["Framework?"] = "Other"       ❌ (never this)
```

## How to Wire AskUserQuestion Into a Skill

### Pattern 1: Prose Question (Typical)

Ask in natural language, users respond freely:

```markdown
## Step 1: Ask User for Input

**What are we building?**

Describe the feature or change you want to make.

(I'll ask follow-up questions if I need clarification)

[User responds with description]

## Step 2: Follow-Up If Needed

Based on their response, ask 1-2 clarifying questions:
- "Is this a new feature or updating existing?"
- "What's the expected outcome?"

[User responds]

## Step 3: Process Answers

Use their responses to inform next steps...
```

### Pattern 2: Structured Options (When Choices Matter)

Use tool when user must select from specific options:

```markdown
## Step 1: Ask for Configuration Choice

Use AskUserQuestion tool:

**Question 1:**
- Text: "Which option?"
- Header: "Choice"
- Options:
  - Label: "Option A"
    Description: "What this does, trade-offs"
  - Label: "Option B"
    Description: "Alternative approach"

[User selects or types "Other" for custom]

## Step 2: Process Answer

The response provides:
- answers["Which option?"] = user's selection

Based on answer:
- If "Option A": Do X
- If "Option B": Do Y
- If custom text: Do Z

## Step 3: Continue

Proceed with workflow...
```

### Progressive Disclosure Pattern

CRITICAL: Ask ONE question, wait for response, THEN ask next.

```markdown
## Question 1: Gather Type

Ask: "What type of project?"
Options: Web, Mobile, CLI

[User answers]

## Question 2: Framework (Conditional)

Based on answer to Q1:
- If Web: Ask "Frontend framework?"
- If Mobile: Ask "Platform?"
- If CLI: Ask "Language?"

[User answers]

## Question 3: Confirmation

Show summary and ask: "Proceed?"
Options: Yes, No, Edit

[Continue based on answer]
```

## Defining Questions in Skills

### Pattern 1: Prose with Guidance (Recommended)

Ask questions in natural language with examples. No options needed:

```markdown
## What are we building?

Please describe the feature or change.

(Be as specific as you like — I'll ask follow-ups if needed)
```

Or with guidance:

```markdown
## Do you have any visuals to reference?

- Mockups or wireframes
- Screenshots of similar features
- Examples from other apps

(Paste images, share file paths, or say "none")
```

This pattern:
- ✅ Feels natural to users
- ✅ Allows truly open input
- ✅ No constraint on number of options
- ✅ Users can respond with anything

### Pattern 2: Structured Options (When Choosing Matters)

Use tool options when user must select from specific choices:

```markdown
**Question: Database Selection**
- Text: "Which database for this project?"
- Header: "Database"  (max 12 chars)
- Options:
  - Label: "PostgreSQL"
    Description: "Relational, ACID compliant, best for complex queries"
  - Label: "MongoDB"
    Description: "Document-based, flexible schema, rapid iteration"
  - Label: "Redis"
    Description: "In-memory, very fast, ideal for caching"
```

Constraints for this pattern:
- Min 2, Max 4 options per question
- "Other" automatic for custom input
- Users can select one (or multiple if `multiSelect: true`)

Use when:
- Multiple mutually-exclusive choices exist
- Each option leads to different workflow
- You want to guide without forcing

### Pattern 3: Multi-Select Options

When users should enable/select multiple independent items:

```markdown
**Question: Which features to enable?**
- Header: "Features"
- multiSelect: true
- Options:
  - "Logging" (Operation logs for debugging)
  - "Metrics" (Performance monitoring)
  - "Alerts" (Error notifications)
  - "Backups" (Automatic data backups)
```

Response: `answers["Features?"] = "Logging, Metrics"` (joined with ", ")

## Processing Responses

### Basic Response Handling

```
The tool returns:

{
  "questions": [...],
  "answers": {
    "Which database?": "PostgreSQL"
  }
}

In skill body:

Based on the answer to "Which database?":
- If "PostgreSQL": Set up relational database
- If "MongoDB": Set up document database
- If "Redis": Set up in-memory cache
- If custom text: Configure for custom database name

Then proceed with configuration...
```

### Checking Multiple Answers

```
From response:
- answers["Database?"] = "PostgreSQL"
- answers["Environment?"] = "production"
- answers["Features?"] = "Logging, Metrics"

In skill:

Database: PostgreSQL (check: is this supported?)
Environment: production (check: validate settings for prod)
Features: Split by ", " and enable each

If any validation fails:
  Log error
  Ask user to reconfigure
  Return to questioning phase
```

### Handling Free-Text Answers

When users select "Other" and type custom input, you need to handle it properly.

**Pattern:** Check if answer is a known option or custom text, then route accordingly.

```
If user selected "Other" and typed "custom-framework":

answers["Framework?"] = "custom-framework"

In skill:

Check if "custom-framework" is in known frameworks:
  - If yes: use framework-specific setup
  - If no: use generic setup with warning

Log: "Using custom framework: custom-framework"
Proceed with generic configuration...
```

See `references/free-text-input-patterns.md` for complete patterns for handling custom input including validation, generic fallbacks, and user feedback.

## When to Use Each Pattern

### Use Prose Questions When:
- Scope is open-ended (user describes feature, context, etc.)
- You need true free-form input
- Multiple follow-ups will be needed
- No specific options constrain the answer
- Examples: "What are we building?", "Describe the problem"

### Use Structured Options When:
- User must choose from specific alternatives
- Each option leads to different workflow/configuration
- You want to guide without forcing
- Examples: "Which database?", "Enable monitoring?" (Yes/No)

### Mixed Approach:
Start with prose for context/understanding, then use structured options for specific decisions:

```
Step 1: Ask "What are we building?" (prose)
Step 2: Ask "Which database?" (structured options)
Step 3: Ask "Which features?" (multi-select options)
```

## Question Design (For Structured Options)

When using predefined options:
- **Be specific:** "Which database for this project?" (not "Database?")
- **Provide context:** "Relational, ACID compliant, best for complex queries"
- **Show trade-offs:** "Fast for reads, slower for writes, good for analytics"
- **Mutually exclusive:** Options should be distinct (unless multiSelect)
- **Consistent format:** Same capitalization, length (~1-2 sentences), detail level

See `references/skill-patterns.md` for complete question design examples.

## Dynamic Questions Pattern

How to ask different questions based on previous answers:

```
## Step 1: Initial Question

Ask: "Application type?"
Options: Web, Mobile, CLI

[Get answer]

## Step 2: Conditional Question

If answer == "Web":
  Ask: "Frontend framework?"
  Options: React, Vue, Svelte

If answer == "Mobile":
  Ask: "Platform?"
  Options: iOS, Android, Cross-platform

If answer == "CLI":
  Ask: "Language?"
  Options: Python, Go, Rust

[Get answer]

## Step 3: More Conditional Questions

Based on BOTH previous answers:
If Web + React:
  Ask: "State management?"
  Options: Redux, Context, Zustand

If Web + Vue:
  Ask: "State management?"
  Options: Pinia, Vuex

[Continue...]
```

## Error Handling in Skills

### Check if Response Received

```
If AskUserQuestion fails or no answers:

Log error: "Failed to gather responses"
Show: "Please try again or provide configuration manually"
Exit

(Or restart the questioning phase)
```

### Validate Answer Format

```
If question expects "port number":
  answers["Port?"] could be:
  - "8080" (valid)
  - "invalid" (needs validation)
  - "12345" (out of range)

Validate before using:
  Parse as number
  Check range (1-65535)
  If invalid: Ask user to reconfigure
```

### Handle Empty Answers

```
If answers["Required field?"] is empty or missing:

Log: "No answer provided for required field"
Ask user to reconfigure

Don't proceed with empty critical answers
```

## Common Limitations & Workarounds

See `references/advanced-patterns.md` for detailed workarounds for common constraint scenarios (max questions, max options, dependent options, pre-populating answers).

## Response Processing Workflow

Typical skill using AskUserQuestion:

```
1. Describe what you're asking
   "Let's configure your database"

2. Ask Question 1
   Call AskUserQuestion with 1 question

3. Get Response
   Extract answers from response object

4. Validate
   Check format, compatibility, ranges

5. Ask Question 2 (if conditional)
   Based on Q1 answer, ask Q2

6. Get Response & Validate

7. Process All Answers
   - Check compatibility across answers
   - Apply configuration
   - Generate outputs

8. Confirm
   Ask: "Does this look right?"
   If Yes: Proceed
   If No: Restart from Q1
```

## Writing About AskUserQuestion in Skills

See `references/skill-patterns.md` for guidance on documenting AskUserQuestion in skill descriptions, body content, and custom input support.

## Testing Skills with AskUserQuestion

See `references/robust-skills.md` for testing validation patterns and common test cases (valid options, custom text, invalid input, edge cases).

## Key Takeaways

✅ **Max constraints:** 1-4 questions, 2-4 options, 12-char header

✅ **Progressive disclosure:** One question → wait → next question

✅ **Custom input:** "Other" automatic, custom text goes in answers

✅ **Conditional:** Ask different Q2 based on Q1 answer

✅ **Validation:** Always check answers before using

✅ **Response format:** Extract from `answers` object

✅ **Error handling:** Check for missing/invalid answers

❌ **Don't:** Combine multiple questions, use >4 options, include "Other" in options

See `references/common-mistakes.md` for detailed anti-patterns and how to avoid them.

## Plan Mode: Clarifying Decisions vs. Meta-Questions

Use AskUserQuestion in plan mode to **clarify real implementation decisions** (database choice, monitoring config), not meta-questions ("Is my plan ready?"). For plan approval, use the plan approval tool instead. See `references/advanced-patterns.md` for detailed guidance.

---

**Based on:** Claude Code system prompt (tool-description-askuserquestion.md)
**Source:** https://github.com/Piebald-AI/claude-code-system-prompts
**Last updated:** 2026-02-25 | **Version:** 1.0.0