when-optimizing-prompts-use-prompt-optimization-analyzer

Prompt Optimization Analyzer

Purpose: Analyze prompt quality and provide actionable optimization recommendations to reduce token waste, improve clarity, and enhance effectiveness.

When to Use This Skill

• Before publishing new skills or slash commands
• When prompts exceed token budgets
• When responses are inconsistent or unclear
• During skill maintenance and refinement
• When analyzing existing prompt libraries

Analysis Dimensions

1. Token Efficiency Analysis

• Redundancy detection (repeated concepts, phrases)
• Verbosity measurement (word count vs. information density)
• Compression opportunities (equivalent shorter forms)
• Example bloat (excessive or redundant examples)

2. Anti-Pattern Detection

• Vague instructions ("do something good")
• Ambiguous terminology (undefined jargon)
• Conflicting requirements (contradictory rules)
• Missing context (insufficient background)
• Over-specification (unnecessary constraints)

3. Trigger Issue Analysis

• Unclear activation conditions
• Overlapping trigger patterns
• Missing edge cases
• Too broad/narrow scope

4. Structural Optimization

• Information architecture (logical flow)
• Section organization (grouping, hierarchy)
• Reference efficiency (cross-references, links)
• Progressive disclosure (layered detail)

Execution Process

Phase 1: Token Waste Detection

# Analyze prompt for redundancy
npx claude-flow@alpha hooks pre-task --description "Analyzing prompt for token waste"

# Store original metrics
npx claude-flow@alpha memory store --key "optimization/original-tokens" --value "{
  \"total_tokens\": <count>,
  \"redundancy_score\": <0-100>,
  \"verbosity_score\": <0-100>
}"

Analysis Script:

// Embedded token analysis
function analyzeTokenWaste(promptText) {
  const metrics = {
    totalWords: promptText.split(/\s+/).length,
    totalChars: promptText.length,
    redundancyScore: 0,
    verbosityScore: 0,
    issues: []
  };

  // Detect phrase repetition
  const phrases = extractPhrases(promptText, 3); // 3-word phrases
  const phraseCounts = countOccurrences(phrases);
  const repeated = Object.entries(phraseCounts).filter(([_, count]) => count > 2);

  if (repeated.length > 0) {
    metrics.redundancyScore += repeated.length * 10;
    metrics.issues.push({
      type: "redundancy",
      severity: "medium",
      count: repeated.length,
      examples: repeated.slice(0, 3).map(([phrase]) => phrase)
    });
  }

  // Measure verbosity
  const avgWordLength = promptText.split(/\s+/)
    .reduce((sum, word) => sum + word.length, 0) / metrics.totalWords;

  if (avgWordLength > 6) {
    metrics.verbosityScore += 20;
    metrics.issues.push({
      type: "verbosity",
      severity: "low",
      avgWordLength: avgWordLength.toFixed(2),
      suggestion: "Consider shorter, clearer words"
    });
  }

  // Detect filler words
  const fillerWords = ["very", "really", "just", "actually", "basically", "simply"];
  const fillerCount = fillerWords.reduce((count, filler) => {
    const regex = new RegExp(`\\b${filler}\\b`, 'gi');
    return count + (promptText.match(regex) || []).length;
  }, 0);

  if (fillerCount > 5) {
    metrics.redundancyScore += fillerCount * 2;
    metrics.issues.push({
      type: "filler-words",
      severity: "low",
      count: fillerCount,
      suggestion: "Remove unnecessary filler words"
    });
  }

  return metrics;
}

function extractPhrases(text, wordCount) {
  const words = text.toLowerCase().split(/\s+/);
  const phrases = [];
  for (let i = 0; i <= words.length - wordCount; i++) {
    phrases.push(words.slice(i, i + wordCount).join(' '));
  }
  return phrases;
}

function countOccurrences(items) {
  return items.reduce((counts, item) => {
    counts[item] = (counts[item] || 0) + 1;
    return counts;
  }, {});
}

Phase 2: Anti-Pattern Detection

Common Anti-Patterns:

1. Vague Instructions
2. ❌ "Make it better"
3. ✅ "Reduce token count by 20% while maintaining clarity"

1. Ambiguous Terminology
2. ❌ "Handle errors appropriately"
3. ✅ "Catch exceptions, log to memory, return user-friendly message"

1. Conflicting Requirements
2. ❌ "Be concise but provide detailed explanations"
3. ✅ "Provide concise summaries with optional detail links"

1. Missing Context
2. ❌ "Use the standard format"
3. ✅ "Use JSON format: {type, severity, description}"

1. Over-Specification
2. ❌ "Always use exactly 4 spaces, never tabs, indent 2 levels..."
3. ✅ "Follow project .editorconfig settings"

Detection Script:

function detectAntiPatterns(promptText) {
  const patterns = [];

  // Vague instruction markers
  const vagueMarkers = ["better", "good", "appropriate", "proper", "suitable"];
  vagueMarkers.forEach(marker => {
    if (new RegExp(`\\b${marker}\\b`, 'i').test(promptText)) {
      patterns.push({
        type: "vague-instruction",
        marker: marker,
        severity: "high",
        suggestion: "Replace with specific, measurable criteria"
      });
    }
  });

  // Missing definitions
  const technicalTerms = promptText.match(/\b[A-Z][A-Za-z]*(?:[A-Z][a-z]*)+\b/g) || [];
  const definedTerms = (promptText.match(/\*\*[^*]+\*\*:/g) || []).length;

  if (technicalTerms.length > 5 && definedTerms < technicalTerms.length * 0.3) {
    patterns.push({
      type: "undefined-jargon",
      severity: "medium",
      technicalTermCount: technicalTerms.length,
      definedCount: definedTerms,
      suggestion: "Add definitions for technical terms"
    });
  }

  // Conflicting modal verbs
  const mustStatements = (promptText.match(/\b(must|required|mandatory)\b/gi) || []).length;
  const shouldStatements = (promptText.match(/\b(should|recommended|optional)\b/gi) || []).length;

  if (mustStatements > 10 && shouldStatements > 10) {
    patterns.push({
      type: "requirement-confusion",
      severity: "medium",
      mustCount: mustStatements,
      shouldCount: shouldStatements,
      suggestion: "Separate MUST vs SHOULD requirements clearly"
    });
  }

  return patterns;
}

Phase 3: Trigger Analysis

function analyzeTriggers(triggerText) {
  const issues = [];

  // Check clarity
  if (!triggerText.includes("when") && !triggerText.includes("if")) {
    issues.push({
      type: "unclear-condition",
      severity: "high",
      suggestion: "Use explicit 'when' or 'if' conditions"
    });
  }

  // Check specificity
  const vagueTerms = ["thing", "stuff", "something", "anything"];
  vagueTerms.forEach(term => {
    if (new RegExp(`\\b${term}\\b`, 'i').test(triggerText)) {
      issues.push({
        type: "vague-trigger",
        term: term,
        severity: "high",
        suggestion: "Replace with specific entity or action"
      });
    }
  });

  // Check scope
  if (triggerText.split(/\s+/).length < 5) {
    issues.push({
      type: "too-narrow",
      severity: "medium",
      wordCount: triggerText.split(/\s+/).length,
      suggestion: "Consider broader applicability"
    });
  }

  return issues;
}

Phase 4: Optimization Recommendations

Code Analyzer Agent Task:

# Spawn analyzer agent
# Agent instructions:
# 1. Analyze prompt structure and flow
# 2. Identify optimization opportunities
# 3. Generate before/after comparisons
# 4. Calculate token savings
# 5. Store recommendations in memory

npx claude-flow@alpha memory store --key "optimization/recommendations" --value "{
  \"structural\": [...],
  \"content\": [...],
  \"examples\": [...],
  \"estimated_savings\": \"X tokens (Y%)\"
}"

Phase 5: Before/After Comparison

Optimization Report Format:

## Prompt Optimization Report

### Original Metrics
- Total tokens: <count>
- Redundancy score: <0-100>
- Verbosity score: <0-100>
- Anti-patterns found: <count>

### Issues Detected

#### High Severity
1. [Type] <description>
   - Location: <section>
   - Impact: <token/clarity impact>
   - Fix: <recommendation>

#### Medium S