Prompt Optimizer

This skill optimizes system prompts for Claude Code agents by applying proven prompt engineering patterns from production systems.

When to Use This Skill

Use this skill when:

• •User provides a prompt and requests optimization
• •User asks for prompt improvement or refinement
• •User wants to apply best practices to agent instructions
• •User needs help with tool-use prompts or workflow automation

Process Overview

This skill uses a two-phase optimization approach:

Phase 1: Section-by-Section Analysis

• •Decompose the prompt into logical sections
• •Analyze each section independently
• •Apply relevant patterns with explicit attribution
• •Present findings per section

Phase 2: Full-Pass Integration

• •Review the complete optimized prompt holistically
• •Ensure cross-section coherence
• •Eliminate redundancies
• •Verify global consistency

Required Resources

Before beginning optimization, ALWAYS read:

references/prompt-engineering.md

This file contains the complete catalog of prompt engineering patterns that MUST be applied during optimization.

Phase 1: Section-by-Section Optimization

Step 1: Decompose the Prompt

Break the prompt into logical sections. Common sections include:

• •Role Definition: Who/what the agent is
• •Core Capabilities: What the agent can do
• •Tool Instructions: How to use specific tools
• •Constraints: What the agent must not do
• •Output Format: How to structure responses
• •Safety Instructions: Security and safety guidelines
• •Workflow Automation: Multi-step procedures
• •Examples: Demonstrations of correct behavior
• •Error Handling: How to handle failures

Not all prompts will have all sections. Identify what exists in the provided prompt.

Step 2: Analyze Each Section

For each section identified:

1. •State the section name and current content
2. •Identify applicable patterns from prompt-engineering.md
3. •For EACH proposed change:
   • •Pattern name (e.g., "Progressive Disclosure")
   • •Why this pattern applies here
   • •Expected behavioral impact
   • •Show the specific change (before/after)

CRITICAL: Every change must have explicit pattern attribution. Changes without attribution are incomplete.

Step 3: Present Section Analysis

Present findings in this format:

## Section: [Section Name]

### Current Content
[Original text]

### Applied Patterns

#### Change 1
**Pattern**: [Pattern Name from prompt-engineering.md]
**Rationale**: [Why this pattern applies]
**Impact**: [Expected behavioral change]
**Change**:
Before: [original text]
After: [optimized text]

#### Change 2
[Same structure...]

Step 4: Handle Pattern Conflicts

When multiple patterns could apply to the same text, present options:

### Pattern Conflict Detected

**Context**: [Section and text in question]

**Option A**: [Pattern Name]
- Application: [How it would be applied]
- Benefits: [What it achieves]
- Trade-offs: [What you might lose]

**Option B**: [Pattern Name]
- Application: [How it would be applied]
- Benefits: [What it achieves]
- Trade-offs: [What you might lose]

**Recommendation**: [Which option and why]

Ask the user which approach they prefer before proceeding.

Phase 2: Full-Pass Integration

After completing section-by-section optimization and receiving user approval:

Step 1: Assemble the Optimized Prompt

Combine all optimized sections into a complete prompt.

Step 2: Global Analysis

Review the complete prompt for:

1. •Cross-section coherence: Do sections work together harmoniously?
2. •Redundancy elimination: Are any instructions repeated unnecessarily?
3. •Consistency: Do all sections use consistent terminology and style?
4. •Flow: Does the prompt follow a logical progression?
5. •Completeness: Are there gaps between sections?

Step 3: Apply Global Patterns

Identify and apply patterns that only become apparent at the full-prompt level:

• •Emphasis Hierarchy: Are the most critical instructions properly emphasized?
• •Progressive Disclosure: Does complexity increase appropriately?
• •Rule Hierarchies: Are there conflicting priorities that need ordering?
• •Default Behaviors: Are failure modes and edge cases handled?

Step 4: Present Final Optimization

Present the complete optimized prompt with:

## Final Optimized Prompt

[Complete optimized prompt]

## Global Changes Applied

### Change 1
**Pattern**: [Pattern Name]
**Rationale**: [Why this global pattern was needed]
**Impact**: [Expected improvement]
**Sections Affected**: [Which sections were modified]

[Additional global changes...]

## Summary

**Total Changes**: [Number]
**Patterns Applied**: [List of unique patterns used]
**Key Improvements**: [3-5 bullet points of major improvements]

Quality Checklist

Before presenting the final optimized prompt, verify:

• • Every change has explicit pattern attribution
• • No section contradicts another section
• • Critical instructions use appropriate emphasis (CAPITAL, NEVER/ALWAYS, etc.)
• • Examples are provided where complexity is high
• • Anti-patterns are explicitly called out where relevant
• • Safety-critical operations have verbose instructions
• • Output format requirements are unambiguous
• • Tool usage hierarchies are clear
• • Default behaviors are specified for edge cases
• • The prompt follows progressive disclosure principles

Best Practices

Token Efficiency

• •Remove redundant explanations
• •Use concise examples over verbose descriptions
• •Consolidate related instructions

Behavioral Clarity

• •Use imperative voice ("Use X" not "You should use X")
• •State absolutes clearly (NEVER, ALWAYS, MUST)
• •Provide specific examples for complex behaviors

Safety and Reliability

• •Longer instructions for dangerous operations
• •Explicit anti-patterns for common mistakes
• •Clear error handling procedures

Pattern Application Discipline

DO:

• •Apply multiple patterns per section when beneficial
• •Explain why each pattern is appropriate
• •Show concrete before/after examples
• •Consider the user's specific use case

DON'T:

• •Apply patterns mechanically without rationale
• •Change text without identifying the pattern used
• •Assume patterns are obvious (always attribute)
• •Optimize for optimization's sake (preserve working patterns)

Notes

• •This process is systematic but not mechanical. Use judgment about which patterns provide value for the specific prompt.
• •When the user's prompt already uses a pattern well, acknowledge it rather than changing it.
• •Focus attribution on changes, not on what was already done well.
• •If the user requests specific optimizations (e.g., "make it more concise"), prioritize those patterns while maintaining completeness.