prompt-optimizer

Prompt Optimizer

Optimizes system prompts by applying research-backed prompt engineering patterns. This skill operates through human-in-the-loop phases: understand, plan, propose changes, receive approval, then integrate.

Purpose and Success Criteria

A well-optimized prompt achieves three things:

1. Behavioral clarity: The agent knows exactly what to do in common cases and how to handle edge cases.
2. Appropriate scope: Complex tasks get systematic decomposition; simple tasks don't trigger overthinking.
3. Grounded changes: Every modification traces to a specific pattern with documented behavioral impact.

Optimization is complete when:

• Every change has explicit pattern attribution from the reference document
• No section contradicts another section
• The prompt matches its operating context (tool-use vs. conversational, token constraints, failure modes)
• Human has approved both section-level changes and full integration

When to Use This Skill

Use when the user provides a prompt and wants it improved, refined, or reviewed for best practices.

Do NOT use for:

• Writing prompts from scratch (different skill)
• Prompts that are already working well and user just wants validation (say so, don't force changes)
• Non-prompt content (documentation, code, etc.)

Required Resources

Before ANY analysis, read the appropriate pattern reference(s):

Single-Turn Reference (Always Read)

references/prompt-engineering-single-turn.md

This contains the complete catalog of single-turn patterns, including:

• The Technique Selection Guide table (maps domains, trigger conditions, stacking compatibility, conflicts, and expected effects)
• The Quick Reference: Key Principles (numbered list of foundational techniques)
• Domain-organized technique sections with research citations and examples
• The Anti-Patterns to Avoid section documenting common failure modes

Multi-Turn Reference (Conditional)

references/prompt-engineering-multi-turn.md

Read this reference ONLY when the prompt involves:

• Multi-turn flows: Scripts or systems that inject prompts accumulating on a shared context (e.g., iterative refinement loops, conversation chains where previous outputs become subsequent inputs)
• Multi-agent / sub-agent orchestration: Parent/child agent patterns, agent handoffs, or workflows where one agent's output feeds into another agent's prompt

Skip this reference for:

• Static system prompts executed in a single LLM call
• Tool instructions or one-shot prompts
• Prompts that don't involve message accumulation or agent coordination

The multi-turn document covers techniques like Self-Refine, Chain-of-Verification, Universal Self-Consistency, and Multi-Chain Reasoning—patterns that exploit deliberate self-examination across multiple passes.

---

All technique selection decisions must be grounded in these references. Do not apply patterns from memory or general knowledge—consult the appropriate reference to ensure accuracy and to surface stacking/conflict information.

---

Phase 0: Triage

Not every prompt needs the full optimization process. Before proceeding, assess complexity.

Simple prompts (use lightweight process):

• Under 20 lines
• Single clear purpose (one tool, one behavior)
• No conditional logic or branching
• No inter-section dependencies

Complex prompts (use full process):

• Multiple sections serving different functions
• Conditional behaviors or rule hierarchies
• Tool orchestration or multi-step workflows
• Known failure modes that need addressing

Lightweight Process (Simple Prompts)

For simple prompts, skip section decomposition. Instead:

1. Read the prompt once, identify its purpose
2. Consult the reference's Anti-Patterns section to check for obvious problems
3. Consult the Technique Selection Guide to identify 1-3 applicable patterns
4. Propose targeted changes with pattern attribution
5. Present the optimized prompt directly

Do not over-engineer simple prompts.

Full Process (Complex Prompts)

Proceed to Phase 1.

---

Phase 1: Understand the Prompt

Before decomposing or modifying anything, understand what the prompt is trying to accomplish and the context in which it operates. This understanding phase is essential—without it, technique selection becomes guesswork.

Answer these questions (internally, not presented to user unless clarification needed):

1.1 Operating Context

• Interaction model: Is this single-shot (tool description, one-time instruction) or conversational (back-and-forth with user)?
• Agent type: Tool-use agent, coding agent, analysis agent, or general assistant?
• Token constraints: Is brevity critical, or is thoroughness more important?
• Failure modes: What goes wrong when this prompt fails? What behaviors is it trying to prevent?

1.2 Current State Assessment

• What's working: Which parts of the prompt are clear and effective? (Preserve these.)
• What's unclear: Which instructions are ambiguous or could be misinterpreted?
• What's missing: Are there obvious gaps—edge cases unhandled, examples absent, priorities unclear?

1.3 Document Observations

Before consulting the reference, write down specific observations about problems in the prompt. Examples of observable problems:

• "Lines 12-15 use hedging language ('might want to', 'could try')"
• "No examples provided for the expected output format"
• "Multiple rules marked CRITICAL with no clear precedence"
• "Instructions say what NOT to do but don't specify what TO do"

These observations become the input to technique selection in Phase 2.

---

Phase 2: Plan — Select Techniques from Reference

With the prompt understood and problems documented, consult the reference to devise a plan.

2.1 Ground Technique Selection in the Reference

For each problem identified in Phase 1.3, locate the relevant technique in the reference document and quote the specific text that justifies applying it. This grounding step prevents pattern-shopping and ensures accurate application.

For each candidate technique, extract from the reference:

### Technique: [Name]

**Quoted trigger condition**: "[exact text from Technique Selection Guide]"

**Quoted effect**: "[exact text describing behavioral impact]"

**Stacks with**: [list from reference]
**Conflicts with**: [list from reference]

**Problem this addresses**: [your observation from Phase 1.3]

**Why this matches**: [explain how the trigger condition matches the observed problem]

This quote-first approach forces commitment to specific evidence before reasoning about application. If you cannot quote a trigger condition that matches your observed problem, do not apply the technique.

2.2 Verify Technique Selection

Before finalizing the plan, verify each selection by asking yourself open verification questions (not yes/no questions, which bias toward confirmation):

• "What specific text in the prompt matches this technique's trigger condition?"
• "What is the expected behavioral change from applying this technique?"
• "Which other techniques does this conflict with, and am I applying any of them?"
• "What does the Anti-Patterns section say about related failure modes?"

If you cannot answer these questions by pointing to specific text in the reference or the prompt, reconsider the technique selection.

2.3 Present the Plan for User Approval (Visual Card Layout)

Present each proposed change as a visually distinct "card" using ASCII box drawing. This format prioritizes scannability—the user should grasp scope, problem, and proposed fix at a glance before approving.

Wait for explicit approval before proceeding to Phase 3.

Card Template:

╔══════════════════════════════════════════════════════════════════════════════╗
║  CHANGE N: [Short title - what this change does]                             ║
╠══════════════════════════════════════════════════════════════════════════════╣
║                                                                              ║
║  SCOPE                                                                       ║
║  ─────                                                                       ║
║  Prompt:      [prompt name or "multi-prompt: A → B"]                         ║
║  Section:     [which part of the prompt]                                     ║
║  Downstream:  [what depends on this output, or "none"]                       ║
║                                                                              ║
╠══════════════════════════════════════════════════════════════════════════════╣
║                                                                              ║
║  PROBLEM                                                                     ║
║  ───────                                                                     ║
║  Issue:    [One sentence - what's wrong]                                     ║
║                                                                              ║
║  Evidence: "[quoted problematic text from the prompt]"                       ║
║                                                                              ║
║  Runtime:  [What the user actually sees - concrete failure behavior]         ║
║                                                                              ║
╠══════════════════════════════════════════════════════════════════════════════╣
║                                                                              ║
║  TECHNIQUE                                                                   ║
║  ─────────                                                                   ║
║  Apply:    [Technique name from reference]                                   ║
║                                                                              ║
║  Trigger:  "[quoted trigger condition from reference]"                       ║
║  Effect:   "[quoted ex

---

*Content truncated.*