Prompt Engineering

Treat prompts as small behavioral specs. Improve them by naming the job, testing the behavior, changing one important thing at a time, and preserving the prompt's operating context.

Core Workflow

1. Scope the prompt job.

Identify the target model or provider, audience, runtime surface, inputs, tools, output contract, constraints, and where the prompt will live. If the prompt belongs to a repo, inspect existing prompts, schemas, examples, tool definitions, evals, logs, and docs before asking avoidable questions.

1. Define success before rewriting.

State the desired behavior, hard requirements, acceptable variation, known failure modes, and evidence that would prove the prompt improved. If success is vague, turn it into 3-7 concrete cases before editing.

1. Choose the lightest pattern that fits.

Use direct instructions for simple tasks, structured sections for context control, few-shot examples for format or judgment calibration, schemas for machine-readable output, tool-use instructions for action boundaries, and repetition only when the model repeatedly drops critical constraints.

1. Draft with clean boundaries.

Put task, context, constraints, examples, tools, and output format in separate labeled sections. Delimit user-controlled or retrieved content clearly. Keep stable instructions before variable content when prompt caching, reuse, or maintainability matters.

1. Evaluate against reality.

Test representative, edge, adversarial, and regression cases. Compare outputs against explicit criteria instead of intuition. Record which failures changed and which remained.

1. Iterate deliberately.

Change one major variable at a time: instruction wording, context ordering, examples, output schema, tool contract, reasoning guidance, or model settings. Preserve the previous prompt and test cases until the new version wins on the target criteria.

1. Ship the prompt with evidence.

Return the final prompt, assumptions, changed behavior, eval cases, expected outputs or grading criteria, remaining risks, and any provider-specific settings the caller must preserve.

When To Use

• design, rewrite, debug, or review an LLM prompt
• create or revise a system prompt, developer prompt, tool-use prompt, few-shot

examples, structured-output instruction, grader prompt, or prompt eval set

• investigate why a prompt is unreliable, unsafe, too costly, too slow, or

mismatched to a target model

• optimize an existing prompt while preserving behavior and evidence

Not For

• model selection alone
• generic prose editing, README writing, marketing copy, or voice matching
• ordinary LLM integration code when the prompt behavior is not the main issue
• security review where data exposure, authorization, tenant isolation, or tool

abuse is the central risk

Compose With

• When the session provides an OpenAI docs skill or official-doc tool, use it

for OpenAI-specific current model, API, structured-output, tool-calling, reasoning, caching, or pricing behavior; otherwise verify official OpenAI docs directly. For other providers, verify current official provider docs when those details affect the prompt.

• Add a testing workflow when the main job is test strategy, evidence quality,

grading design, or acceptance criteria rather than prompt wording.

• Add a security workflow when prompt injection, hidden instruction leakage,

unsafe tool use, data exposure, or trust boundaries dominate the risk.

• Ownership rule with `context-engineering`: picking which facts, files,

or examples to load is context-engineering; deciding how to word the prompt, schema, or example is this skill. When work spans both, draft the context packet first, then own the prompt artifact here.

Prompt Design Rules

• Put the user's real task first; do not optimize a prompt before the objective

and failure mode are clear.

• Prefer explicit success criteria over broad "be better" instructions.
• Separate stable policy from per-request data and untrusted content. When the

prompt embeds retrieved or user-supplied material, fence it with explicit delimiters (e.g. <<untrusted:source>> ... <</untrusted>>, matching the context-engineering convention) and tag fact provenance with [src:code|user|tool|docs|memory|inferred] so downstream graders can detect leakage and instruction-override attempts.

• Specify output shape with examples or schemas when downstream code depends on

structure.

• Use examples that demonstrate decisions, not examples that merely repeat the

instruction.

• Include negative and boundary cases when failure would be costly, silent, or

hard to notice.

• Keep prompts short enough to maintain; move large context to retrieval,

tools, files, or references when possible.

• Verify current official provider guidance before making model- or API-specific

claims. Do not rely on memory for rapidly changing model behavior.

• Treat provider guidance as conditional. Load provider notes only when the

target model, API, or runtime surface makes them relevant.

Anti-Patterns

Prompts that look polished but fail in practice:

• Over-explanation: repeating the same instruction in three different

registers; the model averages them and weakens all three.

• Role stacking: layering "you are an expert X, careful Y, helpful Z"

before the task; clutter without behavioral effect.

• Examples that contradict instructions: when a few-shot demo violates a

rule, the example wins.

• Repetition without structure: restating constraints in prose instead of

putting them in a labeled section or schema.

• Vague quality bars: "be helpful", "be thorough", "use best practices"

without observable criteria.

• Schema mixed with freeform: asking for JSON and commentary; the model

picks one and the parser breaks.

Failure Diagnosis

When a prompt fails, classify the failure before rewriting:

• missing context: the model did not receive facts it needed
• ambiguous instruction: multiple reasonable outputs satisfy the prompt
• weak output contract: format, fields, or refusal behavior are underspecified
• bad examples: examples teach the wrong pattern or conflict with rules
• context collision: retrieved, user, or tool content overrides intent
• tool boundary drift: the model calls tools too early, too late, or with bad arguments
• model mismatch: the prompt assumes capabilities, settings, or reasoning behavior the model does not provide
• evaluation gap: the prompt looks better on anecdotes but fails representative cases

Output Shapes

Omit Original Prompt Or Version and Run Metadata for tiny rewrites when they are unavailable or not material.

For a prompt rewrite:

## Original Prompt Or Version
...

## Final Prompt
...

## What Changed
...

## Eval Cases
...

## Run Metadata
...

## Assumptions And Risks
...

For prompt debugging:

## Diagnosis
Failure category and evidence.

## Original Prompt Or Version
...

## Revision
Changed prompt section or full prompt.

## Validation
Cases that should pass, fail, or remain uncertain.

## Run Metadata
...

Reference Map

• patterns-and-provider-notes.md -

prompt patterns, source synthesis, and provider-specific notes.

• evaluation-flywheel.md - lightweight

prompt eval design, iteration, and grading workflow.

• trigger-evals.md - positive and negative

trigger checks for this skill.