Prompt Engineering

---
name: prompt-engineering
domain: meta
description: |
  [METHODOLOGY] Guide for writing effective prompts for LLMs based on
  Anthropic + OpenAI 2025-2026 guidelines. Pure reference — invoked via slash
  command or explicit Skill tool call, not auto-triggered by keywords.
---

# Prompt Engineering for Reasoning Models

Based on Anthropic and OpenAI guidelines (2025-2026). Every principle here has a motivation — when you understand WHY something works, you follow it more reliably.

## Core Principles

### The model is already smart

Add only what the model lacks: domain context, constraints, success criteria. Every sentence should justify its token cost. The context window is a shared resource — prompts compete for attention with conversation history, tool outputs, and the model's own reasoning.

### Clarity over cleverness

Most prompt failures stem from ambiguity, not model limitations. Test: show the prompt to a colleague with no context. If they're confused about what to do, the model will be too.

### Motivation over emphasis

Explain WHY a rule matters. One motivated sentence outperforms ten capitalized words.

When every instruction screams for attention (ALL CAPS, "CRITICAL", "NEVER", "ALWAYS", "MUST"), nothing stands out. Emphasis words signal a poorly written instruction — rewrite it instead of raising the volume. Over-thorough language ("Be THOROUGH", "Make sure you have the FULL picture") also hurts — it inflates token cost without adding signal.

```
Before:
  CRITICAL: You MUST ALWAYS validate input. NEVER skip validation.
  IMPORTANT: ALWAYS check for edge cases. This is MANDATORY.

After:
  Validate all input before processing.
  Reason: unvalidated input causes pipeline crashes in production.
```

### Positive framing

State what you want, not what to avoid. Models follow positive instructions more reliably. Long prohibition lists get ignored — they add tokens without adding clarity.

```
Before:
  Don't use bullet points. Never include code examples.
  Avoid long explanations. Don't use jargon.

After:
  Write in prose paragraphs, 2-3 sentences each.
  Use plain language accessible to non-technical readers.
```

### Examples over rules

1-3 canonical examples transfer knowledge more efficiently than paragraphs of description. Show the desired output — let the model generalize from the pattern.

### Compress

Remove filler ("could you please", "I would like you to", "make sure to"). Shorter prompts often perform equally well or better — less noise means stronger signal per token.

### Degrees of freedom

Match specificity to the task's fragility. Over-specifying creative tasks stifles the model's reasoning. Under-specifying fragile tasks leads to format errors and broken parsing.

Fragile tasks (parsing specific formats, following exact protocols): prescribe steps.
Creative tasks (writing, analysis, design): give constraints and let the model find its path.

### High-level guidance

Provide constraints and success criteria rather than step-by-step micro-instructions. The model's own reasoning often exceeds prescriptive procedures. Describe WHAT success looks like — the model figures out HOW.

## Techniques That Work

### Context over decoration

Provide concrete context (audience, use case, constraints) instead of decorative phrasing. The model gains nothing from flattery.

```
Before:
  You are an incredibly brilliant and talented expert programmer
  who writes the most amazing code in the world. Please write
  a function that validates emails.

After:
  Write an email validation function.
  Context: TypeScript, used in a signup form, must handle
  international domains. Return {valid: boolean, reason: string}.
```

### Structure with XML tags

Separate instructions, data, and examples with XML tags. This prevents the model from confusing context with instructions. Consistent tag names make handoffs between chained prompts clean.

```
Before:
  Here's some customer feedback. Also, the format should be
  JSON. And please analyze sentiment. The feedback is:
  "Great product but shipping was slow."

After:
  <instructions>
  Analyze sentiment. Output JSON: {text, sentiment, confidence}.
  </instructions>
  <data>
  Great product but shipping was slow.
  </data>
```

### Examples over explanations

Instead of describing the desired output format in paragraphs, show 1-3 examples. The model generalizes from patterns faster than from rules.

```
Before:
  When summarizing articles, create a summary that includes
  the main topic as a short phrase, then 2-3 key points as
  bullet items, then a one-sentence practical takeaway.

After:
  Summarize articles in this format:

  <example>
  Topic: Remote work productivity
  - Async communication reduces meetings by 40%
  - Written documentation improves onboarding speed
  Takeaway: Teams that default to async work ship faster.
  </example>
```

### Prompt chaining over mega-prompts

Break complex tasks into focused steps. Each step gets the model's full attention. A chain of 3 focused prompts outperforms one overloaded prompt — empirically shown to reduce error rates.

```
Before (single mega-prompt):
  Analyze this contract for risks, then draft an email
  to the vendor with concerns, then review for tone.

After (3-step chain):
  Step 1: Analyze <contract> for risks. Output in <risks> tags.
  Step 2: Using <risks>, draft vendor email with proposed changes.
  Step 3: Review <email> for tone. Grade A-F with suggestions.
```

### Define success criteria

Tell the model what good output looks like — not just what to do. Include format, length, audience, and evaluation criteria.

```
Before:
  Write a good product description.

After:
  Write a product description for noise-canceling headphones.
  Audience: Tech-savvy millennials on a comparison shopping site.
  Format: 80-120 words, no superlatives, focus on specs and
  use cases. End with one differentiating fact vs. competitors.
```

## Refinement

How to improve a prompt that isn't working well:

1. **Draft** a first version focused on context and success criteria
2. **Test** against 3-5 representative inputs (include edge cases)
3. **Observe** the output — collect specific problems, not vague impressions
4. **Diagnose** each problem: is it ambiguity? missing context? conflicting instructions? wrong format?
5. **Plan changes**: map each problem to a specific edit (what failed → why → what to change)
6. **Refine** with targeted edits — change one thing at a time, test each separately
7. **Metaprompt**: show the model a problematic output and ask "What in this prompt causes this behavior? Suggest a revision."

### When to add instructions vs. examples

| Problem | Fix |
|---------|-----|
| Model misunderstands the task | Add context (audience, use case, constraints) |
| Output missing required sections | Add an example showing all sections |
| Wrong format or style | Add 1-2 output examples |
| Model uses wrong context | Restructure with XML tags to separate data from instructions |
| Contradictory behavior | Audit prompt for conflicting rules and resolve them |

## Quick Reference

| Instead of | Do this | Why |
|------------|---------|-----|
| Emphasis words (CAPS, "NEVER", "ALWAYS") | One sentence explaining motivation | When everything screams, nothing stands out |
| Lists of prohibitions | State desired behavior | Positive framing is followed more reliably |
| "Act as a world-class expert..." | Provide context + success criteria | Flattery adds tokens without adding signal |
| One mega-prompt with many tasks | Chain of 3-4 focused prompts | Each step gets full model attention |
| Filler ("please", "make sure", "I want you to") | Direct instruction | Fewer tokens = less noise |
| Paragraphs describing format | 1-3 examples of desired output | Models generalize from examples faster than from rules |
| Step-by-step micro-instructions | Constraints + success criteria | Model's own reasoning exceeds prescriptive procedures |