surshar / claude-code

Claude Code is an agentic coding tool that lives in your terminal, understands your codebase, and helps you code faster by executing routine tasks, explaining complex code, and handling git workflows - all through natural language commands.

Built by Anthropic · github.com/anthropics

claude-code / plugins / plugin-dev / skills / command-development / references / interactive-commands.md

Daisy S. HollmanMerge pull request #11780 from anthropics/daisy/plugin-dev/public-marketplace c508e59 · on Nov 18, 2025 History

920 lines · 20.5 KBPreview CodeRaw

1	# Interactive Command Patterns
2
3	Comprehensive guide to creating commands that gather user feedback and make decisions through the AskUserQuestion tool.
4
5	## Overview
6
7	Some commands need user input that doesn't work well with simple arguments. For example:
8	- Choosing between multiple complex options with trade-offs
9	- Selecting multiple items from a list
10	- Making decisions that require explanation
11	- Gathering preferences or configuration interactively
12
13	For these cases, use the AskUserQuestion tool within command execution rather than relying on command arguments.
14
15	## When to Use AskUserQuestion
16
17	### Use AskUserQuestion When:
18
19	1. Multiple choice decisions with explanations needed
20	2. Complex options that require context to choose
21	3. Multi-select scenarios (choosing multiple items)
22	4. Preference gathering for configuration
23	5. Interactive workflows that adapt based on answers
24
25	### Use Command Arguments When:
26
27	1. Simple values (file paths, numbers, names)
28	2. Known inputs user already has
29	3. Scriptable workflows that should be automatable
30	4. Fast invocations where prompting would slow down
31
32	## AskUserQuestion Basics
33
34	### Tool Parameters
35
36	```typescript
37	{
38	questions: [
39	{
40	question: "Which authentication method should we use?",
41	header: "Auth method", // Short label (max 12 chars)
42	multiSelect: false, // true for multiple selection
43	options: [
44	{
45	label: "OAuth 2.0",
46	description: "Industry standard, supports multiple providers"
47	},
48	{
49	label: "JWT",
50	description: "Stateless, good for APIs"
51	},
52	{
53	label: "Session",
54	description: "Traditional, server-side state"
55	}
56	]
57	}
58	]
59	}
60	```
61
62	Key points:
63	- Users can always choose "Other" to provide custom input (automatic)
64	- `multiSelect: true` allows selecting multiple options
65	- Options should be 2-4 choices (not more)
66	- Can ask 1-4 questions per tool call
67
68	## Command Pattern for User Interaction
69
70	### Basic Interactive Command
71
72	```markdown
73	---
74	description: Interactive setup command
75	allowed-tools: AskUserQuestion, Write
76	---
77
78	# Interactive Plugin Setup
79
80	This command will guide you through configuring the plugin with a series of questions.
81
82	## Step 1: Gather Configuration
83
84	Use the AskUserQuestion tool to ask:
85
86	Question 1 - Deployment target:
87	- header: "Deploy to"
88	- question: "Which deployment platform will you use?"
89	- options:
90	- AWS (Amazon Web Services with ECS/EKS)
91	- GCP (Google Cloud with GKE)
92	- Azure (Microsoft Azure with AKS)
93	- Local (Docker on local machine)
94
95	Question 2 - Environment strategy:
96	- header: "Environments"
97	- question: "How many environments do you need?"
98	- options:
99	- Single (Just production)
100	- Standard (Dev, Staging, Production)
101	- Complete (Dev, QA, Staging, Production)
102
103	Question 3 - Features to enable:
104	- header: "Features"
105	- question: "Which features do you want to enable?"
106	- multiSelect: true
107	- options:
108	- Auto-scaling (Automatic resource scaling)
109	- Monitoring (Health checks and metrics)
110	- CI/CD (Automated deployment pipeline)
111	- Backups (Automated database backups)
112
113	## Step 2: Process Answers
114
115	Based on the answers received from AskUserQuestion:
116
117	1. Parse the deployment target choice
118	2. Set up environment-specific configuration
119	3. Enable selected features
120	4. Generate configuration files
121
122	## Step 3: Generate Configuration
123
124	Create `.claude/plugin-name.local.md` with:
125
126	\`\`\`yaml
127	---
128	deployment_target: [answer from Q1]
129	environments: [answer from Q2]
130	features:
131	auto_scaling: [true if selected in Q3]
132	monitoring: [true if selected in Q3]
133	ci_cd: [true if selected in Q3]
134	backups: [true if selected in Q3]
135	---
136
137	# Plugin Configuration
138
139	Generated: [timestamp]
140	Target: [deployment_target]
141	Environments: [environments]
142	\`\`\`
143
144	## Step 4: Confirm and Next Steps
145
146	Confirm configuration created and guide user on next steps.
147	```
148
149	### Multi-Stage Interactive Workflow
150
151	```markdown
152	---
153	description: Multi-stage interactive workflow
154	allowed-tools: AskUserQuestion, Read, Write, Bash
155	---
156
157	# Multi-Stage Deployment Setup
158
159	This command walks through deployment setup in stages, adapting based on your answers.
160
161	## Stage 1: Basic Configuration
162
163	Use AskUserQuestion to ask about deployment basics.
164
165	Based on answers, determine which additional questions to ask.
166
167	## Stage 2: Advanced Options (Conditional)
168
169	If user selected "Advanced" deployment in Stage 1:
170
171	Use AskUserQuestion to ask about:
172	- Load balancing strategy
173	- Caching configuration
174	- Security hardening options
175
176	If user selected "Simple" deployment:
177	- Skip advanced questions
178	- Use sensible defaults
179
180	## Stage 3: Confirmation
181
182	Show summary of all selections.
183
184	Use AskUserQuestion for final confirmation:
185	- header: "Confirm"
186	- question: "Does this configuration look correct?"
187	- options:
188	- Yes (Proceed with setup)
189	- No (Start over)
190	- Modify (Let me adjust specific settings)
191
192	If "Modify", ask which specific setting to change.
193
194	## Stage 4: Execute Setup
195
196	Based on confirmed configuration, execute setup steps.
197	```
198
199	## Interactive Question Design
200
201	### Question Structure
202
203	Good questions:
204	```markdown
205	Question: "Which database should we use for this project?"
206	Header: "Database"
207	Options:
208	- PostgreSQL (Relational, ACID compliant, best for complex queries)
209	- MongoDB (Document store, flexible schema, best for rapid iteration)
210	- Redis (In-memory, fast, best for caching and sessions)
211	```
212
213	Poor questions:
214	```markdown
215	Question: "Database?" // Too vague
216	Header: "DB" // Unclear abbreviation
217	Options:
218	- Option 1 // Not descriptive
219	- Option 2
220	```
221
222	### Option Design Best Practices
223
224	Clear labels:
225	- Use 1-5 words
226	- Specific and descriptive
227	- No jargon without context
228
229	Helpful descriptions:
230	- Explain what the option means
231	- Mention key benefits or trade-offs
232	- Help user make informed decision
233	- Keep to 1-2 sentences
234
235	Appropriate number:
236	- 2-4 options per question
237	- Don't overwhelm with too many choices
238	- Group related options
239	- "Other" automatically provided
240
241	### Multi-Select Questions
242
243	When to use multiSelect:
244
245	```markdown
246	Use AskUserQuestion for enabling features:
247
248	Question: "Which features do you want to enable?"
249	Header: "Features"
250	multiSelect: true // Allow selecting multiple
251	Options:
252	- Logging (Detailed operation logs)
253	- Metrics (Performance monitoring)
254	- Alerts (Error notifications)
255	- Backups (Automatic backups)
256	```
257
258	User can select any combination: none, some, or all.
259
260	When NOT to use multiSelect:
261
262	```markdown
263	Question: "Which authentication method?"
264	multiSelect: false // Only one auth method makes sense
265	```
266
267	Mutually exclusive choices should not use multiSelect.
268
269	## Command Patterns with AskUserQuestion
270
271	### Pattern 1: Simple Yes/No Decision
272
273	```markdown
274	---
275	description: Command with confirmation
276	allowed-tools: AskUserQuestion, Bash
277	---
278
279	# Destructive Operation
280
281	This operation will delete all cached data.
282
283	Use AskUserQuestion to confirm:
284
285	Question: "This will delete all cached data. Are you sure?"
286	Header: "Confirm"
287	Options:
288	- Yes (Proceed with deletion)
289	- No (Cancel operation)
290
291	If user selects "Yes":
292	Execute deletion
293	Report completion
294
295	If user selects "No":
296	Cancel operation
297	Exit without changes
298	```
299
300	### Pattern 2: Multiple Configuration Questions
301
302	```markdown
303	---
304	description: Multi-question configuration
305	allowed-tools: AskUserQuestion, Write
306	---
307
308	# Project Configuration Setup
309
310	Gather configuration through multiple questions.
311
312	Use AskUserQuestion with multiple questions in one call:
313
314	Question 1:
315	- question: "Which programming language?"
316	- header: "Language"
317	- options: Python, TypeScript, Go, Rust
318
319	Question 2:
320	- question: "Which test framework?"
321	- header: "Testing"
322	- options: Jest, PyTest, Go Test, Cargo Test
323	(Adapt based on language from Q1)
324
325	Question 3:
326	- question: "Which CI/CD platform?"
327	- header: "CI/CD"
328	- options: GitHub Actions, GitLab CI, CircleCI
329
330	Question 4:
331	- question: "Which features do you need?"
332	- header: "Features"
333	- multiSelect: true
334	- options: Linting, Type checking, Code coverage, Security scanning
335
336	Process all answers together to generate cohesive configuration.
337	```
338
339	### Pattern 3: Conditional Question Flow
340
341	```markdown
342	---
343	description: Conditional interactive workflow
344	allowed-tools: AskUserQuestion, Read, Write
345	---
346
347	# Adaptive Configuration
348
349	## Question 1: Deployment Complexity
350
351	Use AskUserQuestion:
352
353	Question: "How complex is your deployment?"
354	Header: "Complexity"
355	Options:
356	- Simple (Single server, straightforward)
357	- Standard (Multiple servers, load balancing)
358	- Complex (Microservices, orchestration)
359
360	## Conditional Questions Based on Answer
361
362	If answer is "Simple":
363	- No additional questions
364	- Use minimal configuration
365
366	If answer is "Standard":
367	- Ask about load balancing strategy
368	- Ask about scaling policy
369
370	If answer is "Complex":
371	- Ask about orchestration platform (Kubernetes, Docker Swarm)
372	- Ask about service mesh (Istio, Linkerd, None)
373	- Ask about monitoring (Prometheus, Datadog, CloudWatch)
374	- Ask about logging aggregation
375
376	## Process Conditional Answers
377
378	Generate configuration appropriate for selected complexity level.
379	```
380
381	### Pattern 4: Iterative Collection
382
383	```markdown
384	---
385	description: Collect multiple items iteratively
386	allowed-tools: AskUserQuestion, Write
387	---
388
389	# Collect Team Members
390
391	We'll collect team member information for the project.
392
393	## Question: How many team members?
394
395	Use AskUserQuestion:
396
397	Question: "How many team members should we set up?"
398	Header: "Team size"
399	Options:
400	- 2 people
401	- 3 people
402	- 4 people
403	- 6 people
404
405	## Iterate Through Team Members
406
407	For each team member (1 to N based on answer):
408
409	Use AskUserQuestion for member details:
410
411	Question: "What role for team member [number]?"
412	Header: "Role"
413	Options:
414	- Frontend Developer
415	- Backend Developer
416	- DevOps Engineer
417	- QA Engineer
418	- Designer
419
420	Store each member's information.
421
422	## Generate Team Configuration
423
424	After collecting all N members, create team configuration file with all members and their roles.
425	```
426
427	### Pattern 5: Dependency Selection
428
429	```markdown
430	---
431	description: Select dependencies with multi-select
432	allowed-tools: AskUserQuestion
433	---
434
435	# Configure Project Dependencies
436
437	## Question: Required Libraries
438
439	Use AskUserQuestion with multiSelect:
440
441	Question: "Which libraries does your project need?"
442	Header: "Dependencies"
443	multiSelect: true
444	Options:
445	- React (UI framework)
446	- Express (Web server)
447	- TypeORM (Database ORM)
448	- Jest (Testing framework)
449	- Axios (HTTP client)
450
451	User can select any combination.
452
453	## Process Selections
454
455	For each selected library:
456	- Add to package.json dependencies
457	- Generate sample configuration
458	- Create usage examples
459	- Update documentation
460	```
461
462	## Best Practices for Interactive Commands
463
464	### Question Design
465
466	1. Clear and specific: Question should be unambiguous
467	2. Concise header: Max 12 characters for clean display
468	3. Helpful options: Labels are clear, descriptions explain trade-offs
469	4. Appropriate count: 2-4 options per question, 1-4 questions per call
470	5. Logical order: Questions flow naturally
471
472	### Error Handling
473
474	```markdown
475	# Handle AskUserQuestion Responses
476
477	After calling AskUserQuestion, verify answers received:
478
479	If answers are empty or invalid:
480	Something went wrong gathering responses.
481
482	Please try again or provide configuration manually:
483	[Show alternative approach]
484
485	Exit.
486
487	If answers look correct:
488	Process as expected
489	```
490
491	### Progressive Disclosure
492
493	```markdown
494	# Start Simple, Get Detailed as Needed
495
496	## Question 1: Setup Type
497
498	Use AskUserQuestion:
499
500	Question: "How would you like to set up?"
501	Header: "Setup type"
502	Options:
503	- Quick (Use recommended defaults)
504	- Custom (Configure all options)
505	- Guided (Step-by-step with explanations)
506
507	If "Quick":
508	Apply defaults, minimal questions
509
510	If "Custom":
511	Ask all available configuration questions
512
513	If "Guided":
514	Ask questions with extra explanation
515	Provide recommendations along the way
516	```
517
518	### Multi-Select Guidelines
519
520	Good multi-select use:
521	```markdown
522	Question: "Which features do you want to enable?"
523	multiSelect: true
524	Options:
525	- Logging
526	- Metrics
527	- Alerts
528	- Backups
529
530	Reason: User might want any combination
531	```
532
533	Bad multi-select use:
534	```markdown
535	Question: "Which database engine?"
536	multiSelect: true // ❌ Should be single-select
537
538	Reason: Can only use one database engine
539	```
540
541	## Advanced Patterns
542
543	### Validation Loop
544
545	```markdown
546	---
547	description: Interactive with validation
548	allowed-tools: AskUserQuestion, Bash
549	---
550
551	# Setup with Validation
552
553	## Gather Configuration
554
555	Use AskUserQuestion to collect settings.
556
557	## Validate Configuration
558
559	Check if configuration is valid:
560	- Required dependencies available?
561	- Settings compatible with each other?
562	- No conflicts detected?
563
564	If validation fails:
565	Show validation errors
566
567	Use AskUserQuestion to ask:
568
569	Question: "Configuration has issues. What would you like to do?"
570	Header: "Next step"
571	Options:
572	- Fix (Adjust settings to resolve issues)
573	- Override (Proceed despite warnings)
574	- Cancel (Abort setup)
575
576	Based on answer, retry or proceed or exit.
577	```
578
579	### Build Configuration Incrementally
580
581	```markdown
582	---
583	description: Incremental configuration builder
584	allowed-tools: AskUserQuestion, Write, Read
585	---
586
587	# Incremental Setup
588
589	## Phase 1: Core Settings
590
591	Use AskUserQuestion for core settings.
592
593	Save to `.claude/config-partial.yml`
594
595	## Phase 2: Review Core Settings
596
597	Show user the core settings:
598
599	Based on these core settings, you need to configure:
600	- [Setting A] (because you chose [X])
601	- [Setting B] (because you chose [Y])
602
603	Ready to continue?
604
605	## Phase 3: Detailed Settings
606
607	Use AskUserQuestion for settings based on Phase 1 answers.
608
609	Merge with core settings.
610
611	## Phase 4: Final Review
612
613	Present complete configuration.
614
615	Use AskUserQuestion for confirmation:
616
617	Question: "Is this configuration correct?"
618	Options:
619	- Yes (Save and apply)
620	- No (Start over)
621	- Modify (Edit specific settings)
622	```
623
624	### Dynamic Options Based on Context
625
626	```markdown
627	---
628	description: Context-aware questions
629	allowed-tools: AskUserQuestion, Bash, Read
630	---
631
632	# Context-Aware Setup
633
634	## Detect Current State
635
636	Check existing configuration:
637	- Current language: !`detect-language.sh`
638	- Existing frameworks: !`detect-frameworks.sh`
639	- Available tools: !`check-tools.sh`
640
641	## Ask Context-Appropriate Questions
642
643	Based on detected language, ask relevant questions.
644
645	If language is TypeScript:
646
647	Use AskUserQuestion:
648
649	Question: "Which TypeScript features should we enable?"
650	Options:
651	- Strict Mode (Maximum type safety)
652	- Decorators (Experimental decorator support)
653	- Path Mapping (Module path aliases)
654
655	If language is Python:
656
657	Use AskUserQuestion:
658
659	Question: "Which Python tools should we configure?"
660	Options:
661	- Type Hints (mypy for type checking)
662	- Black (Code formatting)
663	- Pylint (Linting and style)
664
665	Questions adapt to project context.
666	```
667
668	## Real-World Example: Multi-Agent Swarm Launch
669
670	From multi-agent-swarm plugin:
671
672	```markdown
673	---
674	description: Launch multi-agent swarm
675	allowed-tools: AskUserQuestion, Read, Write, Bash
676	---
677
678	# Launch Multi-Agent Swarm
679
680	## Interactive Mode (No Task List Provided)
681
682	If user didn't provide task list file, help create one interactively.
683
684	### Question 1: Agent Count
685
686	Use AskUserQuestion:
687
688	Question: "How many agents should we launch?"
689	Header: "Agent count"
690	Options:
691	- 2 agents (Best for simple projects)
692	- 3 agents (Good for medium projects)
693	- 4 agents (Standard team size)
694	- 6 agents (Large projects)
695	- 8 agents (Complex multi-component projects)
696
697	### Question 2: Task Definition Approach
698
699	Use AskUserQuestion:
700
701	Question: "How would you like to define tasks?"
702	Header: "Task setup"
703	Options:
704	- File (I have a task list file ready)
705	- Guided (Help me create tasks interactively)
706	- Custom (Other approach)
707
708	If "File":
709	Ask for file path
710	Validate file exists and has correct format
711
712	If "Guided":
713	Enter iterative task creation mode (see below)
714
715	### Question 3: Coordination Mode
716
717	Use AskUserQuestion:
718
719	Question: "How should agents coordinate?"
720	Header: "Coordination"
721	Options:
722	- Team Leader (One agent coordinates others)
723	- Collaborative (Agents coordinate as peers)
724	- Autonomous (Independent work, minimal coordination)
725
726	### Iterative Task Creation (If "Guided" Selected)
727
728	For each agent (1 to N from Question 1):
729
730	Question A: Agent Name
731	Question: "What should we call agent [number]?"
732	Header: "Agent name"
733	Options:
734	- auth-agent
735	- api-agent
736	- ui-agent
737	- db-agent
738	(Provide relevant suggestions based on common patterns)
739
740	Question B: Task Type
741	Question: "What task for [agent-name]?"
742	Header: "Task type"
743	Options:
744	- Authentication (User auth, JWT, OAuth)
745	- API Endpoints (REST/GraphQL APIs)
746	- UI Components (Frontend components)
747	- Database (Schema, migrations, queries)
748	- Testing (Test suites and coverage)
749	- Documentation (Docs, README, guides)
750
751	Question C: Dependencies
752	Question: "What does [agent-name] depend on?"
753	Header: "Dependencies"
754	multiSelect: true
755	Options:
756	- [List of previously defined agents]
757	- No dependencies
758
759	Question D: Base Branch
760	Question: "Which base branch for PR?"
761	Header: "PR base"
762	Options:
763	- main
764	- staging
765	- develop
766
767	Store all task information for each agent.
768
769	### Generate Task List File
770
771	After collecting all agent task details:
772
773	1. Ask for project name
774	2. Generate task list in proper format
775	3. Save to `.daisy/swarm/tasks.md`
776	4. Show user the file path
777	5. Proceed with launch using generated task list
778	```
779
780	## Best Practices
781
782	### Question Writing
783
784	1. Be specific: "Which database?" not "Choose option?"
785	2. Explain trade-offs: Describe pros/cons in option descriptions
786	3. Provide context: Question text should stand alone
787	4. Guide decisions: Help user make informed choice
788	5. Keep concise: Header max 12 chars, descriptions 1-2 sentences
789
790	### Option Design
791
792	1. Meaningful labels: Specific, clear names
793	2. Informative descriptions: Explain what each option does
794	3. Show trade-offs: Help user understand implications
795	4. Consistent detail: All options equally explained
796	5. 2-4 options: Not too few, not too many
797
798	### Flow Design
799
800	1. Logical order: Questions flow naturally
801	2. Build on previous: Later questions use earlier answers
802	3. Minimize questions: Ask only what's needed
803	4. Group related: Ask related questions together
804	5. Show progress: Indicate where in flow
805
806	### User Experience
807
808	1. Set expectations: Tell user what to expect
809	2. Explain why: Help user understand purpose
810	3. Provide defaults: Suggest recommended options
811	4. Allow escape: Let user cancel or restart
812	5. Confirm actions: Summarize before executing
813
814	## Common Patterns
815
816	### Pattern: Feature Selection
817
818	```markdown
819	Use AskUserQuestion:
820
821	Question: "Which features do you need?"
822	Header: "Features"
823	multiSelect: true
824	Options:
825	- Authentication
826	- Authorization
827	- Rate Limiting
828	- Caching
829	```
830
831	### Pattern: Environment Configuration
832
833	```markdown
834	Use AskUserQuestion:
835
836	Question: "Which environment is this?"
837	Header: "Environment"
838	Options:
839	- Development (Local development)
840	- Staging (Pre-production testing)
841	- Production (Live environment)
842	```
843
844	### Pattern: Priority Selection
845
846	```markdown
847	Use AskUserQuestion:
848
849	Question: "What's the priority for this task?"
850	Header: "Priority"
851	Options:
852	- Critical (Must be done immediately)
853	- High (Important, do soon)
854	- Medium (Standard priority)
855	- Low (Nice to have)
856	```
857
858	### Pattern: Scope Selection
859
860	```markdown
861	Use AskUserQuestion:
862
863	Question: "What scope should we analyze?"
864	Header: "Scope"
865	Options:
866	- Current file (Just this file)
867	- Current directory (All files in directory)
868	- Entire project (Full codebase scan)
869	```
870
871	## Combining Arguments and Questions
872
873	### Use Both Appropriately
874
875	Arguments for known values:
876	```markdown
877	---
878	argument-hint: [project-name]
879	allowed-tools: AskUserQuestion, Write
880	---
881
882	Setup for project: $1
883
884	Now gather additional configuration...
885
886	Use AskUserQuestion for options that require explanation.
887	```
888
889	Questions for complex choices:
890	```markdown
891	Project name from argument: $1
892
893	Now use AskUserQuestion to choose:
894	- Architecture pattern
895	- Technology stack
896	- Deployment strategy
897
898	These require explanation, so questions work better than arguments.
899	```
900
901	## Troubleshooting
902
903	Questions not appearing:
904	- Verify AskUserQuestion in allowed-tools
905	- Check question format is correct
906	- Ensure options array has 2-4 items
907
908	User can't make selection:
909	- Check option labels are clear
910	- Verify descriptions are helpful
911	- Consider if too many options
912	- Ensure multiSelect setting is correct
913
914	Flow feels confusing:
915	- Reduce number of questions
916	- Group related questions
917	- Add explanation between stages
918	- Show progress through workflow
919
920	With AskUserQuestion, commands become interactive wizards that guide users through complex decisions while maintaining the clarity that simple arguments provide for straightforward inputs.