ai-prompt-engineering

---
name: ai-prompt-engineering
description: Prompt engineering for production LLMs — structured outputs, evals, RAG, tool workflows, multimodal prompting, and safety. Use when designing, debugging, or shipping prompts.
license: MIT
---

# Prompt Engineering — Operational Skill

Use this skill for production prompt design: schema-first outputs, tool and RAG prompts, prompt hardening, evals, and release workflows. Keep it operational. If the main problem is architecture, retrieval quality, deployment, or inference cost, route to the deeper adjacent skill.

## ASCII Flow

```text
prompt job
  |
  v
pattern choice
  structured output | extraction | RAG | tool use | rewrite | classify | release
  |
  v
prompt contract
  inputs + role/task + context rules + output schema + refusal/failure behavior
  |
  v
validation
  schema checks + citation/tool checks + eval cases + regression gate
  |
  v
released prompt
  versioned artifact + rollout notes + rollback path
```

## When to Use This Skill

- designing or refactoring prompts for production LLM systems
- structured outputs, extraction schemas, or response contracts
- prompt debugging, prompt hardening, or prompt review
- prompt evals, regression suites, and rollout criteria
- tool-use or RAG prompt patterns
- multimodal prompts for image, document, audio, or video inputs

## Route Elsewhere

- agent architecture and orchestration -> [ai-agents](../ai-agents/SKILL.md)
- retrieval quality and chunking -> [ai-rag](../ai-rag/SKILL.md)
- broader LLM lifecycle and model strategy -> [ai-llm](../ai-llm/SKILL.md)
- inference latency and cost optimization -> [ai-llm-inference](../ai-llm-inference/SKILL.md)
- deployment, monitoring, and platform controls -> [ai-mlops](../ai-mlops/SKILL.md)

---

## Quick Start

1. Classify the prompt job: structured output, extraction, RAG, tool use, rewrite, classification, or release workflow.
2. Start from a template or provider-native prompt feature rather than writing from scratch.
3. Add explicit output and refusal rules.
4. Add validation: schema checks, citation checks, post-tool checks, and failure handling.
5. Add evals before calling the prompt production-ready.

## Quick Reference

- Pattern selection -> `## Pattern Chooser`
- Reusable prompt shapes -> `## Minimal Prompt Skeletons`
- Release hardening -> `## Production Checklist`
- Deeper references and templates -> `## Navigation`

## Cross-Model Notes

- Prefer provider-native structured outputs, registries, evals, and prompt tooling where available.
- Ask for final answers, checks, or brief justification, not visible chain-of-thought.
- Treat retrieved context, tool outputs, and user documents as untrusted data.
- Run only truly independent tool calls in parallel; keep writes and validation serialized.
- Keep state compact and resilient to context compression.

---

## Pattern Chooser

| Need | Pattern | Core Controls |
|------|---------|---------------|
| Machine-parseable output | Structured output | schema, JSON-only response, validation |
| Deterministic field extraction | Extractor | missing -> `null`, no transformation, exact schema |
| Retrieved factual answering | RAG workflow | relevance check, citation requirement, explicit missing-info behavior |
| Hidden reasoning | Private reasoning / native thinking | final answer only, no exposed chain-of-thought |
| Tool use | Tool or agent planner | plan, tool gating, validation after each call |
| Text transformation | Rewrite and constrain | meaning preservation, style and format rules |
| Classification or routing | Decision tree | mutually exclusive branches, stable output format |
| Prompt release | Prompt ops | versioning, eval gates, rollback path |
| Choosing prompt vs RAG vs fine-tune vs distill | Escalation decision | Prompt → RAG (knowledge gap) → Fine-tune (volume + stable task) → Distill (cost at scale). See [references/prompt-vs-finetune.md](references/prompt-vs-finetune.md). |

## Workflow

1. Pick the closest pattern.
2. Load the smallest useful template or reference.
3. Write the prompt contract:
   - task
   - allowed inputs and tools
   - output schema or format
   - refusal or missing-data behavior
4. Add validators and adversarial tests.
5. Verify current provider behavior before making claims about "best" settings or features.

---

## Minimal Prompt Skeletons

### Output contract

```text
TASK:
{{one_sentence_task}}

INPUT:
{{input_data}}

RULES:
- Use only INPUT and approved tool outputs.
- Do not invent facts.
- Missing required information -> say what is missing.
- Keep reasoning hidden.
- Follow OUTPUT FORMAT exactly.

OUTPUT FORMAT:
{{schema_or_format_spec}}
```

### Tool or agent prompt

```text
AVAILABLE TOOLS:
{{tool_names_or_signatures}}

WORKFLOW:
- Make a short plan.
- Call tools only when needed.
- Validate each tool result before using it.
- Run independent reads in parallel only if the environment supports it.
```

### Grounded RAG prompt

```text
RETRIEVED CONTEXT:
{{chunks_with_ids}}

RULES:
- Use only retrieved context for factual claims.
- Cite chunk ids for each claim.
- If evidence is missing, say what is missing.
```

---

## Production Checklist

- [references/quality-checklists.md](references/quality-checklists.md) for pre-release validation
- [references/production-guidelines.md](references/production-guidelines.md) for rollout, guardrails, and regression policy
- [references/provider-native-prompt-ops.md](references/provider-native-prompt-ops.md) for current provider tooling
- [references/prompt-security-defense.md](references/prompt-security-defense.md) for injection, tool abuse, and approval gates

## Context Engineering

Prompt quality depends on the whole input pipeline, not just instruction wording.

- prioritize the highest-signal context first
- compress history and tool output aggressively
- separate instructions, user data, and retrieved context with clear delimiters
- adapt context size to task complexity instead of dumping everything into the window

Route deep retrieval or memory design work to [ai-rag](../ai-rag/SKILL.md) or `ai-context-layer`.

---

## Core Principles

- Define the contract before optimizing style.
- Make determinism explicit with schemas, constrained decoding, and post-generation validation.
- Treat prompt length and output caps as latency and cost controls.
- Use evals plus regression gates instead of intuition.
- Security means instruction-data separation, output validation, and tool-risk controls.

## Do / Avoid

**Do**

- keep prompts modular and versioned
- centralize shared policies and schemas
- block releases on prompt regressions
- use provider-native prompt ops where they simplify maintenance

**Avoid**

- prompt sprawl with many near-duplicates
- brittle multi-step chains without validation
- mixing product copy, policy, and control logic in one long prompt
- asking for visible chain-of-thought

## Known Traps

- Designing a prompt contract around one specific frontier model as if its availability is guaranteed. Provider-side safety incidents, export-control actions, or capacity constraints can suspend or fall back a model family with no notice; a production prompt contract must already specify what happens when the primary model is unavailable, not just what happens when it refuses.
- Attributing a refusal-rate or format-compliance regression to "the prompt got worse" without first checking whether the provider shipped a safety-classifier or model update in the same window.
- Treating the prompt text itself as the whole system while validators, retrieval shaping, and tool-output checks remain undefined.
- Mixing instructions, retrieved context, and user data without strong delimiters, then misdiagnosing injection or policy failures as "model quality" issues.
- Shipping prompt changes without a regression set for the exact schema, citations, refusal behavior, and edge cases that matter.
- Creating many slightly different prompts for the same job instead of maintaining one reusable pattern with explicit variants.
- Asking for verbose exposed reasoning when the real requirement is a correct answer plus a narrow audit trail.

## Common Anti-Patterns

- Using prompt length as a proxy for quality instead of tightening the output contract and validation path.
- Hardening prompts against every failure mode in prose while leaving post-generation validation weak or absent.
- Letting tool instructions, style guidance, product copy, and policy constraints accumulate in one giant prompt instead of modularizing them.
- Treating provider-specific behavior as universal without rechecking current official docs and runtime constraints.

---

## Navigation

### Core references

- [references/core-patterns.md](references/core-patterns.md)
- [references/best-practices-core.md](references/best-practices-core.md)
- [references/production-guidelines.md](references/production-guidelines.md)
- [references/quality-checklists.md](references/quality-checklists.md)
- [references/provider-native-prompt-ops.md](references/provider-native-prompt-ops.md)
- [references/prompt-security-defense.md](references/prompt-security-defense.md)
- [references/domain-specific-patterns.md](references/domain-specific-patterns.md)

### Specialized references

- [references/extended-thinking-and-reasoning-models.md](references/extended-thinking-and-reasoning-models.md) — Claude Opus 4.7 adaptive thinking (budget_tokens removed), effort levels, task_budget, sampling-param removal, tokenizer note; GPT-5 / o-series reasoning_effort patterns
- [references/prompt-vs-finetune.md](references/prompt-vs-finetune.md) — Prompt → RAG → Fine-tune → Distill escalation decision ladder
- [references/rag-patterns.md](references/rag-patterns.md)
- [references/agent-patterns.md](references/agent-patterns.md)
- [references/extraction-patterns.md](references/extraction-patterns.md)
- [references/reasoning-patterns.md](references/reasoning-patterns.md)
- [references/multimodal-prompt-patterns.md](references/multimodal-prompt-patterns.md)
- [references/generative-media-prompt-patterns.md](references/generative-media-prompt-patterns.md) — Prompting generative image/video models (text-to-image persona, character-consistency edits, image-to-video, lip-sync): the shot-spec anatomy, model-pluggable dialects, copy-paste templates G1–G7
- [references/prompt-testing-ci-cd.md](references/prompt-testing-ci-cd.md)
- [references/additional-patterns.md](references/additional-patterns.md)
- [references/information-theory-applied.md](references/information-theory-applied.md) — Information-theory applied recipes for prompts: redundancy diet, MI few-shot selection, KL drift gate.

### Scripts

| Script | Purpose |
|--------|---------|
| `scripts/prompt_regression_runner.py` | Run a JSONL prompt regression suite (variant_id, prompt, golden_substrings, schema). Groups results by variant. Validates pre-collected outputs only. |

### Templates and data

- [assets/quick/template-quick.md](assets/quick/template-quick.md)
- [assets/standard/template-standard.md](assets/standard/template-standard.md)
- [assets/standard/template-agent.md](assets/standard/template-agent.md)
- [assets/standard/template-rag.md](assets/standard/template-rag.md)
- [assets/standard/template-cot.md](assets/standard/template-cot.md)
- [assets/standard/template-json-extractor.md](assets/standard/template-json-extractor.md)
- [assets/eval/prompt-eval-template.md](assets/eval/prompt-eval-template.md)
- [data/sources.json](data/sources.json)

## Related Skills

- [ai-agents](../ai-agents/SKILL.md)
- [ai-rag](../ai-rag/SKILL.md)
- [ai-llm](../ai-llm/SKILL.md)
- [ai-mlops](../ai-mlops/SKILL.md)
- [dev-api-design](../dev-api-design/SKILL.md)
- [software-backend](../software-backend/SKILL.md)

## Fact-Checking

- Known bugs, regressions, framework/compiler/runtime footguns, and version-specific crash or workaround guidance must be verified against current primary web sources before being treated as current fact.
- Verify current provider capabilities, prompt-tooling behavior, and official guidance before final answers.
- Prefer primary docs and current standards when the answer depends on the latest model or platform behavior.
- If web access is unavailable, avoid presenting prompt recommendations as definitively current.

## Learnings Loop

Before applying this skill on a non-trivial task, read `learnings.consolidated.md` in this directory (and `learnings.md` if present).

After applying it, if you encountered a pattern worth remembering, a mistake worth preventing, or a domain fact that surprised you, append one dated bullet to `learnings.md` via `agents-skills-feedback-loop/scripts/append_learning.py`. Do not modify `SKILL.md` itself.