how-to-guide

Implementing Rich Interactions in Claude Plugins: Interactive Wizard Development

March 13, 2026 anthropics/claude-plugins-official ↗

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.

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

According to the reference documentation in 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.

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

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 demonstrates a complete three-question workflow that collects deployment preferences and generates a persistent configuration file.

Collecting Deployment Preferences

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


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

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

{
  "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 – Complete reference for AskUserQuestion syntax, including conditional flow patterns, multi-select configurations, and error handling strategies.
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 – 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 – Real-world plugin manifest demonstrating proper allowed-tools configuration including AskUserQuestion.
plugins/plugin-dev/scripts/validate-settings.sh – Utility script for validating generated .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, 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 script ensures file integrity.

Have a question about this repo?

These articles cover the highlights, but your codebase questions are specific. Give your agent direct access to the source. Share this with your agent to get started:

Share the following with your agent to get started:

curl -s "https://instagit.com/install.md"

Add to your MCP client configuration:

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}

Ask your agent:

"Use Instagit MCP to understand how anthropics/claude-plugins-official works."

Works with

Claude Codex Cursor VS Code OpenClaw Any MCP Client

Maintain an open-source project? Get it listed too →