prompt-engineer

name	prompt-engineer
description	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. Use when you say "optimize this prompt", "improve this system prompt", or "review my agent prompt".
license	MIT
metadata	null
version	1.0.0

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

Triggers

Trigger Phrase	Operation
optimize this prompt	Full Phase 0-4 optimization workflow
improve this system prompt	Analyze and propose changes with visual cards
review my agent prompt	Pattern-based review against reference
refine this prompt for better results	Targeted improvement with BEFORE/AFTER
make this prompt more effective	Technique selection and application

---

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.

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)

Anti-Patterns

Avoid	Why	Instead
Applying techniques without reading reference first	Missing trigger conditions and constraints	Always read reference documents before analysis
Rewriting entire prompt	Destroys what already works	Preserve working sections, improve problems only
Skipping user approval before changes	May misidentify improvement priorities	Present visual cards in Phase 2, wait for approval
Stacking conflicting techniques	Produces contradictory instructions	Check stacking compatibility per reference
Using more than 3 emphasis markers	Dilutes signal when everything is emphasized	Reserve emphasis for highest-priority instructions

---

Verification

After optimization:

• Reconciliation: paste the count of visual cards presented in Phase 2 and confirm each card named its reference trigger condition (not a claim: list the card titles here)
• No section contradicts another section
• User approved Phase 2 plan before Phase 3 execution (paste the approval message or turn reference)
• Anti-patterns section consulted, none introduced
• Reconciliation: count emphasis markers (** or __) in the optimized prompt; paste the count -- must be <= 3

---

References

• prompt-engineering-single-turn.md - Single-turn patterns
• prompt-engineering-multi-turn.md - Multi-turn patterns
• workflow.md - Detailed phase workflows and card template
• prompting-anti-patterns.md - Anti-pattern catalog with effective replacements
• prompting-ai-detection-cliff.md - AI detection cliff and why more rules increase detectability