/prompt-wizard - Craft Effective Prompts

An interactive wizard that applies Claude Code best practices to help you craft effective prompts for any task.

Scope Constraints

Read-only conversational skill: interviews user and generates prompt text
Does not read, modify, or create project files
Does not execute code or run any tools beyond user interaction

Input Sanitization

All user inputs (task descriptions, scope, context): free text, reject null bytes
File paths referenced in context: reject .. traversal, null bytes, and shell metacharacters
URLs in external docs: validate well-formed URL format

Modes

1. Create Mode (Default)

Walk through an interview to build a well-structured prompt from scratch.

2. Analyze Mode

Share an existing prompt and get suggestions for improvement.

Interview Flow (Create Mode)

When the user invokes /prompt-wizard, run through these questions using the AskUserQuestion tool. Gather all answers before generating the final prompt.

Step 1: Task Type

Question: "What type of task do you need help with?"

| Option | Description | |--------|-------------| | Feature | Add new functionality | | Bug Fix | Fix broken behavior | | Refactor | Improve code structure | | Test | Write or improve tests | | Documentation | Write docs or comments | | Research | Explore codebase or investigate |

Step 2: Complexity Level

Question: "How complex is this task?"

| Option | Description | |--------|-------------| | Simple | Single file, straightforward change | | Medium | Multiple files, clear requirements | | Complex | Architectural changes, many files | | Unknown | Need to investigate first |

Step 3: Verification Criteria

Question: "How should the result be verified?" (Multi-select)

| Option | Description | |--------|-------------| | Tests pass | Existing or new tests should pass | | Type checks | TypeScript compilation succeeds | | Visual check | UI looks correct in browser | | Manual test | Specific manual verification steps | | Builds successfully | No build errors |

Step 4: Context Gathering

Question: "What context should Claude have?" (Multi-select)

| Option | Description | |--------|-------------| | Specific files | List files Claude should read | | Error messages | Include error output | | Screenshots | Reference visual examples | | External docs | URLs to reference | | Existing patterns | Point to similar code |

Based on selections, ask follow-up questions:

If "Specific files": "Which files should Claude examine?"
If "Error messages": "Please paste the error output"
If "Screenshots": "Provide path or describe what it shows"
If "External docs": "What URLs should Claude reference?"
If "Existing patterns": "Where are similar implementations?"

Step 5: Scope Boundaries

Question: "What should be IN scope for this task?" (Free-form text input)

Question: "What should be OUT of scope?" (optional) (Free-form text input)

Step 6: Additional Materials (Optional)

Question: "Do you have any additional context to share?"

| Option | Description | |--------|-------------| | None | Ready to generate prompt | | Code snippet | Include specific code | | Requirements doc | Link to specs | | Previous attempt | What was tried before |

Generated Prompt Template

After gathering all answers, generate a prompt using this structure:

## Task
[Clear, specific description of what needs to be done]

## Task Type
[Feature/Bug Fix/Refactor/Test/Documentation/Research]

## Context
[Files to read, patterns to follow, relevant background]

## Requirements
- [Specific requirement 1]
- [Specific requirement 2]
- [...]

## In Scope
[What this task includes]

## Out of Scope
[What this task explicitly excludes]

## Verification
[How to verify the task is complete]
- [ ] [Verification step 1]
- [ ] [Verification step 2]

## Additional Context
[Error messages, screenshots, links, etc.]

Analyze Mode

When user shares an existing prompt or says "analyze my prompt":

Analysis Checklist

Evaluate the prompt against these best practices:

Specificity - Is the task clear and specific?
Context - Are relevant files/patterns mentioned?
Scope - Are boundaries defined (in/out of scope)?
Verification - Is there a clear definition of done?
Complexity - Is the scope appropriate (not too broad)?
Actionability - Can Claude start immediately?

Improvement Suggestions

Provide concrete suggestions to improve weak areas:

| Issue | Suggestion | |-------|------------| | Vague task | "Instead of 'fix the bug', try 'fix the login form validation that allows empty emails'" | | No context | "Add: 'Examine src/auth/ for existing patterns'" | | No scope | "Add what's in/out of scope to prevent over-engineering" | | No verification | "Add: 'Verify by running npm test and checking the login UI'" | | Too broad | "Break into smaller tasks: 1) investigate, 2) implement, 3) test" |

Best Practices Applied

This wizard implements patterns from Claude Code best practices:

"Let Claude Interview You" - Structured questions gather complete context
Clear Verification Criteria - Every prompt includes how to verify success
Scope Boundaries - Explicit in/out of scope prevents scope creep
Task Decomposition - Complex tasks broken into manageable pieces
Context Provision - Relevant files and patterns explicitly mentioned

Output Format

## Task
Fix login form to trim whitespace from email input.

## Task Type
Bug Fix

## Context
- Read `src/auth/login.ts` — authentication logic
- Read `src/components/LoginForm.tsx` — form component

## Requirements
- Trim whitespace before validation
- Show error for invalid email format

## Verification
- [ ] Existing tests pass
- [ ] Manual test: login with spaces succeeds

Example Output

Input (from interview)

Task Type: Bug Fix
Complexity: Medium
Verification: Tests pass, Manual test
Context: Specific files (src/auth/login.ts, src/components/LoginForm.tsx)
Error: "Login fails silently when email contains spaces"
In Scope: Fix validation, add error message
Out of Scope: Refactoring auth system, adding new auth methods

Generated Prompt

## Task
Fix the login form to properly handle emails with leading/trailing spaces. Currently, login fails silently when users accidentally include spaces in their email.

## Task Type
Bug Fix

## Context
- Read `src/auth/login.ts` - authentication logic
- Read `src/components/LoginForm.tsx` - form UI component
- Follow existing validation patterns in these files

## Requirements
- Trim whitespace from email input before validation
- Show clear error message if email format is invalid
- Preserve existing validation for other fields

## In Scope
- Fix email validation in login form
- Add user-facing error message for invalid emails

## Out of Scope
- Refactoring the auth system
- Adding new authentication methods
- Changing the form styling

## Verification
- [ ] Existing tests pass (`npm test`)
- [ ] Manual test: Login with " user@example.com " (spaces) succeeds
- [ ] Manual test: Invalid email shows error message
- [ ] No TypeScript errors

## Additional Context
**Error reproduction:**
1. Go to /login
2. Enter " test@example.com " (with spaces)
3. Click login - fails silently with no error message

Gotchas

Overly specific file context ("read all 47 files in src/") causes Claude to spend tokens on irrelevant code — list only the 3-5 most relevant files
Too many verification criteria (10+ checkboxes) dilutes focus — keep to 3-5 critical verification steps
Vague scope boundaries ("don't change too much") are unenforceable — be explicit: "Only modify files in src/auth/"
Including error messages without reproduction steps wastes debugging time — always pair errors with exact steps to reproduce
Prompts that describe the solution instead of the problem constrain Claude's approach — state the desired outcome, not the implementation

Usage

# Start the wizard
/prompt-wizard

# Analyze an existing prompt
/prompt-wizard analyze
# Then paste your prompt when asked