Prompt Engineering

Prompt Engineering — a working reference

> Sources: the DeepLearning.AI course "ChatGPT Prompt Engineering for Developers" (the base) + Anthropic's guides "Prompting best practices" / "Effective context engineering" + current OpenAI GPT-5.x prompting guides (5.5, April 2026: "re-baseline your prompts for the new model, don't drag along your old prescriptive stack") + Anthropic's essay "Building Effective Agents" + practice. Updated as I learn.

The core intuition: the model doesn't read minds (whatever isn't stated explicitly, it will either invent or NOT do) and the model only "thinks" in what it prints (there's no internal scratchpad — the reasoning tokens are the thinking).

Reference files alongside this one (read them as needed, not always): PATTERNS.md — reasoning models, reasoning patterns (ReAct, Reflexion, CoVe…), formatting (CAPS/markdown/emoji), curing a bloated prompt; EVAL-JUDGE.md — evals, the iterative loop, LLM-as-judge, DSPy; TOOLS.md — tooling (Console, Promptfoo, Langfuse…).

---

Principle 1 — clear, specific instructions ("clear" ≠ "short")

• Delimiters / XML tags. Any extraneous text (input data, examples, context documents) goes in delimiters: ` , """, `, :::, **XML tags (preferred for complex prompts)**. Why: (a) the model can tell where the instruction ends and the data begins; (b) protection against prompt injection — text inside a block is treated as data, not as a command. Use consistent, meaningful tag names (, , , ); nest them for hierarchy (…`).
• Numbered steps when order or completeness of steps matters.
• Structured output. If the result feeds code — specify the format explicitly. See "Modern standards → Structured Outputs."
• Condition checks. If an assumption might not hold, have the model check and say so ("if there are no steps — reply 'No steps found'") instead of inventing.
• Context helps. Explain who/what the result is for — the model calibrates tone, level of detail, and vocabulary.
• Don't leave the model freedom where you have requirements. Edge cases, what counts as what — spell them out.

Principle 2 — let the model reason before answering

• Spell out the steps. Not "solve the task" but "step 1: …, step 2: …, … , finally, the answer." Intermediate steps in the output are the model's thinking.
• ⚠️ An error/loss at an early step propagates to all the following ones (f(g(x)) — a corrupted g can't be saved).
• ⚠️ The order of steps in the prompt = the order of the model's thinking. That's a lever: e.g. put "count N in the source text" BEFORE "summarize", otherwise it counts on the summary.
• If you only need the clean final result — "reason first, then put the final answer in ...", and extract the tag in code. Or two requests.
• Self-check before the final answer. Add at the end: "before you finish, check the answer against [criteria/tests]." Reliably catches errors, especially in code and math.
• Let it solve first, then evaluate. "Check the student's solution" → the model gets lazy and says "correct." The fix: "first solve the problem yourself, from scratch, without looking at the given solution; then compare; only draw a conclusion afterward." You need an independent answer to compare against, not "look at yours and agree."
• "Think twice" (for ordinary, NON-reasoning models): self-consistency (N independent runs with temperature>0 → the majority answer; helps on tasks with one correct answer, at ×N tokens), reflection/self-refine (answer → critique → fix; careful: the model tends to confirm itself). Use in moderation.
• Reasoning models (GPT-5.x reasoning with reasoning.effort, Claude extended thinking) think on their own — don't duplicate "think step by step", the lever is the effort level. Details: see PATTERNS.md § "Literalness and reasoning."

Hallucinations

The model always wants to give a plausible answer, even when it doesn't know. To reduce them: (a) for long-document tasks — first ask it to quote the relevant chunks, then answer from those; (b) explicitly allow "not enough information"; (c) give it context ← the idea behind RAG; (d) tell it not to invent facts/APIs/links that aren't in the input.

---

Prompt anatomy (the skeleton)

Not every block is always needed; when a prompt "doesn't work" it's usually missing one of these:

1. Role / context — who you are, who/what we're working for. A role is valuable exactly to the extent it's SPECIFIC. "You're a professional", "like a genius" is placebo (the model doesn't get smarter from flattery). "You're a senior Python dev writing for juniors, need type hints and comments" genuinely changes the output.
2. Task — what to do (with a verb: summarize, extract, translate, classify…).
3. Input data — the text/data to process ← in delimiters/tags.
4. Examples (few-shot) — "input → expected answer" samples ← in `` tags.
5. Constraints / rules — what's forbidden, edge cases, "if X → answer Y", length, tone, audience.
6. Output format — JSON with a schema / list / markdown / plain text.

For agents, "role + rules + format" → in the system prompt; the specific request/data → in the user prompt.

The "altitude" of instructions

A system prompt should be at the right "altitude": not too prescriptive (brittle — breaks on any deviation from the scripted scenario) and not too vague (the model doesn't understand what's wanted). Start with a minimal prompt and add specifics as you find real failures during testing — rather than trying to anticipate everything up front. Organize into sections: background / instructions / tool guide / output format.

---

Few-shot (examples) — doing it right

Examples are one of the most reliable ways to control output format, tone, and structure (often stronger than rules in prose). But:

• 3–5 examples — the optimum for most tasks.
• Relevant — closely mirror your real case.
• Diverse — cover edge cases and vary enough that the model doesn't latch onto an unintended pattern (if every example starts with "Sure!" — the model will always start that way).
• Structured — each in ` (several in `), so the model distinguishes them from instructions.
• You can ask the model itself to rate your examples for relevance/diversity, or to generate more from a template.
• For few-shot with reasoning: show the reasoning inside `` tags in the examples — the model picks up the pattern.

---

Output-control techniques

• Positive instructions > negative ones. "Do it this way: …" / showing a correct example works better than "don't do it this way." If you see a specific unwanted pattern, it's better to show a positive example of the desired behavior than to forbid it.
• Length/verbosity. Modern models self-calibrate length to task complexity (shorter on simple, longer on open-ended). Need a specific style/length — spell it out ("keep answers concise, no inessential context, minimal examples"). ⚠️ Models are bad at counting words/characters — "no more than 50 words" works as a hint, not a hard limit; guarantee exact length in code (truncate/check).
• No preamble. If you don't want "Sure! Here's…" / "Based on…", write: "Answer directly, no preamble. Don't start with phrases like 'Here is', 'Based on'." (This replaces the old prefill trick — see below.) If preamble slips through occasionally — trim it in post-processing.
• A concrete threshold instead of qualitative words. Not "output the important errors" but "output the errors that could cause incorrect behavior, a failing test, or a misleading result; skip purely stylistic nitpicks." The model interprets "important" and "significant" its own way.
• Prompt style ≈ output style. Want less markdown in the answer — remove markdown from the prompt. Want a particular format — write the prompt in that same format.
• Prefill (seeding the start of the assistant's response) is a legacy trick. "Seeding" the start of the assistant's reply ({"role":"assistant","content":"{"} → the model continues the JSON) is not supported on current Claude models (the API returns 400). Use direct instructions, structured outputs, or strict tool use instead.
• On CAPS / markdown / emoji / repetition as "amplifiers" — what actually works and what's noise: see PATTERNS.md § "Prompt formatting."
• New models are literal: they don't generalize a rule for you — state the scope explicitly ("to all sections, not just the first"). Details: see PATTERNS.md.

---

Modern standards (2026) — what's missing from or thin in the 2023 course

• System / User / Assistant. system — persona + rules, applies to the whole dialogue, "heavier weighted" (more injection-resistant), invisible to the user. user — the question/data. assistant — the model's replies in history. The course's get_completion puts everything in user for simplicity — don't do that in prod.
• Structured Outputs. Before: "ask for JSON and hope." Now both vendors guarantee schema-valid JSON natively: Anthropic — output_config.format with {"type": "json_schema", "schema": …} (GA; supported on all current models — Sonnet 4.5+, Opus 4.5–4.8, the Claude 5 family) plus strict: true on tools to validate tool-call arguments; OpenAI — response_format (Chat Completions) / text.format (Responses API). Always preferable to "just asking for JSON."
• Tool use / function calling. The model returns not text but a request to call a function with arguments; you execute it, return the result, and the model continues. The foundation of agents. See "Tool design."
• Reasoning models — see PATTERNS.md § "Literalness and reasoning."
• Prompt caching. Large unchanging parts of the prompt (system, long context, tools) are cached by the provider — cheaper and faster. Put stable content at the start of the prompt, changeable content at the end.
• XML markup — the standard for complex/production prompts.
• Long context windows (200k–1M vs the former 4–8k) — changes the approach: sometimes it's simpler to drop in the whole document than to build RAG. But: "lost in the middle" — put long data at the start of the prompt, above the request/instructions/examples; keep the important bits at the start and end.
• Multimodality — images (and more) as input.
• Streaming — the answer token by token; essential for chat UX.
• "Context engineering" — the modern umbrella term (see the dedicated section): not just the prompt text but what/how we put into context. Prompt engineering is a part of it.
• Evals as the foundation of the work. The "guess the incantation" craft is dead; the lever is an eval set + decomposition + structured outputs, with automated optimization (DSPy) when needed. Details: see EVAL-JUDGE.md.

---

Tool design for agents

• A tool description is a mini-prompt. What it does, when to call it, what goes in the parameters — write it as carefully as a system prompt. Instructions specific to one tool ("before create_event, check the slot") live in its description, not buried in the general system prompt.
• Keep the tool set focused and non-overlapping. Overlapping tools create ambiguous choice points → the model gets confused. No "bloated" functionality.
• Return token-efficiently. A tool shouldn't dump a megabyte into context — return the essence.
• Parallel calls. Call independent tools in parallel (reading 3 files = 3 calls at once). Dependent ones (where one's parameter depends on another's result) — sequentially. Never guess missing parameters.
• Triggering. Not "by default, use [tool]" / "when in doubt, use it" — on new models this causes over-calling. Better: "use [tool] when it will improve your understanding of the task."

---

Context engineering for agents (long-horizon)

Context is a finite resource with diminishing returns ("context rot": the more tokens, the worse the model holds attention — like human working memory). The goal is the smallest set of high-signal tokens that maximizes the desired result. For long/multi-step tasks:

• Compaction (history compression). When context approaches the limit — summarize the history, extract what's critical, and start a fresh window from that distillation.
• Structured notes. The agent writes progress notes to an external file (outside context) and pulls them back in later — continuity across sessions. For status data (tests, task statuses) — JSON; for general progress — free text; git is an excellent "state journal" with checkpoints.
• Sub-agents. Narrowly specialized agents do focused work and return a compressed summary to the main agent, not their entire trace. Careful: don't spawn sub-agents where a direct grep/single step suffices.
• Hybrid retrieval. Load some data up front (speed), and let the agent fetch the rest on the fly with tools (just-in-time).
• If the harness can do compaction / file persistence (like Claude Code) — tell the model so in the prompt, otherwise it may "rush to finish" near the context limit.
• Prompt bloated and being ignored? That's the wrong shape, not the wrong wording: break the monolith into workflow steps, move guarantee-rules into code, put tool instructions into their descriptions. Full breakdown (6 remedies): see PATTERNS.md § "The prompt is bloated."

---

"Is the prompt ready?" checklist

• [ ] Is the task phrased with a verb, unambiguously?
• [ ] Is all extraneous data in delimiters/tags?
• [ ] Is the scope of each rule stated explicitly (the model won't generalize on its own)?
• [ ] Are edge cases spelled out ("if … → …")?
• [ ] Is the output format specified explicitly (and if it feeds code — Structured Outputs)?
• [ ] Are qualitative words ("important") replaced with a concrete threshold?
• [ ] Complex task → is there reasoning/steps BEFORE the answer? Is the step order sensible? Is there a self-check at the end?
• [ ] Role/rules in system, data in user?
• [ ] Few-shot: 3–5 examples, relevant, diverse, in `` tags, with no accidental pattern?
• [ ] Long data at the start of the prompt? Stable parts at the start (for caching)?
• [ ] For an agent: are tools focused/non-overlapping, are tool-specific instructions in the tool description?
• [ ] Is the prompt not bloated? If it is — what can move into code / a separate step? (see PATTERNS.md)

Anti-patterns

• "You're a brilliant world-class expert, answer perfectly" — placebo, no effect.
• Asking for a complex answer straight away, without reasoning — a hasty (often wrong) response.
• User data without delimiters — a prompt-injection risk and instruction/data confusion.
• "Return JSON" without a schema, when Structured Outputs exist — needless unreliability.
• Duplicating "think step by step" for a reasoning model — it interferes; and effort=max on a simple task — overthinking + wasted tokens.
• Self-refine as "look at your answer and agree" — you need an independent re-run.
• Negative instructions where a positive example would work.
• Qualitative terms ("important", "significant") without a defined threshold.
• Counting on the model to "generalize" an instruction to all cases — new models are literal, state the scope.
• Asking the model to count words/characters exactly and relying on it — it can't; guarantee it in code.
• "By default, use [tool]" / "when in doubt, use it" — over-calling on new models.
• Changing a prompt "blind" without a test set of inputs — that's not debugging, it's guessing (the eval loop: see EVAL-JUDGE.md).
• One mega-prompt for a complex multi-step task — see PATTERNS.md § "The prompt is bloated."
• Cargo-cult incantations ("take a deep breath", "I'll tip you $200", "my career depends on this", "you're the most brilliant expert") — noise on modern models; the strength is in structured outputs / evals / decomposition.
• CAPS by the paragraph / ❌⚠️🔥 scattered around / repeating one prohibition in five places — visual

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: kirill-sviridov
• Source: kirill-sviridov/agent-dev-skills
• License: MIT

Install and usage instructions live in the source repository linked above.