/prompt-engineering

name: prompt-engineering
description: Optimizes and rewrites prompts using proven prompt engineering techniques — draft diagnosis, canonical structure (role, context+motivation, sequential instructions, XML, few-shot, chain-of-thought, output contract, success criteria), technique selection by task type and by target model (Claude 4.x, OpenAI reasoning/GPT, Gemini). Use when the user says "/prompt-engineering", "improve this prompt", "optimize this prompt", "rewrite this prompt", "apply best practices to this prompt", "turn this into a good prompt", or pastes a prompt draft asking to make it better. Reusable across any project.
license: MIT

Prompt Engineering

Turns a raw draft into a production-grade prompt by applying proven prompt engineering techniques. Distilled from primary sources (Anthropic prompting best practices + prompt improver, OpenAI GPT-5/reasoning guides, Google Gemini PTCF, The Prompt Report) — see `references/` for the full material.

Purpose

The user sends a prompt draft (or describes what they want). The skill returns a **rewritten, optimized version**, ready to paste, plus a **short changelog** of what changed and why. It is not meant to answer the prompt — it is meant to improve the prompt.

Operating principle

• **Improve the prompt, don't run it.** This skill rewrites the prompt; it does not respond to the task the prompt describes. If the request is ambiguous (the user pasted a prompt without saying what they want), the default is to **optimize the prompt** and, at the end, offer to run it. Only execute the task if the user explicitly asks ("run this prompt", "answer this").
• **Produce directly.** Don't ask for permission. Only ask clarifying questions (1–3, max) when missing information would materially change the rewrite — expected output type, target model, or audience. If unanswered, assume the most sensible default, **state the assumption** in the changelog, and proceed.
• **Calibrate effort to complexity.** Simple prompt (lookup, formatting) → lean structural rewrite, no inflating with CoT/examples. Complex prompt (reasoning, classification, generation with criteria, agentic) → full structure. Don't decorate beyond what's needed — prompt over-engineering hurts latency and cost with no gain.
• **If the draft is already good, say so and do the minimum.** Don't invent changes to justify the rewrite. Apply the anti-overengineering rule to yourself: when the prompt already has solid role, structure, scope, and output contract, deliver only the marginal tweaks that genuinely add value and state that the rest was already good. Rewriting a good prompt into something "different but not better" is a failure.
• **Optimize for the right model.** The default is Claude 4.x. If the user indicates another target (GPT/o-series, Gemini), adjust per `references/model-profiles.md` — the rules diverge (e.g. reasoning models do NOT want "think step by step").

Workflow (5 phases)

Inspired by Anthropic's official prompt improver flow (example identification → initial draft → CoT refinement → example enhancement), expanded with diagnosis and technique selection.

Phase 1 — Diagnosis

Extract from the draft (and from conversation context):

• **Real intent:** what the user actually wants the model to produce.
• **Task type:** classification · extraction · generation/writing · coding · reasoning/analysis · research · agentic/tool-use · transformation/summarization · roleplay/persona. (Map in `references/task-patterns.md`.)
• **Target model:** Claude 4.x (default) · OpenAI GPT/reasoning · Gemini · other.
• **Audience and output format:** who reads it, in what form (JSON, prose, bullets, table, code).
• **Constraints and invariants:** hard limits (length, tone, what to never do).
• **Dynamic variables:** parts that change on each call → become `{{placeholders}}`.
• **Draft weaknesses:** ambiguity, negative instruction, missing context/motivation, no success criterion, undefined format, missing or inconsistent examples.

Phase 2 — Technique selection

Pick techniques from the decision table below (detail in `references/techniques.md`). Apply only those that add value to the task. Mentally note the why of each — it goes in the changelog.

Phase 3 — Rewrite

Build the prompt in the **canonical structure** (below), applying the selected techniques and the **golden rules**. Preserve every `{{...}}` variable from the original. Convert negative instructions into positive ones. Add motivation to non-obvious instructions. Mirror the rigor level and the format of the cases in `references/worked-examples.md`.

Phase 4 — Self-review

Run `references/quality-checklist.md` against the rewritten version. Fix whatever fails before delivering. Golden test: *"could a colleague with no context execute this prompt without doubt?"* If not, adjust.

Phase 5 — Delivery

Return in the output format (below): optimized prompt in a copyable block + changelog + open questions (if any). When useful, point to `references/evaluation.md` so the user can A/B test the before/after.

Canonical structure of the optimized prompt

Recommended order (omit sections that don't add value for the task at hand):

1. **Role/persona** — one line defining who the model is and its domain. Focuses tone and behavior. 2. **Task + objective** — what to produce and the success criterion. Outcome-oriented. 3. **Context + motivation** — background information and *why* it matters (the model generalizes from the why). 4. **Data/inputs** — in XML tags. In long-context (20k+ tokens), long data goes **at the top**, before the instructions; the question goes **at the end** (up to +30% quality). 5. **Instructions** — sequential numbered steps when order matters. Positive ("do X"), not negative ("don't do Y"). Explicit scope (Claude 4.x is literal: "apply to ALL sections, not just the first"). 6. **Reasoning** — when the task requires analysis, ask for a `<thinking>`/`<analysis>` block before the answer