prompt-optimizer

Optimize system prompts for Claude Code agents using proven prompt engineering patterns. Use when users request prompt improvement, optimization, or refinement for agent workflows, tool instructions, or system behaviors.

⭐3stars🔀0forks📁View on GitHub🕐Updated Jan 4, 2026⬇️1downloads

When & Why to Use This Skill

This Claude skill provides a professional framework for optimizing system prompts for AI agents using research-backed prompt engineering patterns. It focuses on enhancing behavioral clarity, managing task complexity, and ensuring instructions are grounded in proven methodologies to improve agent performance, reliability, and tool-use accuracy.

Use Cases

  • Refining complex agent system prompts to resolve behavioral contradictions and improve edge-case handling in autonomous workflows.
  • Optimizing tool-use instructions and API interaction logic to ensure agents select the correct tools and parameters consistently.
  • Applying research-backed patterns to existing prompts to reduce 'overthinking' in simple tasks while maintaining depth for complex reasoning.
  • Systematically reviewing and upgrading legacy prompts to align with the latest Claude model capabilities and industry-standard best practices.
  • Decomposing multi-step agent workflows into clear, manageable instructions to prevent instruction-following degradation.
nameprompt-engineer
descriptionOptimize system prompts for Claude Code agents using proven prompt engineering patterns. Use when users request prompt improvement, optimization, or refinement for agent workflows, tool instructions, or system behaviors.
licenseMIT
version1.0.0
modelclaude-sonnet-4-5

Prompt Optimizer

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

Purpose and Success Criteria

A well-optimized prompt achieves:

  1. Behavioral clarity: Agent knows exactly what to do in common cases and edge cases
  2. Appropriate scope: Complex tasks get decomposition; simple tasks don't trigger overthinking
  3. Grounded changes: Every modification traces to a specific pattern with documented 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)
  • 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
  • Non-prompt content (documentation, code, etc.)

Required Resources

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

Single-Turn Reference (Always Read)

Read references/prompt-engineering-single-turn.md

Contains: Technique Selection Guide table, Quick Reference principles, domain-organized techniques with citations, Anti-Patterns section.

Multi-Turn Reference (Conditional)

Read references/prompt-engineering-multi-turn.md

Read ONLY when the prompt involves:

  • Multi-turn flows (iterative refinement, conversation chains)
  • Multi-agent / sub-agent orchestration

Skip for:

  • Static system prompts executed in a single LLM call
  • Tool instructions or one-shot prompts

Workflow Reference

Read references/workflow.md

Contains: Detailed Phase 0-4 workflows, visual card template, completion checkpoint.

Quick Process

┌─────────────────────────────────────────────────────────────────┐
│ 1. READ THE REFERENCE(S)                                        │
│    - Always: references/prompt-engineering-single-turn.md       │
│    - If multi-turn/multi-agent: also read multi-turn reference  │
├─────────────────────────────────────────────────────────────────┤
│ 2. UNDERSTAND THE PROMPT (Phase 1)                              │
│    - Operating context (single-shot? tool-use? constraints?)    │
│    - Current state (working? unclear? missing?)                 │
│    - Document specific problems with quoted prompt text         │
├─────────────────────────────────────────────────────────────────┤
│ 3. PLAN WITH VISUAL CARDS (Phase 2)                             │
│    - Present each change as a visual card with:                 │
│      SCOPE → PROBLEM → TECHNIQUE → BEFORE/AFTER                 │
│    - Quote trigger conditions from reference                    │
│    - ⚠️  WAIT FOR USER APPROVAL before proceeding               │
├─────────────────────────────────────────────────────────────────┤
│ 4. EXECUTE APPROVED CHANGES (Phase 3)                           │
│    - Apply the BEFORE → AFTER transformations                   │
├─────────────────────────────────────────────────────────────────┤
│ 5. INTEGRATE AND VERIFY QUALITY (Phase 4)                       │
│    - Check cross-section coherence                              │
│    - Final anti-pattern check                                   │
│    - Present complete optimized prompt                          │
└─────────────────────────────────────────────────────────────────┘

Triage (Phase 0)

Simple prompts (use lightweight process):

  • Under 20 lines
  • Single clear purpose
  • No conditional logic

Complex prompts (use full process):

  • Multiple sections serving different functions
  • Conditional behaviors or rule hierarchies
  • Tool orchestration or multi-step workflows

Core Quality Principles

  1. Quote before deciding: Every technique selection must quote the reference's trigger condition.
  2. Open verification questions: Ask "What behavior will this produce?" not "Is this correct?"
  3. Approval happens once, upfront: The visual card format in Phase 2 shows full impact.
  4. Preserve what works: Optimization means improving problems, not rewriting everything.

Completion Checkpoint

Before presenting the final prompt, verify:

  • Phase 2 plan used visual card format with BEFORE/AFTER
  • Phase 2 plan quoted trigger conditions from reference
  • Phase 2 plan was approved by user before Phase 3
  • No technique applied without matching trigger condition
  • Stacking compatibility checked; no conflicts
  • Anti-patterns section consulted; none introduced
  • Emphasis markers used sparingly (≤3 highest-level)

References