/prompt-optimizer

name: prompt-optimizer
description: Analyze and optimize user prompts for clarity, specificity, and completeness using interactive questionnaires or direct analysis. Use this skill when user requests are vague, ambiguous, incomplete, or lack necessary details. Supports two modes - Interactive Mode (uses AskUserQuestion tool for guided clarification) and Direct Analysis Mode (provides optimization suggestions). Triggers on prompts containing vague language like "something", "thing", "stuff", "it", or when requests lack context, technical specifications, success criteria, or examples. When user requests interactive/questionnaire mode, use AskUserQuestion to guide them through structured questions. Helps transform unclear requests into well-structured, actionable prompts.
allowed-tools: AskUserQuestion

Prompt Optimizer

This skill analyzes user prompts and provides optimized versions that are clearer, more specific, and more actionable.

Purpose

Transform vague, incomplete, or ambiguous user requests into well-structured prompts that lead to better outcomes. By analyzing prompts against quality criteria and providing optimized versions, this skill helps users communicate their needs more effectively.

When to Use This Skill

Use this skill when user prompts exhibit one or more of these issues:

Clarity Issues

• Vague language: "something", "thing", "stuff", "it", "this"
• Ambiguous pronouns without clear referents
• Multiple possible interpretations
• Unclear desired outcome

Specificity Issues

• Missing context about the problem domain
• No technical specifications (language, framework, version)
• Lack of examples when examples would help
• Undefined scope or boundaries

Completeness Issues

• Missing required information or inputs
• No success criteria defined
• Undefined behavior for edge cases
• Missing constraints or requirements

Structure Issues

• Disorganized information
• Complex requests without clear structure
• Mixing context with requests
• No logical flow

Actionability Issues

• No clear action verb or request
• Passive voice making intent unclear
• Confusing or conflicting instructions
• Missing output format specification

Activation Triggers

Activate this skill when detecting:

• Vague words: "something", "thing", "stuff", "it", "this", "that"
• Quality indicators: "better", "good", "nice" (without criteria)
• Incomplete requests: "help with...", "can you...", "fix..." (without details)
• Overly broad requests: "build an app", "create a system"
• Missing specifications in technical requests
• Requests without clear success criteria

Analysis Workflow

**Two modes available:**

Mode 1: Interactive Questionnaire (Recommended for Complex Requests)

Use the AskUserQuestion tool to guide users through structured questions. This collaborative approach helps users clarify their needs step-by-step.

**When to use**: Medium to complex requests, or when user prefers guided interaction.

Mode 2: Direct Analysis (Fast)

Analyze the prompt and provide suggested improvements in one response.

**When to use**: Simple optimization needs, or when user wants quick results.

**Default**: Start with Mode 2 (Direct Analysis). If user requests interactive mode or if the request is very complex, switch to Mode 1.

---

Mode 2: Direct Analysis Workflow

Step 1: Receive and Read the Prompt

Carefully read the user's original prompt to understand their intent.

Step 2: Identify Issues

Systematically check for issues using `references/optimization-principles.md`:

**Clarity Check**:

• Is the language specific and concrete?
• Are all terms clearly defined?
• Is there only one reasonable interpretation?

**Specificity Check**:

• Is sufficient context provided?
• Are technical requirements specified?
• Are examples included when helpful?

**Completeness Check**:

• Is all necessary information present?
• Are success criteria defined?
• Are edge cases considered?

**Structure Check**:

• Is information organized logically?
• Is the request easy to parse?
• Is context separated from the task?

**Actionability Check**:

• Is there a clear action requested?
• Is the output format specified?
• Are instructions unambiguous?

Step 3: Categorize Issues

List all identified issues by category:

• Clarity problems: [list]
• Specificity gaps: [list]
• Completeness deficiencies: [list]
• Structure issues: [list]
• Actionability concerns: [list]

Step 4: Generate Optimized Prompt

Create an improved version following these principles:

**Add Specificity**:

• Replace vague terms with concrete descriptions
• Add missing technical specifications
• Include relevant context

**Improve Clarity**:

• Use clear, unambiguous language
• Define all terms
• Eliminate multiple interpretations

**Ensure Completeness**:

• Add missing requirements
• Define success criteria
• Specify constraints

**Enhance Structure**:

• Organize information logically
• Use bullet points and sections
• Separate context from task

**Make Actionable**:

• Start with clear action verb
• Specify output format
• Provide concrete deliverables

Reference `references/optimization-principles.md` for patterns and examples.

Step 5: Present Analysis

Provide a structured response:

1. **Original Prompt**: Show the user's original request

2. **Identified Issues**: List specific problems found

• Categorized by type
• Brief explanation of each

3. **Optimized Prompt**: Provide improved version

• Well-structured
• Complete
• Actionable

4. **Key Improvements**: Highlight main changes

• What was added
• What was clarified
• Why it's better

5. **Optional**: Offer to refine further or proceed with the optimized prompt

---

Mode 1: Interactive Questionnaire Workflow

When User Requests Interactive Mode

If the user explicitly asks for interactive/questionnaire mode, or if the prompt has multiple complex issues, use this workflow.

Step 1: Quick Initial Analysis

Qu