| name | prompt-engineering |
|---|---|
| description | Systematic expertise for crafting, analyzing, and improving LLM prompts. Applies to ad-hoc prompts, stored prompt templates, agent system prompts, persona definitions, and prompt evaluation. Activate when the user needs to create, improve, or debug a prompt; is building an agent profile or system prompt; asks "how do I ask AI to...", "create a prompt for...", or "why isn't my prompt working"; or when a prompt is vague, ambiguous, or underperforming. |
Foundational knowledge for writing effective LLM prompts. Covers principles, techniques, writing rules, and common pitfalls. Use this skill when you need to:
- Write a new prompt from scratch (ad-hoc instruction, reusable template, or system prompt)
- Improve or debug an existing prompt that produces poor or inconsistent results
- Build or refine an agent profile or persona definition
- Analyze why a prompt is not working and diagnose the root cause
- Review a prompt for clarity, specificity, and completeness
- Clarify the goal — What exact outcome does the prompt need to produce? For whom? In what context?
- Identify prompt type — Ad-hoc instruction, system/agent prompt, template with variables, conversational turn?
- Draft — Apply the principles and techniques below to construct the prompt
- Evaluate — Check against the writing rules and pitfalls list
- Refine — Iterate: tighten language, add missing constraints, test edge cases
When improving an existing prompt, start with diagnosis: identify what's wrong (vague instructions? missing constraints? conflicting rules? no output format?) before rewriting.
- Simplicity wins. Shorter prompts that work beat longer prompts that might. Start with the simplest version and add complexity only when results are not good enough.
- One goal per prompt. Each prompt should pursue a single clear objective. Mixing unrelated requests degrades quality on all of them.
- Be specific. Replace vague words with concrete requirements. Quantify where possible. Name the audience.
- Provide context and motivation. Tell the model what it cannot infer: domain, audience, purpose. Explain why the task matters — models follow instructions better when they understand the reasoning.
- Show, don't just tell. When the desired behavior is hard to describe in words, provide examples. Input/output demonstrations are often more effective than abstract instructions.
- Structure the prompt. Use headings, sections, delimiters, and lists to organize complex prompts. Separate instructions from data. The model should be able to tell at a glance what it needs to do, what it has to work with, and what the output should look like.
- Specify output format. Define the expected shape of the response — even if just "plain prose, 2-3 paragraphs". Without it, results vary unpredictably.
- Include guardrails. State what the model should NOT do. A dedicated constraints or don'ts section prevents known failure modes.
- Decompose complex tasks. When a task has a clear workflow or multiple stages, break it into numbered steps within the prompt. Each step should be independently verifiable.
- Ask the model to self-check. For correctness-critical output, instruct the model to verify its own work — critique, list mistakes, then fix. This catches errors the first pass misses.
- Balance constraints. A prompt can be over-constrained (too rigid, model cannot maneuver) or under-constrained (too loose, output varies wildly). Aim for the minimum constraints that produce consistent results.
- Teach the model when to refuse. Give explicit permission to say it does not know, ask for clarification, or decline. Specify what to do when information is missing or input is out of scope.
- Define success criteria. Tell the model what good output looks like — quality dimensions, evaluation criteria, or a checklist it should verify against before responding.
Not an exhaustive list. These are common, well-established techniques. They are composable — combine as needed.
Direct instruction with no examples. Start here — add complexity only when zero-shot fails.
Use when: The task is well-defined and the model likely understands it without demonstration (summarization, translation, simple classification, reformatting).
Provide 2-5 input/output examples before the actual task.
Use when: You need specific formatting, consistent style, or patterns that are easier to show than describe.
Keep example format identical to expected output format.
More examples = better pattern matching, but costs tokens — find the minimum effective set.
If the model copies too literally from examples, reduce count or increase diversity.
Ask the model to reason through intermediate steps before answering.
Use when: Multi-step reasoning, math, logic, debugging, analysis, or any task where jumping to the answer produces errors.
Trigger with "think step by step" or by providing a numbered reasoning structure.
Break a complex task into numbered subtasks, each with its own clear instruction.
Use when: A single prompt tries to do too much and quality degrades.
Assign the model a specific expert identity.
Use when: The task benefits from domain-specific language, reasoning style, or perspective. "You are a senior security auditor" produces different analysis than "You are a junior developer".
Watch out: Role alone does not guarantee expertise — pair it with specific instructions and constraints.
Explicitly define the shape of the response (JSON, table, YAML, bullet list, specific template).
Use when: Output feeds into other systems, needs to be parsed, or must follow a specific format for humans.
Rules:
- Define the exact schema (field names, types, allowed values)
- Show one example of valid output
- State return only valid JSON, no additional text when strictness matters
For long document tasks, ask the model to extract and quote relevant passages before carrying out the actual task.
Use when: Working with long documents where the model needs to cut through noise. Anchors reasoning to source material and reduces hallucinations.
Ask the model to validate its own output: generate, then verify, then correct.
Use when: Correctness-critical tasks (code generation, data extraction, legal/compliance text). Can be phrased as "list possible mistakes in your answer, then fix them".
Generate a draft, then critique it, then revise based on the critique.
Use when: You want to improve factuality, style, or completeness without external feedback. The critique step surfaces issues the initial generation missed.
Ask the model to restate the requirements or constraints before solving the task.
Use when: The task has strict output rules (format, word count, schema, multiple constraints). Restating forces the model to internalize constraints before diving into execution.
Include a quality checklist directly in the prompt and instruct the model to verify its output against it before responding.
Use when: The task has multiple quality dimensions (accuracy, tone, format, completeness) and you want the model to self-enforce them. Especially effective combined with critic-revise or self-check.
- State the goal in one sentence. If you cannot, the prompt likely lacks focus.
- Replace vague words with precise ones. Instead of "write a good summary", say "write a 2-sentence summary covering the main finding and its business impact".
- Quantify when possible. Instead of "keep it short", say "maximum 150 words". Instead of "list a few", say "list exactly 5".
- Name the audience. Instead of "explain X", say "explain X to a backend developer unfamiliar with GraphQL".
- Prefer saying what TO DO over what NOT to do. Models follow positive instructions more reliably than prohibitions.
- Instead of "don't make up facts", say "base every claim on the provided source material; if information is missing, say so".
- Do include explicit guardrails. Explicit prohibitions help prevent known failure modes. The point is not to avoid negative instructions entirely, but to make sure the prompt is not only negatives — pair every prohibition with a positive alternative when possible.
- One instruction per sentence. Long compound sentences create parsing ambiguity.
- Define terms the model might interpret differently than you intend. What does "technical" mean here? Senior-level? With code examples? Including implementation details?
- Front-load critical instructions. Models attend most to the beginning and end of prompts (primacy/recency effect).
- Place long-form data above the query. Documents, context, and RAG results go at the top. Instructions, question, and examples go below. The model attends more to what comes right before it needs to answer.
- Separate data from instructions. Never mix the task description with the input in the same block.
- Use structural delimiters — XML tags (
<input>,<rules>,<output_format>), markdown headers, numbered sections, or triple-dash separators. This reduces instruction bleed between sections. XML tags are particularly effective — models are trained to recognize them. - Group related instructions under clear headings or labels. Flat prose walls bury rules.
- Label variable parts clearly in templates:
{{user_input}},[DOCUMENT].
- Every sentence should earn its place. Cut filler, caveats, and pleasantries. Instead of "I'd like you to please help me with summarizing", just say "Summarize".
- Do not repeat instructions in different phrasings hoping the model gets it. Say it once, clearly.
- Use references instead of inlining large data. Say "given the document above" instead of repeating it.
- Typos and grammar matter. Models are trained on patterns — sloppy input signals sloppy output. A well-written prompt is more likely to produce well-written results.
An agent profile defines "who the agent is and how it behaves" across all interactions. A prompt defines "what the agent should do right now".
Agent profile defines behavior across many tasks, not a single task. The profile must be general enough to handle diverse user requests yet specific enough to produce consistent behavior.
Every instruction in the profile is executed repeatedly, not once. This means token cost compounds and conflicting rules surface over time, not immediately.
Agent profile (stable across turns):
- Identity, expertise, tone, communication style
- Scope: what is in and out of bounds
- Hard rules, guardrails, compliance constraints
- Failure modes: what to do when uncertain, when input is out of scope, when rules conflict
- Tool usage policies
- Default output format and style
Prompt (per-task):
- The specific task and its input data
- Task-specific context, examples, constraints
- Output format overrides for this particular request
- Success criteria for this specific output
| Pitfall | Problem | Fix |
|---|---|---|
| Vague qualifiers | "Write a good/better/appropriate X" — good is undefined | Define what good means: criteria, metrics, examples |
| Negative-only constraints | "Don't use jargon, don't be verbose, don't assume..." | Reframe as positive: "use plain language, be concise, ask for clarification" |
| Instruction overload | 30+ rules crammed into one prompt — model drops some | Prioritize ruthlessly. Cut or merge low-value rules. |
| Conflicting instructions | "Be concise" + "explain thoroughly" in the same prompt | Pick one, or scope each to specific situations |
| Missing output format | No format specified, model guesses differently each time | Always specify format, even if it is just "plain prose, 2-3 paragraphs" |
| Example mismatch | Few-shot examples don't match real input distribution | Use realistic examples that cover the actual range of inputs |
| Premature complexity | Over-engineering the prompt before trying a simpler version first | Start with the simplest prompt that could work. Add structure only when the simple version fails. |
| Multiple goals in one prompt | Model tries to address everything, quality drops across the board | One clear goal per prompt. Split compound requests. |
| Ignoring ordering | Critical rules buried in the middle of a long prompt | Front-load important instructions. Use headers to make them scannable. |
| No uncertainty escape hatch | Model forced to always produce an answer, even when it should not | Give explicit permission to say "I do not know" or ask for clarification |
| Sloppy prompt text | Typos and grammar errors signal low quality, model mirrors it | Proofread prompts as carefully as production code |