prompt-optimization-analyzer

name	prompt-optimization-analyzer
description	Active diagnostic tool for analyzing skill prompts to identify token waste, anti-patterns, trigger issues, and optimization opportunities. Use when reviewing skill prompts, debugging why skills aren't triggering, optimizing token usage, or preparing skills for publication. Provides specific, actionable suggestions with examples.

Prompt Optimization Analyzer

When to Use This Skill

Always use when:

• User asks to "review", "analyze", "optimize", or "improve" a skill prompt
• User says a skill "isn't triggering" or "isn't working as expected"
• User wants to "reduce token usage" in a skill
• User is "preparing a skill for publication" or sharing
• User asks "why isn't my skill being called?"
• User wants to "compare" two skill prompt versions

Consider using when:

• User shares a skill file for any reason (offer to analyze)
• User mentions a skill is "using too many tokens"
• User describes confusing or inconsistent skill behavior

---

Analysis Framework

Run each skill prompt through this comprehensive diagnostic checklist. Report findings in order of severity (Critical → High → Medium → Low).

1. Trigger Pattern Analysis

Critical Issues:

• ❌ Missing or extremely vague description field
• ❌ Description doesn't match actual skill capabilities
• ❌ No clear trigger patterns identifiable from description
• ❌ Trigger patterns overlap heavily with other common skills

High Priority:

• ⚠️ Description is too generic ("helps with tasks", "assists users")
• ⚠️ Trigger keywords buried in long description
• ⚠️ Missing key verbs or nouns that users would naturally use
• ⚠️ Ambiguous scope (could apply to too many or too few situations)

Optimization Opportunities:

• 💡 Could add explicit trigger examples to description
• 💡 Could make description more action-oriented
• 💡 Could add domain-specific terminology
• 💡 Could clarify when NOT to use skill

Good Patterns:

• ✅ Description starts with clear trigger context
• ✅ Includes specific verbs that map to user intent
• ✅ Provides clear scope boundaries
• ✅ Uses "Use when..." or "This skill should be used when..." patterns

---

2. Token Efficiency Analysis

Token Waste Patterns:

Redundancy:

• 🔴 Repeating the same concept in multiple ways without adding clarity
• 🔴 Restating information already in the description
• 🔴 Duplicate examples that teach the same pattern
• 🔴 Verbose explanations where concise language would work

Example - Before (wasteful):

This skill helps you create documents. It's useful for document creation.
When you need to make a document, this skill can help. Documents that can
be created include reports, letters, and memos.

Example - After (efficient):

Creates professional documents including reports, letters, and memos.

Over-Politeness:

• 🔴 Excessive apologetic language ("please", "kindly", "if you don't mind")
• 🔴 Unnecessary hedging ("might", "perhaps", "possibly") where direct instruction works
• 🔴 Filler phrases ("it should be noted that", "it's important to mention")

Example - Before:

You might want to perhaps consider possibly using this approach if you think it could help.

Example - After:

Use this approach when [specific condition].

Bloated Structure:

• 🔴 Excessive nested XML tags when flat structure would work
• 🔴 Long prose explanations where bullet points are clearer
• 🔴 Including "meta" instructions about the skill itself (usually unnecessary)
• 🔴 Detailed explanations of concepts Claude already knows

Over-Specified Formatting:

• 🔴 Dictating exact phrasing for every possible response
• 🔴 Template sentences that reduce flexibility
• 🔴 Formatting rules that don't materially impact quality

Efficiency Checklist:

• Calculate estimated token count (rough: 1 token ≈ 4 characters)
• Identify sections that could be condensed by 30%+
• Flag any paragraph longer than 100 words for review
• Look for opportunities to replace prose with structured format

---

3. Anti-Pattern Detection

Reference the prompting-pattern-library skill for detailed anti-patterns. Key failures to check:

Ambiguity Failures:

• ❌ Unclear success criteria ("make it better", "improve quality")
• ❌ Vague output format requirements
• ❌ Ambiguous scope ("explain X" without audience/depth specification)
• ❌ Undefined technical terms or jargon

Conflicting Instructions:

• ❌ "Be concise but comprehensive"
• ❌ "Be creative but follow strict rules"
• ❌ "Be formal but conversational"
• ❌ Multiple competing priorities without clear hierarchy

Implicit Assumptions:

• ❌ Assuming Claude knows context not provided in skill
• ❌ Assuming knowledge beyond training cutoff
• ❌ Assuming familiarity with domain-specific processes
• ❌ Assuming Claude can access external state/memory

Over-Constraint:

• ❌ So many rules that quality suffers (rule count > 20 is warning sign)
• ❌ Micro-managing phrasing instead of outcomes
• ❌ Restricting Claude's reasoning ability unnecessarily
• ❌ Specifying implementation details instead of desired results

Under-Specification:

• ❌ No examples for complex or novel tasks
• ❌ Missing error handling guidance
• ❌ No quality criteria defined
• ❌ Unclear edge case handling

---

4. Clarity and Structure Review

Structural Issues:

• ⚠️ No clear sections or organization (wall of text)
• ⚠️ Instructions scattered throughout instead of logically grouped
• ⚠️ Missing or unclear headers
• ⚠️ Poor information hierarchy (important stuff buried)
• ⚠️ Inconsistent formatting (switching between styles)

Language Clarity:

• ⚠️ Overly complex sentences (25+ words frequently)
• ⚠️ Passive voice where active is clearer
• ⚠️ Abstract concepts without concrete examples
• ⚠️ Technical jargon without definitions
• ⚠️ Pronouns with unclear antecedents

Better Patterns:

• ✅ Use imperative voice ("Create X" not "You should create X")
• ✅ One instruction per sentence when possible
• ✅ Concrete examples alongside abstract rules
• ✅ Consistent terminology throughout
• ✅ Clear section headers that preview content

---

5. Example Quality Assessment

Poor Examples:

• ❌ Examples that don't demonstrate the core pattern
• ❌ Overly simple examples that miss edge cases
• ❌ Examples without explanation of why they work
• ❌ Too many examples teaching the same thing
• ❌ Examples using outdated syntax or practices

High-Quality Examples:

• ✅ Show before/after or good/bad contrasts
• ✅ Include "why this works" explanations
• ✅ Cover common edge cases
• ✅ Demonstrate key patterns concisely
• ✅ Realistic scenarios (not toy problems)

Example Count:

• 0 examples: Usually needs at least 1-2 for complex tasks
• 1-3 examples: Usually optimal
• 4-6 examples: Carefully evaluate if all are necessary
• 7+ examples: Almost always contains redundancy

---

6. Special Pattern Checks

Tool Usage Instructions:

• ⚠️ Are tool-calling instructions actually necessary?
• ⚠️ Does skill over-specify when Claude should know?
• ⚠️ Are there instructions about tools Claude doesn't have access to?

Meta-Instructions:

• ⚠️ Instructions about "how to use this skill" (usually redundant with description)
• ⚠️ Explaining skill's purpose inside the skill (already in description)
• ⚠️ Documentation for documentation's sake

Conditional Logic:

• ⚠️ Complex if/then trees that Claude can reason about independently
• ⚠️ Edge case handling that duplicates Claude's reasoning
• ⚠️ Over-specified decision trees (trust Claude's judgment more)

---

Output Format

Structure analysis results as follows:

Skill Overview

• Name: [skill name]
• Estimated token count: [rough estimate]
• Overall assessment: [1-2 sentence summary]

Critical Issues (Must Fix)

[List any critical problems that will prevent skill from working]

High Priority Improvements

[List significant improvements that will materially help]

Token Optimization Opportunities

[Specific sections/patterns that waste tokens with estimates]

• Section X: ~[N] tokens could be saved by [specific change]
• Pattern Y: ~[N] tokens wasted on [specific issue]

Medium Priority Suggestions

[Helpful improvements that aren't urgent]

Low Priority Polish

[Nice-to-haves that would marginally improve]

Rewrite Suggestions

[For any section with critical issues, provide rewritten version]

Before (X tokens):

[original text]

After (Y tokens, Z% reduction):

[optimized text]

Estimated Impact

• Total potential token savings: ~[N] tokens ([X]%)
• Clarity improvement: [Significant/Moderate/Minor]
• Trigger reliability: [Better/Same/Need testing]

---

Analysis Process

1. First Pass - Skim

   • Get overall sense of skill purpose
   • Check description field first
   • Note structure and organization
   • Flag any obvious red flags

2. Second Pass - Deep Dive

   • Run through each checklist section systematically
   • Mark specific line numbers or sections with issues
   • Count approximate tokens in bloated sections
   • Identify patterns (don't just note individual issues)

3. Third Pass - Synthesize

   • Prioritize findings by severity and impact
   • Group related issues together
   • Prepare concrete rewrite examples for worst sections
   • Calculate potential savings

4. Output Generation

   • Start with most critical issues
   • Be specific (quote exact text, give line numbers)
   • Provide rewrites, not just criticism
   • Estimate token impacts
   • Balance criticism with recognition of what works well

---

Key Principles

Be Specific

❌ "The description could be better" ✅ "The description 'helps with tasks' is too vague. Suggest: 'Analyzes code quality metrics and suggests refactoring priorities for Python codebases'"

Show Impact

❌ "This section is redundant" ✅ "Lines 45-78 repeat concepts from lines 12-23, wasting ~120 tokens (18% of skill)"

Provide Solutions

❌ "This doesn't work" ✅ "This doesn't work because [reason]. Instead, try: [concrete rewrite]"

Respect Intent

• Understand what the skill author was trying to achieve
• Preserve core functionality while optimizing
• Don't just delete - replace with better alternatives
• Acknowledge trade-offs in suggestions

Context Matters

• A 2000-token skill for complex workflows may be appropriate
• A 2000-token skill for simple formatting is bloated
• Judge efficiency relative to task complexity
• Consider how frequently skill will be triggered

---

Common Optimization Wins

Quick Wins (Usually Save 20-40% Tokens)

1. Remove Meta-Commentary Delete sections explaining the skill to Claude (Claude will read and understand)

2. Condense Verbose Prose Replace paragraphs with bullet points, remove filler words

3. Consolidate Examples Replace 5 similar examples with 2 contrasting examples

4. Trust Claude's Reasoning Remove over-specified decision trees and edge case handling

5. Simplify Structure Flatten unnecessary XML nesting, remove redundant headers

Deep Optimizations (Can Save 40-60% Tokens)

1. Rewrite Entire Sections Take bloated sections and rewrite from scratch focusing on clarity

2. Remove Implicit Instructions Delete instructions about things Claude already knows how to do

3. Consolidate Redundant Concepts Merge sections teaching the same pattern multiple ways

4. Streamline Tool Instructions Trust Claude's tool-use abilities more, remove over-specification

5. Clarify Over Adding Instead of adding more examples/explanation, clarify existing content

---

Red Flags for Common Skill Issues

"My skill isn't triggering"

Check:

1. Description too vague or generic?
2. Description doesn't mention key trigger words?
3. Skill scope overlaps too much with existing skills?
4. Trigger pattern requires exact phrasing user won't say?

"My skill triggers too often"

Check:

1. Description too broad ("helps with writing")?
2. Missing scope boundaries or exclusions?
3. Generic trigger words that match many queries?
4. Need more specific domain terminology?

"My skill gives inconsistent results"

Check:

1. Conflicting instructions?
2. Ambiguous success criteria?
3. Too many conditional branches?
4. Under-specified output requirements?

"My skill seems slow"

Check:

1. Token count >2000? (high context load)
2. Requesting Claude read multiple large references?
3. Over-complicated reasoning chains?
4. Excessive examples or edge case handling?

---

Reference Integration

This skill works alongside:

• prompting-pattern-library: Reference for patterns and anti-patterns
• token-budget-advisor: Assess if skill fits within token budgets
• skill-creator: Guidelines for building skills initially
• learning-capture: Identify patterns from analysis to capture

When analyzing prompts, reference the prompting-pattern-library for detailed pattern explanations. Focus this skill on active diagnosis and concrete suggestions.

---

Limitations and Caveats

What this skill can't do:

• Guarantee a skill will trigger in all desired situations (triggering is complex)
• Test actual skill performance (requires real usage)
• Determine if skill logic is correct for domain (needs domain expertise)
• Predict user behavior or query patterns

Best used for:

• Identifying clear anti-patterns and inefficiencies
• Suggesting specific improvements with examples
• Estimating token costs and optimization potential
• Catching common failure modes before publication

Remember:

• Analysis is a starting point, not gospel
• Some verbose skills are appropriately complex
• User intent matters more than arbitrary token targets
• Test optimized versions to ensure they still work correctly