# Implementing Rich Interactions in Claude Plugins: Interactive Wizard Development

> Learn how to implement rich interactions in Claude plugins using the AskUserQuestion tool. Build dynamic, context-aware wizards for sophisticated multi-step workflows.

- Repository: [Anthropic/claude-plugins-official](https://github.com/anthropics/claude-plugins-official)
- Tags: how-to-guide
- Published: 2026-03-13

---

**Claude plugins support sophisticated multi-step workflows through the built-in `AskUserQuestion` tool, enabling developers to create interactive wizards that collect context-aware input and adapt dynamically to user responses.**

The `anthropics/claude-plugins-official` repository demonstrates how to move beyond simple slash-commands by embedding interactive dialogs directly in command markdown files. By leveraging `AskUserQuestion` as implemented in the official plugin toolkit, you can present multi-select options, conditional follow-up questions, and persist configurations for subsequent runs—all without external dependencies.

## Core Architecture of Interactive Commands

Interactive workflows in Claude plugins rely on three foundational components: front-matter tool declarations, JSON question payloads, and markdown-based answer processing.

### Declaring Interactive Tools in Front Matter

Every interactive command must begin with YAML front matter that explicitly lists `AskUserQuestion` in the `allowed-tools` array. This declaration grants the command permission to invoke the interactive tool during execution.

```markdown
---
description: Interactive deployment configuration
allowed-tools: AskUserQuestion, Write
---

```

According to the reference documentation in [`plugins/plugin-dev/skills/command-development/references/interactive-commands.md`](https://github.com/anthropics/claude-plugins-official/blob/main/plugins/plugin-dev/skills/command-development/references/interactive-commands.md), commands may also declare additional tools like `Bash`, `Read`, or `Write` to process answers or generate files based on user input.

### Structuring Multi-Question Dialogs

The `AskUserQuestion` tool accepts a JSON payload containing one to four questions. Each question requires a `header`, `question` text, and an `options` array. Setting `multiSelect: true` converts radio buttons to checkboxes, allowing users to select multiple values.

```json
{
  "questions": [
    {
      "header": "Deploy to",
      "question": "Which deployment platform will you use?",
      "multiSelect": false,
      "options": [
        { "label": "AWS", "description": "Amazon Web Services (ECS/EKS)" },
        { "label": "GCP", "description": "Google Cloud (GKE)" },
        { "label": "Azure", "description": "Microsoft Azure (AKS)" }
      ]
    }
  ]
}

```

### Processing Answers with Variable Interpolation

After the user submits responses, the tool returns a JSON object accessible through markdown variable interpolation. Commands reference specific answers using `$answers[index].answer` syntax, where the index corresponds to the question order in the payload.

```markdown
Selected platform: $answers[0].answer
Selected features: $answers[1].answer

```

This interpolation enables conditional logic—commands can inspect answers to determine which subsequent `AskUserQuestion` calls to invoke or which files to generate.

## Creating a Deployment Configuration Wizard

The following example from [`interactive-commands.md`](https://github.com/anthropics/claude-plugins-official/blob/main/interactive-commands.md) demonstrates a complete three-question workflow that collects deployment preferences and generates a persistent configuration file.

### Collecting Deployment Preferences

```markdown
---
description: Interactive deployment configuration
allowed-tools: AskUserQuestion, Write
---

# Deploy Setup

Use **AskUserQuestion** to collect the deployment target and environment.

```json
{
  "questions": [
    {
      "header": "Deploy to",
      "question": "Which deployment platform will you use?",
      "multiSelect": false,
      "options": [
        { "label": "AWS", "description": "Amazon Web Services (ECS/EKS)" },
        { "label": "GCP", "description": "Google Cloud (GKE)" },
        { "label": "Azure", "description": "Microsoft Azure (AKS)" },
        { "label": "Local", "description": "Docker on local machine" }
      ]
    },
    {
      "header": "Environments",
      "question": "How many environments do you need?",
      "multiSelect": false,
      "options": [
        { "label": "Single", "description": "Just production" },
        { "label": "Standard", "description": "Dev, Staging, Production" },
        { "label": "Complete", "description": "Dev, QA, Staging, Production" }
      ]
    },
    {
      "header": "Features",
      "question": "Which features do you want to enable?",
      "multiSelect": true,
      "options": [
        { "label": "Auto-scaling", "description": "Automatic resource scaling" },
        { "label": "Monitoring", "description": "Health checks & metrics" },
        { "label": "CI/CD", "description": "Automated deployment pipeline" },
        { "label": "Backups", "description": "Automated database backups" }
      ]
    }
  ]
}

```

```

### Generating Configuration Using Answers

```markdown

## Generate config

```yaml
---
deployment_target: $answers[0].answer
environments: $answers[1].answer
features:
  auto_scaling: $answers[2].answer contains "Auto-scaling"
  monitoring: $answers[2].answer contains "Monitoring"
  ci_cd: $answers[2].answer contains "CI/CD"
  backups: $answers[2].answer contains "Backups"
---

# Deployment configuration generated on $(date)

```

```

The generated YAML is written to [`.claude/deploy-config.local.md`](https://github.com/anthropics/claude-plugins-official/blob/main/.claude/deploy-config.local.md) for reuse in subsequent command invocations. As documented in the plugin-settings skill, this pattern allows progressive disclosure—first-time users get the full wizard while repeat users can skip directly to execution using persisted values.

## Building Multi-Stage Conditional Workflows

For complex scenarios like launching multi-agent swarms, plugins can chain multiple `AskUserQuestion` calls with conditional logic between stages.

### Initial Agent Count Selection

```markdown
---
description: Launch multi-agent swarm with guided task creation
allowed-tools: AskUserQuestion, Write, Bash
---

# Multi-Agent Swarm Launcher

**Stage 1 – Agent count**

```json
{
  "questions": [
    {
      "header": "Agent count",
      "question": "How many agents should we launch?",
      "multiSelect": false,
      "options": [
        { "label": "2 agents" },
        { "label": "3 agents" },
        { "label": "4 agents" },
        { "label": "6 agents" },
        { "label": "8 agents" }
      ]
    }
  ]
}

```

```

### Task Definition Method

```json
{
  "questions": [
    {
      "header": "Task setup",
      "question": "How would you like to define tasks?",
      "multiSelect": false,
      "options": [
        { "label": "File" },
        { "label": "Guided" },
        { "label": "Custom" }
      ]
    }
  ]
}

```

### Conditional Iterative Configuration

If the user selects **"Guided"**, the command enters an iterative loop based on the agent count selected in Stage 1. The command uses markdown conditionals to present additional `AskUserQuestion` calls for each agent:

```markdown

## Guided task creation (repeat $answers[0].answer times)

### Agent name

```json
{
  "questions": [
    { "header": "Agent name", "question": "What should we call agent #$i?", "multiSelect": false }
  ]
}

```

### Agent role

```json
{
  "questions": [
    {
      "header": "Task type",
      "question": "What task for $agent_name?",
      "multiSelect": false,
      "options": [
        { "label": "Authentication" },
        { "label": "API Endpoints" },
        { "label": "UI Components" },
        { "label": "Database" },
        { "label": "Testing" },
        { "label": "Documentation" }
      ]
    }
  ]
}

```

### Dependencies (multi-select)

```json
{
  "questions": [
    {
      "header": "Dependencies",
      "question": "What does $agent_name depend on?",
      "multiSelect": true,
      "options": [
        { "label": "No dependencies" },
        { "label": "Previous agents" }
      ]
    }
  ]
}

```

```

### File Generation with Bash

After collecting all data, the command executes a bash script to assemble the final configuration:

```bash
#!/usr/bin/env bash

# Assemble the collected data into tasks.md

cat <<EOF > .daisy/swarm/tasks.md

# Generated Swarm Tasks

$(for a in "${AGENTS[@]}"; do
  echo "- Agent: ${a[name]}"
  echo "  Role: ${a[role]}"
  echo "  Deps: ${a[deps]}"
done)
EOF

```

This pattern demonstrates how `AskUserQuestion` integrates with other allowed tools like `Bash` and `Write` to create sophisticated, stateful workflows.

## Essential Reference Files

When implementing rich interactions in Claude plugins, consult these specific files in the `anthropics/claude-plugins-official` repository:

- **[`plugins/plugin-dev/skills/command-development/references/interactive-commands.md`](https://github.com/anthropics/claude-plugins-official/blob/main/plugins/plugin-dev/skills/command-development/references/interactive-commands.md)** – Complete reference for `AskUserQuestion` syntax, including conditional flow patterns, multi-select configurations, and error handling strategies.

- **[`plugins/plugin-dev/README.md`](https://github.com/anthropics/claude-plugins-official/blob/main/plugins/plugin-dev/README.md)** – Overview of the Plugin Development Toolkit, specifically the section on combining traditional arguments with interactive questions for progressive disclosure.

- **[`plugins/plugin-dev/skills/plugin-settings/README.md`](https://github.com/anthropics/claude-plugins-official/blob/main/plugins/plugin-dev/skills/plugin-settings/README.md)** – Documentation for persisting wizard results in `.claude/*.local.md` files, enabling commands to skip wizards on subsequent runs.

- **[`plugins/code-simplifier/.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-official/blob/main/plugins/code-simplifier/.claude-plugin/plugin.json)** – Real-world plugin manifest demonstrating proper `allowed-tools` configuration including `AskUserQuestion`.

- **[`plugins/plugin-dev/scripts/validate-settings.sh`](https://github.com/anthropics/claude-plugins-official/blob/main/plugins/plugin-dev/scripts/validate-settings.sh)** – Utility script for validating generated [`.local.md`](https://github.com/anthropics/claude-plugins-official/blob/main/.local.md) configuration files against expected schemas.

## Summary

- **`AskUserQuestion`** is a built-in tool requiring no external dependencies—only front-matter declaration in `allowed-tools`.
- Each call supports 1-4 questions with optional **multi-select** capability via the `multiSelect: true` flag.
- Access user responses through **variable interpolation** using `$answers[index].answer` syntax.
- Implement **conditional flows** by inspecting answers to determine subsequent tool invocations or question chains.
- Support **progressive disclosure** by combining simple command-line arguments with optional interactive wizards for complex configurations.
- Persist wizard outputs to **`.claude/<plugin>.local.md`** files to enable fast repeat invocations.

## Frequently Asked Questions

### What is the maximum number of questions per AskUserQuestion call?

The `AskUserQuestion` tool accepts a JSON payload containing up to four questions in a single invocation. Each question requires a `header`, `question` text, and `options` array. If your workflow requires more than four inputs, chain multiple `AskUserQuestion` calls using conditional logic based on previous answers.

### How do I access user answers in subsequent command steps?

After the tool execution completes, reference answers using markdown variable interpolation with the syntax `$answers[index].answer`, where `index` starts at 0 and corresponds to the question's position in the JSON payload. For multi-select questions, the answer contains all selected labels separated by delimiters, allowing you to use `contains` operators for conditional checks.

### Can I combine traditional arguments with interactive questions?

Yes. According to [`plugins/plugin-dev/README.md`](https://github.com/anthropics/claude-plugins-official/blob/main/plugins/plugin-dev/README.md), commands support progressive disclosure—simple arguments remain available for fast scripted invocations, while the `AskUserQuestion` tool handles complex configuration. Check if arguments are provided; if missing, trigger the interactive wizard instead.

### Where should I store configuration generated by interactive wizards?

Write generated configurations to `.claude/<plugin-name>.local.md` files within the project directory. This convention, documented in the plugin-settings skill, allows commands to detect existing configuration and skip the wizard on subsequent runs, while the [`validate-settings.sh`](https://github.com/anthropics/claude-plugins-official/blob/main/validate-settings.sh) script ensures file integrity.