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:
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)

```text
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)

```text
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

```text
Read references/workflow.md
```

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

## Process

```text
┌─────────────────────────────────────────────────────────────────┐
│ 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](references/prompt-engineering-single-turn.md) - Single-turn patterns
- [prompt-engineering-multi-turn.md](references/prompt-engineering-multi-turn.md) - Multi-turn patterns
- [workflow.md](references/workflow.md) - Detailed phase workflows and card template
- [prompting-anti-patterns.md](references/prompting-anti-patterns.md) - Anti-pattern catalog with effective replacements
- [prompting-ai-detection-cliff.md](references/prompting-ai-detection-cliff.md) - AI detection cliff and why more rules increase detectability