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:

{
  "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:

## 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:

## 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.

## 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:

## 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:

## 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:

**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:

**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