advanced-ask

name

advanced-ask

description

Use when the built-in AskUserQuestion tool is insufficient - specifically when needing to ask more than 4 questions, present more than 4 options, get direct text input without "Other" workaround, pick files/directories, or fuzzy-filter through long lists. IMPORTANT - when any AskUserQuestion limit is hit (>4 options, >4 questions, need text input, need file picker), automatically use this skill instead of degrading the question. NEVER work around limits by splitting one question across multiple AskUserQuestion calls, narrowing options to fit within 4, or truncating a naturally enumerable set (e.g. 7 rainbow colors presented as two 4-option questions). These are degradation anti-patterns — load this skill instead. Complements gum and interactive-tmux skills.

Advanced Ask

Extended user questioning capabilities that complement the built-in AskUserQuestion tool using gum via interactive-tmux.

When to Use This Skill

Use advanced-ask when AskUserQuestion cannot handle the scenario:

Scenario	AskUserQuestion	advanced-ask
>4 options	No (max 4)	Yes (unlimited)
>4 questions	No (max 4)	Yes (unlimited via form)
Direct text input	No (only via "Other")	Yes (ask-input)
Multi-line text	No	Yes (ask-write)
File/dir picker	No	Yes (ask-file)
Fuzzy filter list	No	Yes (ask-filter)
Custom confirm labels	No	Yes (ask-confirm)

Prefer AskUserQuestion for simple cases (≤4 questions, ≤4 options) as it has better integration with Claude Code's UI. When AskUserQuestion limits are hit, switch to this skill automatically — do not degrade the question to fit AskUserQuestion's constraints.

Degradation Signals

Before calling AskUserQuestion, check for these anti-patterns. If any apply, stop and use advanced-ask instead:

Anti-pattern	Example	Fix
Splitting one question across multiple calls	7 rainbow colors → two questions of 3-4 each	ask-multi or ask-choose with all 7
Narrowing options to fit within 4	"Favorite animal?" with only Cat/Dog/Fox/Owl	ask-input (free text) or ask-choose with a full list
Truncating a naturally enumerable set	Days of week, months, colors — but only showing some	ask-choose/ask-multi with the full set
Using "Other" as a crutch for open-ended questions	"Favorite animal?" where most answers won't be in the list	ask-input for free text
Asking >4 questions sequentially	Splitting a 6-question form into two AskUserQuestion calls	ask-form with all questions

Rule of thumb: If you find yourself reshaping a question to fit AskUserQuestion's constraints, that's the signal to use this skill.

Quick Reference

All scripts are in ~/.claude/skills/advanced-ask/scripts/.

Piping Options via Stdin

When options contain special characters (em-dashes, unicode, etc.) or there are many options, pipe them via stdin. Use a heredoc — this avoids both file-write permission prompts and the Bash safety checker's newline-in-command flag:

~/.claude/skills/advanced-ask/scripts/ask-choose.sh --header "Pick a framework" --descriptions <<'EOF'
React|Meta's UI library
Vue|Progressive framework
Angular|Google's full framework
Svelte|Compiler-based reactive framework
EOF

Format: one option per line, plain UTF-8. Empty lines are skipped. For --descriptions mode, use label|description format (same as positional args). Stdin options are appended to any positional args.

Why heredoc over printf? Multi-line printf with backslash continuations triggers the Bash safety checker ("Command contains newlines that could separate multiple commands"). Heredocs are recognized as a single command and pass cleanly. They are also easier to read with many options.

Why stdin over files? Writing temp files (via the Write tool or Bash redirections) triggers permission prompts regardless of directory.

Using Options Files (Alternative)

The --options-file flag is still available when options are already in a file (e.g., dynamically generated by another command):

~/.claude/skills/advanced-ask/scripts/ask-choose.sh --header "Pick a framework" \
    --descriptions --options-file /path/to/options.txt

Single Selection (Many Options)

~/.claude/skills/advanced-ask/scripts/ask-choose.sh --header "Pick a framework" \
    "React" "Vue" "Angular" "Svelte" "Solid" "Preact" "Qwik"

# With descriptions (use "label|description" format)
~/.claude/skills/advanced-ask/scripts/ask-choose.sh --header "Pick a language" --descriptions \
    "Python|Great for scripting" "Go|Fast and compiled" "Rust|Memory safe"

# With Other/Skip/Chat options (like AskUserQuestion)
~/.claude/skills/advanced-ask/scripts/ask-choose.sh --header "Pick a language" \
    --other --skippable --chattable \
    "Python" "Go" "Rust"

Multi-Selection

~/.claude/skills/advanced-ask/scripts/ask-multi.sh --header "Select features" \
    "Auth" "Database" "API" "Cache" "Queue" "Search"

# With descriptions
~/.claude/skills/advanced-ask/scripts/ask-multi.sh --header "Select features" --descriptions \
    "Auth|User authentication" "Database|PostgreSQL setup" "Cache|Redis caching"

# With Other option (allows custom additions)
~/.claude/skills/advanced-ask/scripts/ask-multi.sh --header "Select features" --other \
    "Auth" "Database" "API"

Text Input

~/.claude/skills/advanced-ask/scripts/ask-input.sh \
    --header "Configuration" \
    --placeholder "Enter API key"

# With a default value pre-filled
~/.claude/skills/advanced-ask/scripts/ask-input.sh \
    --header "Server port" \
    --value "8080"

# Password mode (input masked)
~/.claude/skills/advanced-ask/scripts/ask-input.sh \
    --header "Enter secret" \
    --password

Multi-line Text

~/.claude/skills/advanced-ask/scripts/ask-write.sh \
    --header "Description" \
    --placeholder "Enter detailed description..."

File Picker

~/.claude/skills/advanced-ask/scripts/ask-file.sh ~/projects
~/.claude/skills/advanced-ask/scripts/ask-file.sh --directory              # directories only
~/.claude/skills/advanced-ask/scripts/ask-file.sh --preview                # with file preview
~/.claude/skills/advanced-ask/scripts/ask-file.sh --all                    # include hidden files
~/.claude/skills/advanced-ask/scripts/ask-file.sh --glob "SKILL.md" ~/.claude/skills  # only SKILL.md files
~/.claude/skills/advanced-ask/scripts/ask-file.sh --ext "ts" ~/project     # only .ts files
~/.claude/skills/advanced-ask/scripts/ask-file.sh --name "*.test.js"       # pattern match

Note: Uses fzf instead of gum file due to gum display bugs.

Fuzzy Filter

# From arguments
~/.claude/skills/advanced-ask/scripts/ask-filter.sh --header "Search" \
    "item1" "item2" "item3" ...

# From stdin (e.g., git branches, docker containers, file lists)
git branch --format='%(refname:short)' | \
    ~/.claude/skills/advanced-ask/scripts/ask-filter.sh --header "Select branch"

See references/patterns.md for more dynamic option examples (docker containers, npm packages, etc.).

Confirmation

~/.claude/skills/advanced-ask/scripts/ask-confirm.sh \
    --yes "Deploy" --no "Cancel" \
    "Deploy to production?"
# Exit code: 0=yes, 1=no

Multi-Question Form

# From JSON file
~/.claude/skills/advanced-ask/scripts/ask-form.sh form.json

# Inline JSON
~/.claude/skills/advanced-ask/scripts/ask-form.sh --inline '{
  "questions": [
    {"question": "Project name?", "type": "input", "key": "name"},
    {"question": "Language?", "type": "choose", "options": ["TypeScript", "Python", "Go", "Rust"], "key": "lang"},
    {"question": "Features?", "type": "multi", "options": ["Tests", "CI", "Docker", "Docs"], "key": "features"},
    {"question": "Description?", "type": "write", "key": "desc"}
  ]
}'
# Returns JSON: {"name": "...", "lang": "...", "features": [...], "desc": "..."}

For multi-step wizards, conditional follow-ups, and progressive disclosure forms, see references/patterns.md.

Script Reference

Script	Purpose	Output
ask-choose.sh	Single selection from many options	Selected option
ask-multi.sh	Multiple selections	Newline-separated selections
ask-input.sh	Single-line text input	User input
ask-write.sh	Multi-line text input	User text
ask-file.sh	File/directory picker with glob/ext filters	Selected path
ask-filter.sh	Fuzzy search through list	Selected item(s)
ask-confirm.sh	Yes/no with custom labels	Exit code (0=yes, 1=no)
ask-form.sh	Multi-question form	JSON object with answers

Common Flags for ask-choose.sh and ask-multi.sh

Flag	Description
--header "text"	Header text shown above choices
--descriptions	Enable descriptions using "label|description" format
--other	Add "Other..." option for custom input
--skippable	Add "Skip" option (returns empty)
--chattable	Add "Chat about this" option (exits with code 2)
--options-file FILE	Read options from file (one per line); appends to any positional args
--limit N	(multi only) Maximum selections

Exit Codes

Code	Meaning
0	Normal selection (including Skip, Other, empty)
1	Cancelled or error
2	"Chat about this" selected (header text in stdout)

Form JSON Schema

For the complete schema reference with all fields and a full-featured example, see references/form-schema.md.

Quick inline example:

{
  "questions": [
    {"question": "Project name?", "type": "input", "key": "name"},
    {"question": "Language?", "type": "choose", "options": ["TypeScript", "Python", "Go"], "key": "lang"},
    {"question": "Features?", "type": "multi", "options": ["Tests", "CI", "Docker"], "key": "features"}
  ]
}

Dependencies

This skill depends on:

• gum - Charmbracelet's CLI tool (brew install gum)
• fzf - Fuzzy finder, used for file picking (brew install fzf)
• interactive-tmux skill - For running interactive TUIs
• jq - For JSON processing in ask-form.sh (brew install jq)
• fd (optional) - Faster file finding for ask-file.sh (brew install fd)

Background Task Notifications

CRITICAL: The scripts run as background Bash commands. After the result is read via TaskOutput and the user receives a response, a <task-notification> for the same task ID will arrive later as a duplicate. On receiving a late duplicate notification:

1. NEVER acknowledge, mention, or respond to it in any way
2. NEVER produce any output — not even a brief "(Already handled)" or similar
3. NEVER re-read the output file or re-process the result
4. Completely ignore the notification — produce absolutely zero visible output

The question was already answered. Any response to a late notification is noise that clutters the conversation.

Additional Resources

File	Purpose
references/patterns.md	Advanced patterns: conditional follow-ups, validation loops, wizards with back navigation, dynamic options
references/form-schema.md	Complete form JSON schema with all fields and examples