# Prompt Engineering > Rules and techniques for writing system/user prompts in LLM applications and agents — prompt anatomy, few-shot, XML-tag markup, output control, structured outputs, tool use, reasoning models, context engineering, prompt debugging/decomposition. Use when designing, writing, or debugging prompts for an AI agent or LLM feature. - **Type:** Skill - **Install:** `agentstack add skill-kirill-sviridov-agent-dev-skills-prompt-engineering` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [kirill-sviridov](https://agentstack.voostack.com/s/kirill-sviridov) - **Installs:** 0 - **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [kirill-sviridov](https://github.com/kirill-sviridov) - **Source:** https://github.com/kirill-sviridov/agent-dev-skills/tree/main/plugins/agent-dev-skills/skills/prompt-engineering ## Install ```sh agentstack add skill-kirill-sviridov-agent-dev-skills-prompt-engineering ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # 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](https://github.com/kirill-sviridov) - **Source:** [kirill-sviridov/agent-dev-skills](https://github.com/kirill-sviridov/agent-dev-skills) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-kirill-sviridov-agent-dev-skills-prompt-engineering - Seller: https://agentstack.voostack.com/s/kirill-sviridov - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.