• NEVER apply an optimized prompt without showing the user a diff and getting explicit approval.
• NEVER change what a prompt does — only improve how it's expressed.
• NEVER remove or modify tool/function definitions in the prompt.
• NEVER substitute template variables (

  {{variable_name}}

  ) with actual content.
• NEVER run the optimizer repeatedly on the same prompt — optimize once, validate, iterate if needed.
• ALWAYS preserve the original prompt version for rollback.
• ALWAYS recommend

  run-experiment

  to validate the optimization afterward.

• User has reviewed and approved the diff between original and optimized prompt
• New prompt version created on orq.ai (original preserved for rollback)

• run-experiment

  recommended to validate the optimization with A/B testing

• run-experiment

  — validate optimized prompts with A/B experiments

• build-evaluator

  — create evaluators to measure prompt quality

• analyze-trace-failures

  — identify failures that inform prompt optimization

• build-agent

  — if the prompt is for an agent

• "optimize my prompt"
• "improve my system prompt"
• "rewrite my prompt"
• "analyze prompt quality"
• "make my prompt better"
• User has a prompt that needs general improvement
• User asks to optimize, improve, or rewrite a system prompt
• User wants AI-powered analysis of prompt quality

• Have production traces showing failures? → Use

  analyze-trace-failures

  first to identify specific failure patterns, then come back here to apply fixes
• Need to evaluate prompt changes? → Use

  run-experiment

  to A/B test prompt variants with evaluators
• Need to build an agent? → Use

  build-agent

  to create an agent with tool-calling capabilities

Official documentation: Prompt Engineering Guide — Best Practices

1. Role assignment & expertise — Clear, emphasized role with specific domain expertise and qualifications
2. Task definition — Clear explanation of what the system will do
3. Stress induction — Emphasis on the importance and criticality of the task
4. Guidelines — Breakdown of the task into clear guidelines covering: task explanation, behavioral constraints, communication style, knowledge boundaries
5. Output format — Specified and stressed output format. If tools are present, they provide their own format so no additional output format is needed
6. Tool calling — If tools/functions are mentioned, they are part of the task. Never suggest removing tools. Keep tool definitions in their original state but may suggest adjustments to how they're referenced
7. Reasoning — For complex tasks requiring analysis, reasoning must be instructed and must appear before the final answer. If reasoning is instructed but the output format has no space for it, suggest adding one (e.g., a

   reasoning

   key in JSON)
8. Examples — Few-shot examples using

   <example>

   XML tags to demonstrate desired behavior, with proper variable formatting inside
9. Remove unnecessary content — No unnecessary markdown, emojis, XML tags, or contradictions
10. Proper variable usage — Variables with

    {{double curly brackets}}

    should only appear once near the end; earlier references should use XML tags
11. Recap — A one-sentence recap of the task and format at the end of the prompt

AskUserQuestion

• Creating a new prompt version with the optimized prompt
• Modifying a deployment's prompt configuration

• No arguments (

  /optimize-prompt

  ): Start with Phase 2 (Analyze), then Phase 3 (Rewrite)
• With instructions (

  /optimize-prompt make this way more assertive

  ): Skip Phase 2, go straight to Phase 3 using the user's instructions

1. Find and retrieve the target prompt:
   • If the user provided prompt text inline (not referencing an orq.ai prompt by name), skip the search and proceed directly to Phase 2 using the provided text. Skip Phase 4 (Apply) unless the user explicitly asks to save it to orq.ai.
   • Otherwise, use

     search_entities

     with

     type: "prompt"

     to find the target prompt
   • Use HTTP API to get full prompt details including current version text
   • Document: prompt name, current version, system message content, model, parameters
2. Extract the system prompt text for analysis.
   • Important: Template variables in the prompt must be preserved as

     {{variable_name}}

     literally — do NOT substitute the variable content.
   • If the prompt contains tool/function definitions, include them as-is for analysis.

Skip this phase if the user provided specific optimization instructions.

1. Analyze the prompt against the Prompting Guidelines Framework:
   • Evaluate each of the 11 guidelines
   • Identify strengths and weaknesses
   • Generate up to 5 concrete, actionable suggestions for improvement
2. Present analysis to the user:

   ## Prompt Analysis
   
   **Strengths:** [what the prompt does well]
   
   ### Suggestions
   1. [Guideline X] — [specific suggestion]
   2. [Guideline Y] — [specific suggestion]
   3. [Guideline Z] — [specific suggestion]

3. Ask the user which suggestions to apply:
   • User may accept all, select specific ones, or modify suggestions
   • The accepted suggestions become the rewriting instructions for Phase 3

1. Rewrite the prompt based on instructions:
   • If coming from Phase 2: use the accepted suggestions as directives
   • If user provided instructions directly: use those as directives
   • Apply changes while preserving the original intent, persona, and constraints
   • Keep template variables as

     {{variable_name}}

   • Keep tool/function definitions intact
2. Present a diff to the user:
   • Show the original and optimized prompts side by side or as a diff
   • Highlight key changes and which guidelines/instructions they address
   • Ask for user approval before proceeding

1. Create a new prompt version (with user confirmation):
   • Use HTTP API to create a new version on the existing prompt
   • Document the version number and what was optimized
   • Keep the original version intact for rollback
2. Recommend next steps:
   • Suggest using

     run-experiment

     to A/B test the optimized prompt against the original
   • Suggest using

     build-evaluator

     to create evaluators that measure the targeted improvements
   • Suggest monitoring production traces to verify improvement

• View/edit the prompt:

  https://my.orq.ai/prompts

  — review original and optimized versions
• View deployments:

  https://my.orq.ai/deployments

  — update deployment to use the optimized prompt

1. orq MCP tools — query live data first (

   search_entities

   ,

   get_agent

   ); API responses are always authoritative
2. orq.ai documentation MCP — use

   search_orq_ai_documentation

   or

   get_page_orq_ai_documentation

   to look up platform docs programmatically
3. docs.orq.ai — browse official documentation directly
4. This skill file — may lag behind API or docs changes