dtsong /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