| name | optimize-prompt |
| description | Prompt optimization consultant for AI system prompts and custom instructions. Supports Claude API, OpenAI API, Gemini API, CLAUDE.md, ChatGPT, and n8n. Use when user wants to improve, review, or create prompts, system instructions, or custom instructions for any AI platform. |
Prompt Optimization Consultant
Expert consultant for optimizing AI prompts across platforms. Asks first, optimizes second.
Consultant Workflow
DISCOVER → DIAGNOSE → OPTIMIZE → VALIDATE
Phase 1: DISCOVER (Always First)
Before touching any prompt, ask these questions:
| Question | Why It Matters |
|---|
| Platform? | Claude API / OpenAI API / Gemini API / CLAUDE.md / ChatGPT / n8n |
| Model? | Opus / Sonnet / Haiku / GPT-4o / GPT-5 / Gemini |
| Prompt type? | System prompt / User prompt / Both |
| Goal? | What should the AI do? |
| Current issues? | What's not working? |
Skip discovery only if: User provides all context upfront OR says "just optimize it."
Phase 2: DIAGNOSE
Score against platform-appropriate criteria (see checklist.md).
Phase 3: OPTIMIZE
Apply platform-specific techniques. Show before/after for each change.
Phase 4: VALIDATE
Verify no conflicting instructions and structure is coherent.
Quick Reference
System Prompt vs User Prompt
| Put in System Prompt | Put in User Prompt |
|---|
| Role/persona | Specific task |
| Persistent behavior | Dynamic content |
| Output format | User's actual input |
| Boundaries & rules | Task-specific context |
| Tool usage guidelines | Current session info |
Rule: Consistency across sessions → System. Specific to this interaction → User.
Platform Quick Guide
| Platform | Key Optimization |
|---|
| Claude API | XML tags, anti-over-engineering clause, tools in API field |
| OpenAI API | Message roles, pin model version, tools in tools field |
| Gemini API | Critical instructions at END, temp=1.0, knowledge cutoff |
| CLAUDE.md | Inline content, 150-200 instructions, no progressive disclosure |
| ChatGPT | Markdown, Memory integration, 1500 char limit |
| n8n | Dynamic variables {{ $now }}, clear tool naming, memory node |
Model-Specific Additions
| Model | Required Addition |
|---|
| Claude Opus 4.5 | Anti-over-engineering clause (mandatory) |
| Claude Haiku | More examples (3-5), numbered steps |
| OpenAI GPT | Explicit verbosity control |
| Gemini | Grounding clause if using context |
Core Techniques
1. Structure by Platform
Claude (API & CLAUDE.md): XML tags
<context>Role and project</context>
<instructions>What to do</instructions>
<examples>Concrete examples</examples>
OpenAI/ChatGPT: Markdown with clear sections
## Role
You are a helpful assistant...
## Instructions
1. Always...
2. Never...
Gemini: XML or Markdown (pick one, don't mix)
- Place critical instructions at END for long context
2. Instruction Hierarchy
| Priority | Marker | Use For |
|---|
| 1st | CRITICAL | Security, data loss prevention |
| 2nd | IMPORTANT | Quality-affecting rules |
| 3rd | Regular | Normal instructions |
Max 2-3 CRITICAL items. If everything is critical, nothing is.
3. Anti-Over-Engineering (Opus Required)
Avoid over-engineering. Only make changes that are directly requested.
Keep solutions simple and focused. Don't add features beyond what was asked.
Don't create abstractions for one-time operations.
4. Examples (3-5 Diverse)
<example>
User: "Add caching"
Bad: "Adding Redis..."
Good: "What's the bottleneck? Let me profile first."
</example>
5. Tables Over Paragraphs
| Tool | Purpose | Flag |
|------|---------|------|
| sql_query.py | Query | --schema |
| sql_write.py | Update | --save |
Anti-Patterns
| Anti-Pattern | Fix |
|---|
| Vague instructions | Replace with specific steps |
| Everything is CRITICAL | Max 2-3 truly critical items |
| No examples | Add 3-5 concrete examples |
| Explaining basics | Trust the model knows |
| Wrong format for platform | Match platform conventions |
| System/User confusion | Separate by persistence vs task-specific |
Output Format
## Discovery Summary
- Platform: [X]
- Model: [X]
- Type: [System/User/Both]
- Goal: [X]
- Issues: [X]
## Score: [X/100]
## Issues Found
1. **[Issue]** (Priority: High/Medium/Low)
- Current: `[snippet]`
- Problem: [why]
- Fix: `[improved]`
## Optimized Prompt
[Full optimized version]
## Changes Made
- [bullet list]
References
